接続の確立

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

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。

Install-Module Dynamics365Cmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。

Import-Module Dynamics365Cmdlets;

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

$conn = Connect-Dynamics365 -OrganizationUrl "https://myaccount.operations.dynamics.com/" -Edition "Sales"

Microsoft Dynamics 365 への接続

接続には、Edition およびOrganizationUrl 接続プロパティが必須です。Microsoft Dynamics 365 ドライバーは、以下のMicrosoft Dynamics 365 エディションへの接続をサポートしています。

CustomerService
FieldService
FinOpsOnline
FinOpsOnPremise
HumanResources
Marketing
ProjectOperations
Sales

"Supply Chain Management" は"Finance and Operations" と同一です。Edition を"FinOpsOnline" または"FinOpsOnPremise" のいずれかに設定することで接続できます。

Microsoft Dynamics 365 Business Central については、個別のMicrosoft Dynamics 365 Business Central ドライバーを使用してください。

OrganizationUrl は、Microsoft Dynamics 365 組織へのURL です。例：https://orgcb42e1d0.crm.dynamics.com

Microsoft Dynamics 365 への認証

OAuth

Azure テナントの新しいOAuth アプリケーションを承認する際、組織による管理者の同意が必要になる場合があります。すべてのOAuth フローにおいて、組織の誰かがOAuth アプリケーションを初めてインストールして使用する場合、組織の管理者がそのAzure テナントのアプリケーションを承認する必要があります。

しかし、組織はこの要件を無効にすることを選択できます。

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

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、Azure AD アプリケーションの作成を参照してください。

認証に関する2つの方法の違いは、カスタムOAuth アプリケーションを使用する場合に、2つの接続プロパティを追加で設定する必要があることだけです。次の接続プロパティを設定して、接続してください。

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

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

Web アプリケーション

Web アプリケーション経由で接続する場合は、Microsoft Dynamics 365 にカスタムOAuth アプリケーションを作成および登録する必要があります。カスタムアプリケーションについて詳しくは、Azure AD アプリケーションの作成を参照してください。それから本製品を使用してOAuth トークンの値を取得および管理します。

OAuth アクセストークンの取得

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

AuthScheme： AzureAD。
OAuthClientId：アプリケーション設定のクライアントId。
OAuthClientSecret：アプリケーション設定のクライアントシークレット。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。ストアドプロシージャがOAuth エンドポイントのURL を返します。
URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。

アクセストークンとリフレッシュトークンを取得すると、データに接続し、OAuth アクセストークンを自動または手動でリフレッシュすることができるようになります。

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

ドライバーがOAuth アクセストークンを自動的にリフレッシュするようにするには、最初のデータ接続で次のように設定します。

InitiateOAuth： REFRESH。
OAuthClientId：アプリケーション設定のクライアントId。
OAuthClientSecret：アプリケーション設定のクライアントシークレット。
OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
OAuthRefreshToken：GetOAuthAccessToken によって返されたリフレッシュトークン。
OAuthSettingsLocation：本製品がOAuth トークン値を保存する場所。これは接続間で維持されます。

次回のデータ接続では、OAuthAccessToken およびOAuthRefreshToken の値は、OAuthSettingsLocation から取得されます。

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

データ接続時に手動でOAuth アクセストークンをリフレッシュするために必要な値は、OAuth リフレッシュトークンのみです。

GetOAuthAccessToken によって返されたExpiresIn パラメータ値が経過した後に、RefreshOAuthAccessToken ストアドプロシージャを使用し、手動でOAuthAccessToken をリフレッシュします。次の接続プロパティを設定します。

OAuthClientId：アプリケーション設定のクライアントId。
OAuthClientSecret：アプリケーション設定のクライアントシークレット。

次に、RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを指定します。新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定し、新しい接続をオープンします。

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

ヘッドレスマシン

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

以下の2つのオプションから選択します。
- オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2：別のマシンに本製品をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
その後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品を設定します。

カスタムOAuth アプリのOAuth クレデンシャルを使用して、ヘッドレスOAuth 認証フローに従うことができます。カスタムOAuth アプリケーションを作成するには、Azure AD アプリケーションの作成を参照してください。このセクションでは、データの認証および接続を行う手順について説明します。

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

まず最初に、ヘッドレスマシンで次のプロパティを設定します。

InitiateOAuth：OFF に設定。
OAuthClientId：OAuth 統合設定のクライアントID に設定。
OAuthClientSecret：OAuth 統合設定のクライアントシークレットに設定。

次に、別のマシンから認証してOAuthVerifier 接続プロパティを取得します。

GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したリダイレクトURI に設定します。ストアドプロシージャがOAuth エンドポイントのURL を返します。
返されたURL をブラウザで開きます。ログインして、本製品にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
Verifier の値を保存します。OAuthVerifier 接続プロパティにVerifier の値を設定する必要があります。

最後に、ヘッドレスマシンで、次の接続プロパティを設定してOAuth 認証値を取得します。

OAuthClientId：OAuth 統合設定のクライアントID に設定。
OAuthClientSecret：OAuth 統合設定のクライアントシークレットに設定。
OAuthVerifier：verifier code に設定。
OAuthSettingsLocation：暗号化されたOAuth 認証値を指定された場所に永続化。
InitiateOAuth：REFRESH に設定。

データへの接続

OAuth 設定ファイルが生成されたら、次のプロパティを設定してデータに接続します。

OAuthSettingsLocation：暗号化されたOAuth 認証値が保存される場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所がプロバイダーに読み書きのアクセス許可を与えることを確認してください。
InitiateOAuth：REFRESH に設定。

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

別のマシンに本製品をインストールするには、認証してから、結果のOAuth 値を転送します。

セカンドマシンに、本製品をインストールして、次の接続プロパティセットで接続します。
- OAuthSettingsLocation：書き込み可能な場所に設定。
- OAuthClientId：アプリケーション設定のクライアントID に設定。
- OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
- CallbackURL：アプリケーション設定のコールバックURL に設定。
認証する接続をテストします。生成された認証値は、OAuthSettingsLocation で指定されたパスに書き込まれて暗号化されます。接続テストに成功したら、OAuth 設定ファイルをヘッドレスマシンにコピーします。ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
- InitiateOAuth：REFRESH に設定。
- OAuthSettingsLocation：OAuth 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品に読み書きのアクセス許可を与えることを確認してください。

管理者の同意

管理者の同意とは、Azure Active Directory テナントの管理者が、管理者の同意を必要とするアプリケーションに権限を付与することを指します。 CData Cmdlets PowerShell Module for Microsoft Dynamics 365 内の埋め込みアプリケーションには、管理者の同意を必要とするアクセス許可はありません。したがって、この情報はカスタムアプリケーションにのみ適用されます。

管理者の同意の付与

Azure ポータルで新しいOAuth アプリケーションを作成する場合には、アプリに必要なアクセス許可を指定する必要があります。一部のアクセス許可には、「管理者の同意が必要」と記載されている場合があります。例えば、すべてのグループのアクセス許可には管理者の同意が必要です。アプリケーションに管理者の同意が必要な場合、いくつかの方法があります。

管理者の同意を付与する最も簡単な方法は、管理者がportal.azure.com にログインして、アプリの登録で作成したアプリケーションに移動するだけです。API のアクセス許可で、同意の付与をクリックして、アプリケーションが作成されたテナントで必要なアクセス権限を付与します。

組織に複数のテナントがある場合、またはアプリケーションが組織外の他のテナントにアクセス許可を与える必要がある場合、GetAdminConsentURL を使用してAdmin Authorization URL を生成できます。 GetOAuthAuthorizationUrl とは異なり、このエンドポイントから返される重要な情報はありません。テナントがアクセスを許可すると、許可が付与されたことを示すboolean を返します。

管理者が同意すると、通常どおり認証を行うことができます。

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

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

クライアントOAuth フロー

クライアントOAuth フローに関連するすべてのアクセス許可には、管理者の同意が必要です。これは、CData Cmdlets PowerShell Module for Microsoft Dynamics 365 が埋め込まれたアプリケーションをクライアントOAuth フローでは使用できないことを意味します。クライアント資格情報を使用するには、独自のOAuth アプリケーションの作成が必要になります。詳しくは、Azure AD アプリケーションの作成を参照してください。

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

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

クライアントシークレット
- InitiateOAuth： GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant：接続するテナント。
- OAuthGrantType： CLIENT。
- OAuthClientId：アプリケーション設定のクライアントID。
- OAuthClientSecret：アプリケーション設定のクライアントシークレット。
証明書
- InitiateOAuth： GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant：接続するテナント。
- OAuthGrantType： CLIENT。
- OAuthClientId：アプリケーション設定のクライアントID。
- OAuthJWTCert：JWT 証明書のストア。
- OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類。

Azure AD

Azure AD は、OAuth を使用して認証する接続タイプです。AuthScheme をAzureAD に設定します。

下記の手順に従って、カスタムAzureAD アプリの資格情報を使用して認証します。Azure AD アプリケーションの作成を参照してください。

アプリの認証には、クライアントシークレットを使用する方法と、証明書を使用する方法の2種類があります。設定されたアプリ認証に応じて、いずれかを使用できます。

AzureAD アクセストークンの取得

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

クライアントシークレット
- AuthScheme：アプリ設定のAzureServicePrincipal。
- InitiateOAuth： GETANDREFRESH。InitiateOAuth を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant：接続するテナント。
- OAuthClientId：アプリケーション設定のクライアントID。
- OAuthClientSecret：アプリケーション設定のクライアントシークレット。
証明書
- AuthScheme：アプリ設定のAzureServicePrincipal。
- InitiateOAuth： GETANDREFRESH。InitiateAzureAD を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant：接続するテナント。
- OAuthClientId：アプリケーション設定のクライアントID。
- OAuthJWTCert：JWT 証明書のストア。
- OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類。

Azure サービスプリンシパル

Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理されます。直接のユーザー認証は行われません。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。 Azure アプリとAzure サービスプリンシパルの作成 Azure サービスプリンシパルを使用して認証する場合、Azure AD テナントにアプリケーションを登録する必要があります。詳しくは、カスタムAzureAD サービスプリンシパルアプリの作成を参照してください。

アプリケーションへのロールの割り当て

サブスクリプションのリソースにアクセスするには、アプリケーションにロールを割り当てる必要があります。

検索バーでサブスクリプションサービスを検索・選択して、サブスクリプションページを開きます。
アプリケーションを割り当てるサブスクリプションを選択します。
アクセス制御 (IAM)を開き、追加 -> ロール割り当ての追加 を選択してロール割り当ての追加ページを開きます。
作成したAzure AD アプリに割り当てるロールとして、所有者を選択します。

認証の完了

接続するには以下の手順に従います。

アプリケーション設定でクライアントシークレットを使用する場合はAuthScheme をAzureServicePrincipal に、証明書を使用する場合はAzureServicePrincipalCert に設定します。
両方のスキームに適用される接続プロパティを設定します。
選択した認証スキームに固有の接続プロパティを設定します。

クライアントシークレットと証明書の両方

これらの接続プロパティを設定し、次に該当するセクションに進みます。

InitiateOAuth： GETANDREFRESH。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
AzureTenant：接続するテナント。

クライアントシークレット

続いて、以下を設定します。

OAuthClientId：アプリケーション設定のクライアントId。
OAuthClientSecret：アプリケーション設定のクライアントシークレット。

証明書

続いて、以下を設定します。

OAuthJWTCert：JWT 証明書のストア。
OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類。

データの取得

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

$results = Select-Dynamics365 -Connection $conn -Table "GoalHeadings" -Columns @("GoalHeadingId, GoalHeadingId") -Where "Name='MyAccount'"

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

cmdlet 出力のパイプ処理

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

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

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

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

 
PS C:\> $conn  = Connect-Dynamics365 -OrganizationUrl "https://myaccount.operations.dynamics.com/" -Edition "Sales"
PS C:\> $row = Select-Dynamics365 -Connection $conn -Table "GoalHeadings" -Columns (GoalHeadingId, GoalHeadingId) -Where "Name <> 'MyAccount'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "GoalHeadings",
  "Columns":  [

  ],
  "GoalHeadingId":  "MyGoalHeadingId",
  "GoalHeadingId":  "MyGoalHeadingId"
}

データの削除

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

Select-Dynamics365 -Connection $conn -Table GoalHeadings -Where "Name = 'MyAccount'" | Remove-Dynamics365

データの変更

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

Import-Csv -Path C:\MyGoalHeadingsUpdates.csv | %{
  $record = Select-Dynamics365 -Connection $conn -Table GoalHeadings -Where ("GoalHeadingId = `'"+$_.GoalHeadingId+"`'")
  if($record){
    Update-Dynamics365 -Connection $conn -Table GoalHeadings -Columns @("GoalHeadingId","GoalHeadingId") -Values @($_.GoalHeadingId, $_.GoalHeadingId) -Where "GoalHeadingId  = `'$_.GoalHeadingId`'"
  }else{
    Add-Dynamics365 -Connection $conn -Table GoalHeadings -Columns @("GoalHeadingId","GoalHeadingId") -Values @($_.GoalHeadingId, $_.GoalHeadingId)
  }
}

Cmdlets for Microsoft Dynamics 365