接続の確立

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

Lakebase への接続

Lakebase に接続するには以下のプロパティを設定します。

DatabricksInstance：Databricks インスタンスまたはサーバーのホスト名。instance-abcdef12-3456-7890-abcd-abcdef123456.database.cloud.databricks.com の形式で指定します。
Server：Lakebase データベースをホスティングしているサーバーのホスト名またはIP アドレス。
Port（オプション）：Lakebase データベースをホスティングしているサーバーのポート。デフォルトは5432 に設定されています。
Database（オプション）：Lakebase サーバーへの認証後に接続するデータベース。デフォルトでは認証ユーザーのデフォルトデータベースに設定されています。

Lakebase の認証スキーム

Lakebase は、ワークスペースレベルのAPI を呼び出すため、次の2種類のOAuth ベースの認証スキームをサポートしています：OAuthClient およびOAuthPKCE。

OAuthClient

OAuthClient は、OAuth のクライアントクレデンシャルグラント種別を使用します。この認証スキームでは、OAuthClient 認証の設定に記載されているように、接続するためにサービスプリンシパルに対して追加の設定を実行する必要があります。

認証はOAuth クライアントクレデンシャルフローを介して処理されます。このフローには直接的なユーザー認証は含まれません。代わりに、アプリケーション自体にのみ適用される資格情報を使用します。 CData Cmdlets PowerShell Module for Lakebase は、サービスプリンシパル自体を使用して認証し、関連する権限はサービスプリンシパルで定義されます。

埋め込みのOAuth クレデンシャルは提供されないため、OAuthClient 認証スキームを指定するには、OAuthClient 認証の設定に記載されているように、サービスプリンシパルの追加設定を実行する必要があります。

以下の設定パラメータを設定します。

AuthScheme：OAuthClient。
OAuthClientId：サービスプリンシパルを設定したときに割り当てられたクライアントID（コンシューマーキーとも呼ばれます）。このID は、認証時にOAuth 認可サーバーにアプリケーションを識別させるために必要です。
OAuthClientSecret：サービスプリンシパルを設定したときに割り当てられたクライアントシークレット（アプリケーションシークレットまたはコンシューマーシークレットとも呼ばれます）。この機密情報は、OAuth 認可サーバーに対してアプリケーションを認証するために使用されます。

OAuthPKCE

OAuthPKCE は、PKCE（Proof Key for Code Exchange）を使用したOAuth code グラント種別を使用して、クロスサイトリクエストフォージェリおよび認可コードインジェクション攻撃から保護します。

この認証スキームでは、認証は、クライアントがアクセストークンと交換する一時的なコードの使用を介して処理されます。コード自体は認可サーバーから取得され、ユーザーはクライアントが要求している情報を確認し、リクエストを承認または拒否できます。

以下の設定パラメータを設定します。

AuthScheme：OAuthPKCE。
User：認証するユーザーのユーザーID。

Lakebase への認証

Lakebase に接続するために必要な接続パラメータと、選択した認証形式に必要な設定パラメータを設定したら、以下のセクションで説明されているようにLakebase に認証できます。

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

デスクトップアプリケーションからLakebase に初めて認証する場合、OAuth フローの過程でInitiateOAuth を2回設定する必要があります

初回ログイン時、InitiateOAuth をGETANDREFRESH に設定する必要があります。これによりログインページが起動し、トークンが保存されます。
有効なアクセストークンとリフレッシュトークンを取得したら、InitiateOAuth をREFRESH に再設定できます。これにより、ユーザーに再度プロンプトを表示することなく保存されたトークンが再利用されます。これは無人マシンで役立ちます。

認証後、トークンはOAuthSettingsLocation に保存されます。これらの値はセッション間で永続化され、アクセストークンの期限が切れたときに自動的に更新するために使用されます。これは、後続の接続時に再度ログインする必要がないことを意味します。

ヘッドレスマシン

CI / CD パイプライン、バックグラウンドサービス、サーバーベース連携などのヘッドレス環境では、対話型のブラウザが使用できません。 OAuthClient を使用して認証するには、別のデバイス上のブラウザでOAuth フローを完了し、その認証結果をヘッドレスシステムに転送する必要があります。

Note： 以下の手順は、OAuthPKCE 認証スキームでの使用を目的としています。OAuthClient 認証スキームはブラウザの対話を必要としないため、ヘッドレスマシンでもInitiateOAuth=GETANDREFRESH を使用できます。

セットアップオプション :

Verifier code を取得および交換：別のデバイスを使用してサインインし、Verifier code を取得します。ヘッドレスシステムがこのコードを使用してトークンを要求します。
OAuth 設定ファイルを転送：別のデバイスで認証を行い、その後、保存されたトークンファイルをヘッドレス環境にコピーします。

Verifier code の使用

ブラウザを備えたデバイスで：
- InitiateOAuth をOFF に設定します。.
- GetOAuthAuthorizationUrl ストアドプロシージャを呼び出し、サインインURL を生成します。
- 返されたURL をブラウザで開きます。サインインして、ドライバーにアクセス許可を与えます。
  verifier code を含むコールバックURL にリダイレクトされます。
- サインイン後、リダイレクトURL のcode パラメータの値を保存します。この値は後でOAuthVerifier 接続プロパティを設定する際に使用します。
ヘッドレスマシンで：
- 次のプロパティを設定します。
  - OAuthClientId：サービスプリンシパルを設定したときに生成されたクライアントId。
  - OAuthClientSecret：サービスプリンシパルを設定したときに生成されたクライアントシークレット。
- トークンを保存した後、以下の設定により再利用できます。
  - OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。

OAuth 設定を転送

ブラウザを備えたデバイスで、デスクトップアプリケーションセクションの説明に従って接続します。接続後、トークンはOAuthSettingsLocation のファイルパスに保存されます。デフォルトのファイル名はOAuthSettings.txt です。
ヘッドレスマシンで：
1. OAuth 設定ファイルをマシンにコピーします。
2. 次のプロパティを設定します。
  - OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。

セットアップ後、ドライバーは保存されたトークンを使用してアクセストークンを自動的に更新します。ブラウザや手動でのログインは必要ありません。

接続オブジェクトの作成

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

$conn = Connect-Lakebase -User 'lakebase' -Password 'admin' -Server '127.0.0.1' -Port '5432' -Database 'lakebase'

データの取得

接続の作成が完了したら、リレーショナルデータベースに対して通常行える操作を別のcmdlet を使って実行できます。 Select-Lakebase cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。

$results = Select-Lakebase -Connection $conn -Table ""lakebase"."schema01".Orders" -Columns @("ShipName, ShipCity") -Where "ShipCountry='USA'"

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

cmdlet 出力のパイプ処理

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

Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where "ShipCountry = 'USA'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my"lakebase"."schema01".OrdersData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Lakebase -User 'lakebase' -Password 'admin' -Server '127.0.0.1' -Port '5432' -Database 'lakebase'
PS C:\> $row = Select-Lakebase -Connection $conn -Table ""lakebase"."schema01".Orders" -Columns (ShipName, ShipCity) -Where "ShipCountry = 'USA'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  ""lakebase"."schema01".Orders",
  "Columns":  [

  ],
  "ShipName":  "MyShipName",
  "ShipCity":  "MyShipCity"
}

データの削除

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

Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where "ShipCountry = 'USA'" | Remove-Lakebase

データの変更

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

Import-Csv -Path C:\My"lakebase"."schema01".OrdersUpdates.csv | %{
  $record = Select-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity) -Where "Id  = `'$_.Id`'"
  }else{
    Add-Lakebase -Connection $conn -Table "lakebase"."schema01".Orders -Columns @("ShipName","ShipCity") -Values @($_.ShipName, $_.ShipCity)
  }
}

Cmdlets for Lakebase