接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でBitbucket Cmdlets を使用する例を示します。

Bitbucket への接続

ほとんどのクエリで、Workspace を設定する必要があります。唯一の例外はWorkspaces テーブルであり、このプロパティを設定する必要はありません。クエリを実行すると、Workspace を設定するために使用できるワークスペーススラッグのリストが提供されるためです。このテーブルをクエリするには、Schema を'Information' に設定し、クエリ'SELECT * FROM Workspaces' を実行します。

Schema を'Information' に設定すると、一般的な情報が表示されます。 Bitbucket に接続するには以下のパラメータを設定します。

Schema：ユーザー、リポジトリ、プロジェクトなど、ワークスペースについての一般的な情報を表示するには、これをInformation に設定します。そうでない場合は、クエリ対象のリポジトリやプロジェクトのスキーマを設定します。利用可能なスキーマのフルセットを取得するには、sys_schemas テーブルをクエリします。
Workspace：Workspaces テーブルをクエリしない場合は必須です。 Workspaces テーブルをクエリする場合は、このプロパティは必要ありません。このクエリは、Workspace を設定するために使用できるワークスペーススラッグの一覧のみを返すだけです。
Workspaces テーブルをクエリするには、Schema をInformation に設定して以下を実行します：
```
SELECT * FROM Workspace
```

Bitbucket への認証

Bitbucket はOAuth 認証のみサポートします。この認証を有効にするには、すべてのOAuth フローでカスタムOAuth アプリケーションを作成し、AuthScheme をOAuth に設定する必要があります。

以下のサブセクションでは、3つの一般的な認証フローでのBitbucket への認証について詳しく説明します。

カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成を参照してください。

Bitbucket で利用可能な接続文字列プロパティの全リストは、Connection を参照してください。

デスクトップアプリケーション

デスクトップアプリケーション経由で接続するには、OAuth アクセストークンを設定し、リフレッシュする必要があります。

OAuth アクセストークンの取得およびリフレッシュ

以下を設定して、接続してください。

OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたキー。
OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
CallbackURL：アプリケーションの登録時に定義されたCallback URL。通常はhttp://localhost:33333 に設定します。

接続すると、本製品はデフォルトブラウザでBitbucket のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。

アクセストークンの期限が切れたときは、本製品は自動でアクセストークンをリフレッシュします。

OAuth アクセストークンの自動リフレッシュ

本製品がOAuth アクセストークンを自動的にリフレッシュするようにするには：

はじめてデータに接続する前に、次の接続パラメータを設定します。
- InitiateOAuth：REFRESH。
- OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたキー。
- OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
- OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
- OAuthSettingsLocation：本製品がOAuth 値を保存する場所のパス。これは接続間で維持されます。
その後のデータ接続では、以下を設定します。
- InitiateOAuth
- OAuthSettingsLocation

OAuth アクセストークンの手動リフレッシュ：

OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。

ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
次の接続プロパティを設定します。
- OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレット。
RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。

OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

Note： AuthScheme がcode とclient のどちらに設定されているかによって、認証は認可コードまたはクライアントクレデンシャルグラントタイプのいずれかで実行されます。

以下のいずれかの方法で行います。

オプション1：OAuthVerifier 値を取得します。
オプション2：インターネットブラウザに対応したマシンに本製品をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

オプション1またはオプション2を実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品を設定します。

オプション1：Verifier code を取得および交換

Verifier コードを取得するには、次のようにOAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得します。

次のプロパティを設定します。
- InitiateOAuth：OFF。
- OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたキー。
- OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャは、カスタムOAuth アプリケーションが登録されたときに構築されたCallbackURL を返します。（カスタムOAuth アプリケーションの作成を参照してください。）

このURL をコピーして、新しいブラウザのタブに貼り付けます。
ログインして、本製品にアクセス許可を与えます。OAuth アプリケーションは、code というパラメータを付加したリダイレクトURI にリダイレクトします。このパラメータの値を控えておきます。OAuthVerifier 接続プロパティを設定するために、後で必要になります。
OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。

ヘッドレスマシンでは、OAuth 認証値を取得するには次のプロパティを設定します。
- InitiateOAuth：REFRESH。
- OAuthVerifier：verifier code（コールバックURL のcode パラメータの値）。
- OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたキー。
- OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
- OAuthSettingsLocation：暗号化されたOAuth 認証値を指定された場所に永続化。
接続をテストしてOAuth 設定ファイルを生成します。
これらのプロパティを再設定すると、接続の準備が整います。
- InitiateOAuth：REFRESH。
- OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたキー。
- OAuthClientSecret：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
- OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所。アクセストークンの自動リフレッシュを有効にするには、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定されたパスに暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンでデータに接続するには、次の接続プロパティを設定します。

InitiateOAuth：REFRESH。
OAuthClientId：カスタムOAuth アプリケーションを作成した際に表示されたシークレット。
OAuthSettingsLocation：ブラウザでマシンからコピーしたOAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品に読み書きのアクセス許可を与えることを確認してください。

接続オブジェクトの作成

Connect-Bitbucket cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。

$conn = Connect-Bitbucket -Workspace 'myworkspaceslug' -Schema 'Information'

データの取得

Select-Bitbucket cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。

$results = Select-Bitbucket -Connection $conn -Table "Issues" -Columns @("Title, ContentRaw") -Where "ContentRaw='Bug'"

Invoke-Bitbucket cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。

Select-Bitbucket -Connection $conn -Table Issues -Where "ContentRaw = 'Bug'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myIssuesData.csv -NoTypeInformation

Select-Bitbucket からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。

 
PS C:\> $conn  = Connect-Bitbucket -Workspace 'myworkspaceslug' -Schema 'Information'
PS C:\> $row = Select-Bitbucket -Connection $conn -Table "Issues" -Columns (Title, ContentRaw) -Where "ContentRaw = 'Bug'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Issues",
  "Columns":  [

  ],
  "Title":  "MyTitle",
  "ContentRaw":  "MyContentRaw"
}

データの削除

以下は、抽出条件に合うあらゆるレコードを削除します。

Select-Bitbucket -Connection $conn -Table Issues -Where "ContentRaw = 'Bug'" | Remove-Bitbucket

データの変更

cmdlet はデータクレンジング同様、データの変換を容易にします。次の例は、レコードがすでに存在するかどうか、挿入する前に更新が必要かどうかをチェックしてから、CSV ファイルのデータをBitbucket にロードします。

Import-Csv -Path C:\MyIssuesUpdates.csv | %{
  $record = Select-Bitbucket -Connection $conn -Table Issues -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-Bitbucket -Connection $conn -Table Issues -Columns @("Title","ContentRaw") -Values @($_.Title, $_.ContentRaw) -Where "Id  = `'$_.Id`'"
  }else{
    Add-Bitbucket -Connection $conn -Table Issues -Columns @("Title","ContentRaw") -Values @($_.Title, $_.ContentRaw)
  }
}

Cmdlets for Bitbucket