接続の確立

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

Azure Analysis Services への接続

接続するには、認証に加えて、URL プロパティを有効なAzure Analysis Services サーバー、例えばasazure://southcentralus.asazure.windows.net/server に設定します。

必要に応じて、Database を設定して、サーバー上のどのAzure データベースに接続するかを区別します。

Azure Analysis Services への認証

Entra ID（Azure AD）

Microsoft Entra ID は、マルチテナント型のクラウドベースのID およびアクセス管理プラットフォームです。 OAuth ベースの認証フローに対応しており、ドライバーによるAzure Analysis Services エンドポイントへのセキュアなアクセスを実現します。

Web アプリケーションを介したEntra ID への認証には、必ずはじめにカスタムOAuth アプリケーションを作成して登録する必要があります。これにより、アプリケーションは独自のリダイレクトURI を定義し、クレデンシャルのスコープを管理し、組織固有のセキュリティポリシーに準拠することができるようになります。

カスタムOAuth アプリケーションの作成および登録方法の詳細については、Entra ID（Azure AD）アプリケーションの作成を参照してください。

AuthScheme をAzureAD に設定した後の認証手順は、環境によって異なります。デスクトップアプリケーション、Web ベースのワークフロー、またはヘッドレスシステムから接続する方法の詳細については、以下のセクションを参照してください。

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

デスクトップアプリケーションでは、ドライバーに組み込まれたOAuth アプリケーション、またはMicrosoft Entra ID に登録されたカスタムOAuth アプリケーションのいずれかを使用して認証を行うことができます。

オプション1：組み込みOAuth アプリケーションの使用

これはドライバーに含まれている、事前登録済みのアプリケーションです。セットアップが簡単で、独自の認証情報を登録する必要がないため、開発環境、単一ユーザー向けツール、または迅速かつ簡単な認証が求められる構成に最適です。

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

AuthScheme：AzureAD
InitiateOAuth：
- GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
- REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。

接続時には、ドライバーは既定のブラウザでMicrosoft Entra のサインインページを開きます。サインインしてアクセスを許可すると、ドライバーはアクセストークンおよびリフレッシュトークンを取得し、OAuthSettingsLocation で指定されたパスに保存します。

オプション2：カスタムOAuth アプリケーションの使用

組織でセキュリティポリシーの管理、リダイレクトURI の設定、アプリケーションのブランディングなど、より高度な制御が必要な場合は、代わりにMicrosoft Entra ID にカスタムOAuth アプリケーションを登録し、接続時にその値を指定することができます。

登録時に、以下の値を記録してください。

OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

カスタムOAuth アプリケーションの登録とリダイレクトURI の設定方法の詳細については、Entra ID（Azure AD）アプリケーションの作成を参照してください。

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

AuthScheme： AzureAD
InitiateOAuth：
- GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
- REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。
OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

認証後、トークンはOAuthSettingsLocation に保存されます。これらの値はセッションをまたいで保持され、アクセストークンの有効期限が切れた際に自動的に更新されるため、次回以降の接続時に再度ログインする必要はありません。

ヘッドレスマシン

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

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

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

Verifier code の使用

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

OAuth 設定を転送

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

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

Azure サービスプリンシパル

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

Azure サービスプリンシパルは、ロールに基づいたアプリケーションベースの認証です。これは、認証がユーザーごとではなく、アプリケーションごとに行われることを意味します。アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで、割り当てられたロールに基づいて実行されます。リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Azure サービスプリンシパル認証の設定方法については、Entra ID（Azure AD）でのサービスプリンシパルアプリの作成を参照してください。

Azure Password

Azure 認証情報を使用してAzure Active Directory に直接認証するには、以下の接続プロパティを指定します：

AuthScheme：AzurePassword。
User：認証するAzure ユーザーのアカウント。
Password：認証するAzure ユーザーのパスワード。
AzureTenant：Azure 上のAzure Analysis Services への認証に使用するカスタムAzure AD アプリケーションのディレクトリ（テナント）ID。これを見つけるには、カスタムアプリケーションの概要ページに移動します。

Managed Service Identity (MSI)

Azure VM 上でAzure Analysis Services を実行しており、マネージドID（MSI）認証情報を自動的に取得して接続したい場合は、AuthScheme を AzureMSI に設定します。

User-Managed Identities

マネージドID のトークンを取得するには、OAuthClientId プロパティを使用してマネージドID のclient_id を指定します。

VM に複数のユーザーが割り当てられたマネージドID がある場合は、OAuthClientId も指定する必要があります。

接続オブジェクトの作成

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

$conn = Connect-AAS -URL 'asazure://southcentralus.asazure.windows.net/server'

データの取得

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

$results = Select-AAS -Connection $conn -Table "[adventureworks].[Model].Customer" -Columns @("Country, Education") -Where "Country='Australia'"

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

cmdlet 出力のパイプ処理

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

Select-AAS -Connection $conn -Table [adventureworks].[Model].Customer -Where "Country = 'Australia'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\my[adventureworks].[Model].CustomerData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-AAS -URL 'asazure://southcentralus.asazure.windows.net/server'
PS C:\> $row = Select-AAS -Connection $conn -Table "[adventureworks].[Model].Customer" -Columns (Country, Education) -Where "Country = 'Australia'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "[adventureworks].[Model].Customer",
  "Columns":  [

  ],
  "Country":  "MyCountry",
  "Education":  "MyEducation"
}

Cmdlets for Azure Analysis Services