PowerShell は、反復的なタスクを自動化し、ワークフローを合理化できる強力なスクリプト言語であり、Dataverse との統合に最適なツールです。 このクイック スタートでは、Visual Studio Code で Dataverse Web API で PowerShell を使用する方法について説明します。 PowerShell を使用した Visual Studio Code では、Postman や 不眠症などの API クライアントを使用する代わりに使用できます。
このクイック スタートでは、次の方法を学習します。
- PowerShell で Visual Studio Code を使用して、アプリケーションを登録せずに Dataverse で対話形式で認証します。
- PowerShell Invoke-RestMethod コマンドレットを使用して、Dataverse Web API への要求を作成します。
注
このクイック スタートの記事では、基本的な概念のみを紹介します。 基本的なテストにはこれで十分です。 この記事の手順を完了したら、「 Dataverse Web API で PowerShell と Visual Studio Code を使用 する」を参照して、次のような生産性を向上させる高度な機能について学習します。
- 再利用可能な関数を作成する
- 例外の処理
- Dataverse サービス保護の制限を管理する
- Fiddler を使用したデバッグ
- Dataverse Web API CSDL $metadata ドキュメントをダウンロードする
この記事の手順は Windows、Linux、および macOS で動作するはずですが、これらの手順は Windows でのみテストされています。 変更が必要な場合は、この記事の下部にある フィードバック セクションを使用してお知らせください。
[前提条件]
次の各前提条件が満たされていることを確認せずに続行しないでください。
以下をインストールするか、インストールされていることを確認する
Visual Studio Code をインストールします。 Visual Studio Code をダウンロードする を参照してください
Visual Studio Code 用の PowerShell をインストールします。 Visual Studio Code 用 PowerShell を参照してください
PowerShell 7.4 移行をインストールします。 Windows、Linux、macOS に PowerShell をインストールする を参照します
Az PowerShell モジュール バージョン 11.1.0 以降をインストールします。 Azure PowerShell をインストールする方法 を参照します
既存のインストールを最新のバージョンに更新 するには、
Update-Module -Name Az -Force
を使います
インストールを検証する
Visual Studio Code を開きます。
[ ターミナル ] メニューの [ 新しいターミナル] を選択します。
Visual Studio Code ナビゲーション ウィンドウで、PowerShell 拡張子の
アイコンを選択します。
Visual Studio Code ターミナル ウィンドウで、次のスクリプトをコピーして貼り付けます。
Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString() Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version
Enter キーを押します。 出力は、次の例のようになります。
PowerShell Version: 7.4.0 PowerShell Az version: 11.1.0
このような結果が表示されない場合は、前提条件をインストールまたは更新してください。
さらに必要なこと
- Dataverse 環境に有効なユーザー アカウント
- 接続に使用したい Dataverse 環境への URL。 検索方法については、開発者向けリソースを表示 をご覧ください。 次のようになります:
https://yourorg.crm.dynamics.com/
、これはyourorg.crm
が異なります。 - PowerShell スクリプト言語の基本的な解釈
使ってみる
Visual Studio Code で、[ファイル>新しいテキスト ファイル]、または Ctrl+を選択して新しいファイルを開きます。
ファイルを保存する必要はありません。
次のスクリプトをコピーして新しいファイルに貼り付けます。
$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this ## Login if not already logged in if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) { Connect-AzAccount | Out-Null } # Get an access token $secureToken = (Get-AzAccessToken ` -ResourceUrl $environmentUrl ` -AsSecureString).Token # Convert the secure token to a string $token = ConvertFrom-SecureString ` -SecureString $secureToken ` -AsPlainText # Common headers $baseHeaders = @{ 'Authorization' = 'Bearer ' + $token 'Accept' = 'application/json' 'OData-MaxVersion' = '4.0' 'OData-Version' = '4.0' } # Invoke WhoAmI Function Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders | ConvertTo-Json
Visual Studio Code では、PowerShell スクリプトが自動的に検出されます。
dataverse 環境の URL と一致するように、
$environmentUrl
変数の値 (https://yourorg.crm.dynamics.com/
) を編集します。F5 キーを押すか、Visual Studio Code の [実行>デバッグの開始] メニュー コマンドを使用します。
ブラウザー ウィンドウが開きます。 ブラウザ ウィンドウで、認証に使用する資格情報を入力または選択します。
Visual Studio Code ターミナル ウィンドウで出力を確認します。
ターミナルの下部で、WhoAmI 関数に必要な WhoAmIResponse 複合型の値を見つけます。 次のように見えるはずです。
{ "@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse", "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa", "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee" }
ターミナル ウィンドウで、「
cls
」と入力して、ターミナルの内容をクリアします。F5 キーを押すか、Visual Studio Code の [実行>デバッグの開始] メニュー コマンドを使用してスクリプトをもう一度実行します。
既にログインしているため、ブラウザー ウィンドウは開きません。 スクリプトを編集して実行し続けて、さまざまな要求を試すことができます。
動作方法
このセクションでは、「 試してみる」セクションに含まれる PowerShell スクリプトの詳細について説明します。
Authentication
このスクリプトでは、Az PowerShell モジュール Get-AzTenant コマンドを使用して、現在のユーザーに対して承認されたテナントを取得します。 ログインしていない場合、このコマンドはエラーを返します。 このスクリプトでは、 -ErrorAction SilentlyContinue
パラメーターを使用してエラーが無視され、何も返されません。
Get-AzTenant
コマンドが何も返さない場合、スクリプトは Connect-AzAccount を使用して対話型のブラウザー ウィンドウを開きます。このウィンドウでは、サインインする資格情報を入力または選択できます。 Azure PowerShell に対話形式でサインインする方法、またはサービス プリンシパルを使用して非対話型でサインインする方法について詳しく学びましょう。
最後に、スクリプトでは、と共に -ResourceUrl $environmentUrl
コマンドを使用して PSAccessToken インスタンスを取得します。このインスタンスには、Dataverse での認証に使用できるアクセス トークンに変換できる SecureString Token プロパティが含まれています。
別の資格情報セットで接続する場合は、 Disconnect-AzAccount コマンドを使用する必要があります。
WhoAmI 関数で Invoke-RestMethod
を使用する
$token
変数にアクセス トークンを設定したら、Dataverse Web API への要求を作成し、Invoke-RestMethod コマンドレットを使用して送信する必要があります。
ヘッダーを設定する
すべての Dataverse Web API 要求には、アクセス トークン値を含む Authorization
ヘッダーを含む一連の共通 HTTP 要求ヘッダーが含まれている必要があります。 一部の操作では、より多くのヘッダーが必要です。
Dataverse Web API 要求ヘッダーの詳細
# Common headers
$baseHeaders = @{
'Authorization' = 'Bearer ' + $token
'Accept' = 'application/json'
'OData-MaxVersion' = '4.0'
'OData-Version' = '4.0'
}
要求を送信する
WhoAmI 関数は、実行できる最も単純な Dataverse 操作の 1 つです。
アクションではなく OData 関数であるため、GET
HTTP メソッドが必要です。
Web API 関数の詳細
この要求を送信するには、 Invoke-RestMethod コマンドレットUri
、 Method
、および Headers
パラメーターを使用します。
# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json
POST
または PATCH
HTTP メソッドを使用する操作では、Body
パラメーターを使用して JSON ペイロードを送信するよう設定してください。
ConvertTo-Json コマンドレットは、返されたオブジェクトを、ターミナルで見やすい JSON 形式の文字列に変換します。
応答の UserId
プロパティのみをキャプチャする場合は、代わりに次のスクリプトを使用できます。
# Get UserId
$userId = (
Invoke-RestMethod `
-Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
-Method 'Get' `
-Headers $baseHeaders
).UserId
Write-Host $userId
トラブルシューティング
「インストールの確認」の説明に従って、必要なすべてのプログラムが インストールされていることを確認してください。
このクイック スタートの手順が失敗する可能性がある状況を次に示します。
F5 キーを押しても何も起こりません
キーボードの F-Lock、 Fn Lock、または Function Lock キーを押して、キーボードでファンクション キーが有効になっていることを確認します。
代わりに、Visual Studio Codeの
そのようなホストは不明です
スクリプトの実行後にこのエラーが表示される場合:
Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 | Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| No such host is known.
$environmentUrl
がアクセス権を持つ環境を表していることを確認します。 既定値 (https://yourorg.crm.dynamics.com/
) から変更していることを確認します。
ユーザーが組織のメンバーではない
スクリプトの実行後にこのエラーが表示される場合:
Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 | Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| { "error": { "code": "0x80072560", "message": "The user is not a member of the organization." } }
ブラウザー ウィンドウで選択するアカウントが、 $environmentUrl
パラメーターで指定された Dataverse 環境にアクセスできるアカウントであることを確認します。
以前に使用した資格情報とは異なる資格情報セットを使用している場合は、ターミナル ウィンドウで Disconnect-AzAccount コマンドを使用します。
警告: TenantId '<テナント ID>' に複数のアクティブなサブスクリプションが含まれています
スクリプトを初めて実行し、ブラウザーを使用してログインすると、次の警告が表示されることがあります。
WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use.
To select another subscription, use Set-AzContext.
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`.
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.
この警告が表示された場合は無視してかまいません。 これらの要求にはサブスクリプションは必要ありません。
次のステップ
Dataverse Web API で PowerShell と Visual Studio Code を使用して生産性を高める高度な機能について説明します。次のような方法があります。
- 再利用可能な関数を作成する
- 例外の処理
- Dataverse サービス保護の制限を管理する
- Fiddler を使用したデバッグ
- Dataverse Web API CSDL $metadata ドキュメントをダウンロードする
PowerShell を使用して Dataverse Web API 要求を認証して送信する機能が得たので、他の Web API 操作を試すことができます。
サービス ドキュメントを理解することで、Dataverse Web API 機能の詳細を学びます。