接続の確立

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

Databricks への接続

Databricks クラスターに接続するには、以下のプロパティを設定します。

Database：Databricks データベース名。
Server：Databricks クラスターのサーバーのホスト名。
HTTPPath：Databricks クラスターのHTTP パス。
Token：個人用アクセストークン。この値は、Databricks インスタンスのユーザー設定ページに移動してアクセストークンタブを選択することで取得できます。

Databricks インスタンスで必要な値は、クラスターに移動して目的のクラスターを選択し、 Advanced Options の下にあるJDBC/ODBC タブを選択することで見つけることができます。

Google Cloud Storage の設定

本製品は、CSV ファイルのアップロードにDBFS、Azure Blob Storage、およびAWS S3 をサポートしています。

DBFS Cloud Storage

クラウドストレージにDBFS を使用するには、CloudStorageType をDBFS に設定します。

Azure Blob Storage

次のプロパティを設定します。

CloudStorageType：Azure Blob storage。
StoreTableInCloud：新しいテーブルを作成する際にクラウドストレージにテーブルを保存する場合は、True。
AzureStorageAccount：Azure ストレージアカウント名。
AzureAccessKey：Databricks アカウントに関連付けられているストレージキー。Azure ポータル（ルートアカウントを使用）経由で確認してください。ストレージアカウントを選択し、Access Keys をクリックしてこの値を取得します。
AzureBlobContainer：Azure Blob ストレージコンテナの名前に設定。

AWS S3 Storage

次のプロパティを設定します。

CloudStorageType：AWS S3。
StoreTableInCloud：新しいテーブルを作成する際にクラウドストレージにテーブルを保存する場合は、True。
AWSAccessKey：AWS アカウントのアクセスキー。この値には、AWS セキュリティ認証情報ページから取得できます。
AWSSecretKey：AWS アカウントのシークレットキー。この値には、AWS セキュリティ認証情報ページから取得できます。
AWSS3Bucket：AWS S3 バケット名。
AWSRegion：Amazon Web サービスのホスティングリージョン。AWS Region の値は、Amazon S3 サービスのBuckets List ページに移動して取得できます。例：us-east-1

Databricks への認証

CData は、次の認証スキームをサポートしています。

個人用アクセストークン
Microsoft Entra ID（Azure AD）
Azure サービスプリンシパル
OAuthU2M
OAuthM2M

個人用アクセストークン

認証するには、次を設定します。

AuthScheme：PersonalAccessToken。
Token：Databricks サーバーへの接続に使用するトークン。Databricks インスタンスのユーザー設定ページに移動してアクセストークンタブを選択することで取得できます。

Microsoft Entra ID（Azure AD）

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

Entra ID を使用して認証を行う前に、Entra ID（Azure AD）アプリケーションの作成の説明に従って、Azure ポータルで Entra ID エンドポイントにアプリケーションを登録する必要があります。（Microsoft のAzure portal でアプリを構成するも参照してください。）アプリケーションが完成したら、次のプロパティを設定します。

AuthScheme：AzureAD。
AzureTenant：AzureAD アプリケーションの"概要"ページにある"ディレクトリ（テナント）ID"。
OAuthClientId：AzureAD アプリケーションの"概要"ページにある"アプリケーション（クライアント）ID"。
CallbackURL：AzureAD アプリケーションの"認証"ページの"リダイレクトURI"。

接続すると、認証を促すWeb ページが開きます。認証に成功すると、接続が確立されます。

接続文字列の例：

"Server=https://adb-8439982502599436.16.azuredatabricks.net;HTTPPath=sql/protocolv1/o/8439982502599436/0810-011933-odsz4s3r;database=default;
AuthScheme=AzureAD;InitiateOAuth=GETANDREFRESH;AzureTenant=94be69e7-edb4-4fda-ab12-95bfc22b232f;OAuthClientId=f544a825-9b69-43d9-bec2-3e99727a1669;CallbackURL=http://localhost;"

Azure サービスプリンシパル

認証するには、次のプロパティを設定します。

AuthScheme：AzureServicePrincipal。
AzureTenantId：Microsoft Azure Active Directory のテナントID。
AzureClientId：Microsoft Azure Active Directory アプリケーションのアプリケーション（クライアント）ID。
AzureClientSecret：Microsoft Azure Active Directory アプリケーションのアプリケーション（クライアント）シークレット。

OAuthU2M

OAuthU2M（User-to-Machine）認証により、ユーザーはCLI やSDK などのアプリケーションにワークスペースへのアクセスを許可することができます。セキュアなOAuth トークンを使用するため、ユーザーのパスワードを共有する必要はありません。

OAuthU2M がどのように機能するかは、次のとおりです。

ユーザーがサインインしてOAuthU2M 認証リクエストに同意すると、ツールまたはSDK はOAuth トークンを受け取ります。このトークンにより、ツールまたはSDK はユーザーに代わって認証を行うことができます。

デフォルトでは、本製品はリダイレクトURL がhttp://localhost:8020 の埋め込みOAuth アプリケーションを使用し、設定は不要です。ただし、認証時に使用されるリダイレクトURL やスコープをカスタマイズするために、Databricks Account Console でカスタムOAuth アプリケーションを登録することができます。

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

必要な設定は以下のとおりです。

AuthScheme： OAuthU2M
OAuthLevel：トークンを要求したいレベルに設定します。
OAuthClientId：OAuth 認証サーバーを使用してアプリケーションを登録する場合に割り当てられます。
CallbackURL：OAuth アプリケーションで登録されたリダイレクトURL。
DatabricksAccountId：OAuthLevel がAccountLevel に設定されている場合にのみ必要です。

OAuthM2M

OAuthM2M（Machine-to-Machine）認証は、ネットワークを介して通信するデバイスやアプリケーションの識別を検証します。認可されたマシンのみが、人間の介入なしに安全にデータを交換し、リソースにアクセスできるようにします。

OAuthM2M がどのように機能するかは、次のとおりです。

アプリケーションを認可サーバーに登録し、クライアントID およびシークレットを取得します。保護されたリソースにアクセスする際、お使いのマシンはこれらの認証情報と希望するスコープを含むリクエストを送信します。サーバーは提供された情報を検証し、有効であればアクセストークンを返します。このトークンは、リソースにアクセスするAPI コールのリクエストヘッダーに含まれます。

必要な設定は以下のとおりです。

AuthScheme：OAuthM2M
OAuthLevel：トークンを要求したいレベルに設定します。
OAuthClientId：OAuth 認証サーバーを使用してアプリケーションを登録する場合に割り当てられます。
OAuthClientSecret：OAuth 認証サーバーを使用してアプリケーションを登録する場合に割り当てられます。
DatabricksAccountId：OAuthLevel がAccountLevel に設定されている場合にのみ必要です。

接続オブジェクトの作成

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

$conn = Connect-Databricks -Server "127.0.0.1" -HTTPPath "MyHTTPPath"" -User "MyUser" -Token "MyToken"

データの取得

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

$results = Select-Databricks -Connection $conn -Table "[CData].[Sample].Customers" -Columns @("City, CompanyName") -Where "Country='US'"

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

cmdlet 出力のパイプ処理

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

Select-Databricks -Connection $conn -Table [CData].[Sample].Customers -Where "Country = 'US'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my[CData].[Sample].CustomersData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-Databricks -Server "127.0.0.1" -HTTPPath "MyHTTPPath"" -User "MyUser" -Token "MyToken"
PS C:\> $row = Select-Databricks -Connection $conn -Table "[CData].[Sample].Customers" -Columns (City, CompanyName) -Where "Country = 'US'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "[CData].[Sample].Customers",
  "Columns":  [

  ],
  "City":  "MyCity",
  "CompanyName":  "MyCompanyName"
}

データの削除

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

Select-Databricks -Connection $conn -Table [CData].[Sample].Customers -Where "Country = 'US'" | Remove-Databricks

データの変更

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

Import-Csv -Path C:\My[CData].[Sample].CustomersUpdates.csv | %{
  $record = Select-Databricks -Connection $conn -Table [CData].[Sample].Customers -Where ("_id = `'"+$_._id+"`'")
  if($record){
    Update-Databricks -Connection $conn -Table [CData].[Sample].Customers -Columns @("City","CompanyName") -Values @($_.City, $_.CompanyName) -Where "_id  = `'$_._id`'"
  }else{
    Add-Databricks -Connection $conn -Table [CData].[Sample].Customers -Columns @("City","CompanyName") -Values @($_.City, $_.CompanyName)
  }
}

Cmdlets for Databricks