Cmdlets for Microsoft Dataverse

Build 25.0.9434

接続の確立

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

スキーマ

Microsoft Dataverse は、System とEntities の2つのSchema プロパティ値をサポートしています。

  • System：Web API を使用してエンティティやテーブルを直接クエリします。
  • Entities：EntityDefinitions エンティティセットパスを使用して、EntityMetadata エンティティとテーブルに関するメタデータを取得します。これは通常、より分かりやすい名前を提供しますが、追加のメタデータリクエストが必要になります。

Microsoft Dataverse への接続

Microsoft Dataverse データソースを認証するには、まずOrganizationURL プロパティを接続先の組織のURL に設定します。

例：https://[organization].crm.dynamics.com.

Entra ID（Azure AD）

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

本製品 は、Entra ID を使用したOAuth 2.0 によるMicrosoft Dataverse への認証をサポートします。 OAuth の実際の動作は、使用される認証フローを決定するAuthScheme 接続プロパティの値に依存します。

以下の表は、AuthScheme、OAuth グラントタイプ、および典型的なユースケースの関係を概説したものです。

AuthScheme OAuth グラントタイプ ユースケース
AzureAD 認可コード ブラウザ操作によるユーザーのログイン（デスクトップ / Web）、またはヘッドレス環境で別デバイスを使用してログイン
AzureServicePrincipal クライアントクレデンシャル クライアントシークレットを使用したアプリケーション単体でのアクセス
AzureServicePrincipalCert クライアントクレデンシャル 証明書ベースの認証を使用したアプリケーション単体でのアクセス
AzureMSI マネージドID Azure のマネージドID を使用するAzure ホストのアプリ / サービス

デスクトップアプリケーション向け認可コードフロー

このフローは、ブラウザを通じたユーザーログインが必要なシナリオ向けに設計されています。

CData は、認可コードグラントタイプを使用したOAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。 代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。 両者の違いは、カスタムアプリケーションでは構成時に追加で2つの接続プロパティを設定する必要があるという点だけです。

次の接続プロパティを設定して、接続してください。

  • OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。
  • CallbackURL：アプリケーション設定のリダイレクトURL に設定。

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

ヘッドレスマシン向け認可コードフロー

ヘッドレスマシンとは、ブラウザインターフェースを持たないマシンです。OAuth ではブラウザでのユーザー操作が必要なため、ブラウザを持つ別のマシンで認証を実行する必要があります。 認証完了後、クレデンシャルをヘッドレスマシンに転送します。

サポートされているオプションは2つあります。

  1. 別のデバイスで認証し、検証コードを手動でコピーする
  2. 別のマシンで認証を完了し、保存されたOAuth 設定ファイルを転送する

いずれかのオプションを完了した後、ヘッドレスマシンでアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：検証コードを取得および交換

ブラウザを備えた別のマシンを使用してOAuth 検証コードを生成します。

ブラウザを備えたデバイスで、次の方法のいずれか1つを設定してください。

  • 組み込みOAuth アプリケーション：

    本製品 は自動的にOAuth 認可URL を生成し、デフォルトのブラウザで開きます。 ブラウザウィンドウが表示されたら、Microsoft アカウントでサインインし、要求された権限を付与します。 認証後、クエリ文字列に検証コードを含むコールバックURL にリダイレクトされます。 code パラメータの値をコピーしてください。これがOAuthVerifier 接続プロパティの検証コードになります。

  • カスタムOAuth アプリケーション： 以下の接続プロパティを手動で設定します。
    • InitiateOAuth：OFF に設定。
    • OAuthClientId：登録されたアプリケーションに割り当てられたクライアントID に設定。
    • OAuthClientSecret：登録されたアプリケーションに割り当てられたクライアントシークレットに設定。

    次に、適切なCallbackURL を指定してGetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。 プロシージャが返したURL をブラウザで開き、ログインしてアプリケーションにアクセス許可を与えます。 検証コードをクエリ文字列に含むコールバックURL にリダイレクトされます。 code パラメータの値をコピーしてください。これが検証コードになります。

次に：検証コードをトークンと交換

ヘッドレスマシンで、以下の接続プロパティを設定して検証コードをアクセストークンとリフレッシュトークンに交換します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthVerifier：上記で取得したverifier code に設定。
  • OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
  • OAuthSettingsLocation：ドライバーがトークン値を保存するファイルパスに設定。

この交換が完了し設定ファイルが生成されたら、以下のように接続を再設定します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
  • OAuthSettingsLocation：保存された設定ファイルの場所に設定。トークンが自動的に更新されるよう、本製品 が読み書き可能であることを確認してください。
オプション2：OAuth 設定を転送

この方法では、ブラウザが使用可能なマシンで完全なOAuth フローを完了し、その結果の設定ファイルをヘッドレスマシンに転送します。

  1. ブラウザ対応マシンで、デスクトップアプリケーションの説明に従って接続を設定します。
  2. 認証後、本製品 は暗号化されたトークン値をOAuthSettingsLocation で指定されたファイルに保存します。デフォルトのファイル名はOAuthSettings.txt です。
  3. 接続をテストしてファイルが期待通りに動作することを確認し、ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシン上で、以下のように接続を設定します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：（カスタムアプリケーションのみ）登録したクライアントID に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）登録したクライアントシークレットに設定。
  • OAuthSettingsLocation：コピーされたOAuth 設定ファイルのパスに設定。ファイルが本製品 に読み取り / 書き込み権限を付与していることを確認してください。

クライアントクレデンシャル

クライアントクレデンシャルは、直接ユーザー認証が行われないOAuth のフローを指します。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。 アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。そのため、認証フローが標準とは少し違ったものになります。

クライアントOAuth フロー

クライアントOAuth フローに関連するすべての権限には、管理者の同意が必要です。これは、CData Cmdlets PowerShell Module for Microsoft Dataverse が埋め込まれたアプリをクライアントOAuth フローでは使用できないことを意味します。クライアントクレデンシャルを使用するには、独自のOAuth アプリの作成が必要になります。 詳しくは、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

portal.azure.com の［アプリの登録］で［API のアクセス許可］に移動し、Microsoft Graph アクセス許可を選択します。アクセス許可には、委任されたアクセス許可とアプリケーションの許可の2つの異なるアクセス許可セットがあります。 クライアントクレデンシャル認証時に使用されるアクセス許可は、［アプリケーションの許可］の下にあります。インテグレーションに必要なアクセス許可を選択します。

認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

  1. クライアントシークレット
    • AuthScheme：AzureServicePrincipal に設定。
    • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthClientSecret：アプリ設定のクライアントシークレットに設定。
  2. 証明書

クライアントクレデンシャルでの認証は、他の接続同様に自動的に行われますが、ユーザーにプロンプトするウィンドウは表示されません。ユーザーコンテキストがないため、ブラウザのポップアップは必要ないからです。 接続が行われ、内部的に処理されます。

Azure サービスプリンシパル

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

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

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

Managed Service Identity (MSI)

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

User-Managed Identities

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

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

接続オブジェクトの作成

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

$conn = Connect-CDS -OrganizationUrl "https://myaccount.crm.dynamics.com/" -OAuthClientId "clientid" -OAuthClientSecret "secret"

データの取得

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

$results = Select-CDS -Connection $conn -Table "Accounts" -Columns @("accountid, Name") -Where "Name='MyAccount'"
Invoke-CDS cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

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

Select-CDS -Connection $conn -Table Accounts -Where "Name <> 'MyAccount'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myAccountsData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-CDS -OrganizationUrl "https://myaccount.crm.dynamics.com/" -OAuthClientId "clientid" -OAuthClientSecret "secret"
PS C:\> $row = Select-CDS -Connection $conn -Table "Accounts" -Columns (accountid, Name) -Where "Name <> 'MyAccount'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Accounts",
  "Columns":  [

  ],
  "accountid":  "Myaccountid",
  "Name":  "MyName"
}

データの削除

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

Select-CDS -Connection $conn -Table Accounts -Where "Name = 'MyAccount'" | Remove-CDS

データの変更

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

Import-Csv -Path C:\MyAccountsUpdates.csv | %{
  $record = Select-CDS -Connection $conn -Table Accounts -Where ("AccountId = `'"+$_.AccountId+"`'")
  if($record){
    Update-CDS -Connection $conn -Table Accounts -Columns @("accountid","Name") -Values @($_.accountid, $_.Name) -Where "AccountId  = `'$_.AccountId`'"
  }else{
    Add-CDS -Connection $conn -Table Accounts -Columns @("accountid","Name") -Values @($_.accountid, $_.Name)
  }
}

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9434