接続の確立

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 への接続

Microsoft Dynamics 365 ドライバーは、以下のMicrosoft Dynamics 365 エディションへの接続をサポートしています。

CustomerService
FieldService
FinOpsOnline (Default)
FinOpsOnPremise
HumanResources
Marketing
ProjectOperations
Sales

Notes：

Supply Chain Management はFinance and Operations と同一です。これらのいずれかに接続するには、Edition をFinOpsOnline またはFinOpsOnPremise のいずれかに設定します。
Microsoft Dynamics 365 Business Central については、個別のMicrosoft Dynamics 365 Business Central ドライバーを使用してください。

接続するには、次のパラメータを設定します。

RSBDynamics365_p_OrganizationURL：お使いのMicrosoft Dynamics 365 組織のURL。例えば、https://orgcb42e1d0.crm.dynamics.com。
Edition：上記のエディション一覧に示すとおり。

Microsoft Dynamics 365 への認証

Microsoft Dynamics 365 は、Azure AD、Azure サービスプリンシパル、Azure マネージドID（MSI）を経由する認証をサポートします。これらはすべてOAuth 規格に基づきます。

Azure AD

Azure AD 経由で認証するには、Azure AD アプリケーションの作成で説明するように、カスタムAzureAD アプリケーションを作成する必要があります。クライアントシークレットまたはJWT 証明書のいずれかで認証できます。

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

AuthScheme：AzureAD。
InitiateOAuth：GETANDREFRESH。この設定により、InitiateOAuth を使用することでAzureAD 交換の繰り返しや手動でのOAuthAccessToken 設定を避けられます。
AzureTenant：接続するAzure テナント。
OAuthClientId：カスタムアプリケーションの作成時に割り当てられたクライアントId。
OAuthClientSecret（クライアントシークレットのみ）：カスタムアプリケーションの作成時に割り当てられたクライアントシークレット。
OAuthJWTCert（証明書のみ）：JWT 証明書のストア。
OAuthJWTCertType（証明書のみ）：OAuthJWTCert で指定された証明書ストアの種類。

管理者の同意

管理者の同意とは、Azure AD テナントの管理者が、使用ケースに応じてカスタムアプリケーションに付与する権限を指します。（CData Cmdlets PowerShell Module for Microsoft Dynamics 365 内の埋め込みアプリケーションには管理者の同意を必要とする権限は含まれていないため、管理者の同意はカスタムアプリケーションにのみ適用されます。）

組織がAzure テナントの新しいOAuth アプリケーションを認可するために管理者の同意を必要とする場合、組織の誰かが初めてOAuth アプリケーションをインストールして使用するときは、組織の管理者が明示的にそのアプリケーションへのアクセスを許可する必要があることを意味します。

（組織はこの要件を無効にすることができます。）

管理者の同意の付与

Azure ポータルで新しいOAuth アプリケーションを作成する場合（Azure AD アプリケーションの作成参照）には、そのアプリケーションに必要なアクセス許可を指定する必要があります。新しいカスタムアプリケーションに管理者の同意が必要であることが分かっている場合は、管理者の同意が必要と表示されている権限を指定することから始めることができます。（例えば、すべてのグループのアクセス許可には管理者の同意が必要です。）

管理者の同意を付与するには2つの方法があります。

管理者の同意を付与する最も簡単な方法は、管理者がportal.azure.com にログインして、アプリの登録で作成したアプリケーションに移動するだけです。 API のアクセス許可で、同意の付与をクリックします。アプリケーションが作成されたテナントで必要なアクセス権限を付与します。
組織に複数のテナントがある場合、またはアプリケーションが組織外の他のテナントにアクセス許可を与える必要がある場合、GetAdminConsentURL を使用してAdmin Authorization URL を生成できます。 GetOAuthAuthorizationUrl とは異なり、このエンドポイントから返される重要な情報はありません。テナントがアクセスを許可すると、権限が付与されたことを確認するBoolean を返します。

管理者が同意を付与すると、通常通り認証が行われます。

クライアントクレデンシャル認証フロー

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

クライアントOAuth フローに関連するすべてのアクセス許可には、管理者の同意が必要です。 これは、CData Cmdlets PowerShell Module for Microsoft Dynamics 365 が埋め込まれたアプリケーションをクライアントOAuth フローでは使用できないことを意味します。クライアントクレデンシャルを使用するには、Azure AD アプリケーションの作成で説明するように独自のOAuth アプリケーションを作成する必要があります。

これを行うには：

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

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

InitiateOAuth：GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
AzureTenant：接続するテナント。
OAuthClientId：カスタムアプリケーションの作成時に割り当てられたクライアントId。
OAuthClientSecret（クライアントシークレットのみ）：カスタムアプリケーションの作成時に割り当てられたクライアントシークレット。
OAuthJWTCert（証明書のみ）：JWT 証明書のストア。
OAuthJWTCertType（証明書のみ）：OAuthJWTCert で指定された証明書ストアの種類。

Azure サービスプリンシパル

Azure AD のアクションは、ユーザーアカウントまたはサービスプリンシパルのいずれかで実行できます。サービスプリンシパルは、割り当てられたロールと権限に基づいてタスクを実行する、上位権限を持つ非インタラクティブアカウントです。 Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理されるため、ユーザーは関与しません。 Azure サービスプリンシパルとして認証するには、カスタムAzureAD サービスプリンシパルアプリの作成で説明するように、カスタムAzureAD サービスプリンシパルアプリケーションを作成する必要があります。

接続の準備ができたら、次のプロパティを設定します。

AuthScheme： クライアントシークレットを使用する場合はAzureServicePrincipal、JWT 証明書を使用する場合はAzureServicePrincipalCert。
InitiateOAuth：GETANDREFRESH。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
AzureTenant：接続するテナント。
OAuthClientId（クライアントシークレットのみ）：アプリケーション設定のクライアントId。
OAuthClientSecret（クライアントシークレットのみ）：カスタムアプリケーションの作成時に割り当てられたクライアントシークレット。
OAuthJWTCert（証明書のみ）：JWT 証明書のストア。
OAuthJWTCertType（証明書のみ）：OAuthJWTCert で指定された証明書ストアの種類。

Managed Service Identity (MSI)

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

User-Managed Identities

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

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

データの取得

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