クイックスタート PowerShell と Visual Studio Code を使った Web API

PowerShell は、反復的なタスクを自動化し、ワークフローを合理化できる強力なスクリプト言語であり、Dataverse との統合に最適なツールです。 このクイック スタートは、Dataverse コード内の Visual Studio Code の Web API で PowerShell の使用を開始するのに役立つことに重点を置いています。 PowerShell を使用した Visual Studio Code は、Postman などの API クライアントか Insomnia の使用の代替を提供します。

このクイックスタートで学習する内容は次のとおりです。

• PowerShell を使用した Visual Studio Code を使用して、アプリケーションを登録せずに Dataverse と対話的に認証します。
• PowerShell Invoke-RestMethod コマンドレット を使用して、Dataverse Web API へのリクエストを作成します。

注意

このクイック スタート記事では、基本的な概念のみを紹介します。 基本的なテストにはこれで十分です。 この記事の手順を完了したら、次の方法など、生産性を向上させる高度な機能である、PowerShell と Visual Studio Code を Dataverse Web API を使用して使う に移動して詳細を確認してください。

• 再利用可能な関数を作成する
• 例外処理
• 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 を使います

インストールを検証する

1. Visual Studio Code を開きます。

2. ターミナル メニューで、新規ターミナル を選択します。

3. Visual Studio Code ナビゲーション ウィンドウで、PowerShell 拡張子の アイコンを選択します。

4. Visual Studio Code ターミナル ウィンドウで、次のスクリプトをコピーして貼り付けます。

   Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
   Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version
   

5. Enter キーを押します。 出力は、次の例のようになります。

   PowerShell Version: 7.4.0
   PowerShell Az version: 11.1.0
   

このような結果が表示されない場合は、前提条件をインストールまたは更新してください。

さらに必要なこと

• Dataverse 環境に有効なユーザー アカウント
• 接続に使用したい Dataverse 環境への URL。 検索方法については、開発者向けリソースを表示 をご覧ください。 次のようになります: https://yourorg.crm.dynamics.com/、これは yourorg.crm が異なります。
• PowerShell スクリプト言語の基本的な解釈

試用する

1. Visual Studio Code で、 ファイル > 新しいテキスト ファイル を選択するか、Ctrl+N で新しいファイルを開きます。

   ファイルを保存する必要はありません。

2. 以下のスクリプトを ファイルにコピーし貼り付けます。

   $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
   $token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
   # 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 スクリプトであることを自動的に検出する必要があります。

3. $environmentUrl 変数値 (https://yourorg.crm.dynamics.com/) を Dataverse 環境 URL と一致するように編集します。

4. F5 を押すか、Visual Studio Code実行 > デバッグ開始 メニューコマンドを使います。

   新しいブラウザ ウィンドウが開きます。 ブラウザ ウィンドウで、認証に使用する資格情報を入力または選択します。

5. Visual Studio Code ターミナルウィンドウで出力を確認します。

   ターミナルの下部で、WhoAmIResponse 複合型 に期待される値 WhoAmI 関数 を見つけます。 次のように見えるはずです。

   {
   "@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId": "639dea3c-505c-4c3a-b8b5-d916cb507e1e",
   "UserId": "d2159662-498a-406b-83cd-f515b7e561d6",
   "OrganizationId": "83e197ed-ede1-4886-81f2-f41fe9395297"
   }
   

6. ターミナル ウィンドウで、cls と入力して、端末のコンテンツをクリアします。

7. F5 を押すか、Visual Studio Code 実行 > デバッグ開始 メニューコマンドを使って、スクリプトを再度実行します。

   すでにログインしているため、ブラウザ ウィンドウは開きません。 スクリプトの編集と実行を続けて、さまざまなリクエストを試すことができます。

動作方法

このセクションでは、 試してみる セクション に含まれている PowerShell スクリプトの詳細を説明します。

認証

スクリプトは Az PowerShell モジュール Get-AzTenant コマンドを使用して、現在のユーザーに認可されたテナントを取得します。 ログインしていない場合、このコマンドはエラーを返します。 このスクリプトでは、-ErrorAction SilentlyContinue パラメータを指定するとエラーが無視され、何も返されません。

Get-AzTenant コマンドは何も返さないとき、スクリプトは Connect-AzAccount を使用して、対話型のブラウザ ウィンドウが開き、ログインするための資格情報を入力または選択できます。 Azure PowerShell への対話型ログインの詳細について または サービスプリンシパルで非対話型 の詳細を学びます。

最後に、スクリプトは Get-AzAccessToken コマンドと -ResourceUrl $environmentUrl を使用して PSAccessToken インスタンスを取得します。これには、Dataverse との認証に使用できる アクセス トークン である文字列 トークン プロパティが含まれています。

別の資格情報セットを使用して接続する場合は、Disconnect-AzAccount コマンドを使用する必要があります。

異なるシェル環境を使用して認証する

Azure PowerShell は、Windows PowerShell および PowerShell シェル環境を使用して動作しますが、Cmd と Bash シェル環境では動作しません。 Cmd または Bash シェル環境で認証する場合は、Azure CLI を使用できます。

このスクリプトは、Azure CLI コマンドを使用して認証します。

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## <a name="login-if-not-already-logged-in"></a>Login if not already logged in
if ($null -eq (az account tenant list  --only-show-errors)) {
   az login --allow-no-subscriptions | Out-Null
}
# <a name="get-token"></a>Get token
$token = az account get-access-token --resource=$environmentUrl --query accessToken --output tsv

この表は、同等の Az PowerShell および Azure CLI コマンドを示しています。

Az PowerShell	Azure CLI	説明
Get-AzTenant	az アカウントのテナント リスト	すでにログインしているかどうかを検出するためにテナントのリストを取得してみます
Connect-AzAccount	az login	Azure にログインするには
AzAccessToken を取得する	az アカウントのアクセストークンを取得する	アクセス トークンを取得するには
Disconnect-AzAccount	az ログアウト	Azureからログアウトする

WhoAmI 関数で Invoke-RestMethod を使用します

アクセス トークン を $token 変数に設定したら、Dataverse Web API へのリクエストを作成し、Invoke-RestMethod コマンドレット を使用して送信する必要があります

Set headers

すべての Dataverse Web API リクエストには、アクセス トークン 値を含む Authorization ヘッダーなど、共通の HTTP リクエスト ヘッダーのセットが含まれている必要があります。 一部の操作ではさらに多くのヘッダーが必要です。 Dataverse Web API 要求ヘッダーについての詳細

# <a name="common-headers"></a>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 パラメータを使用します。

# <a name="invoke-whoami-function"></a>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 プロパティのみをキャプチャしたい場合は、代わりに次のスクリプトを使用できます。

# <a name="get-userid"></a>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 またはキーボードの ファンクション ロック キーを押すか、キーボードでファンクション キーが有効になっていることを確認します。

代わりに、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."   } }

ブラウザ ウィンドウで選択したアカウントが、Dataverse パラメータで指定された $environmentUrl 環境にアクセスできるアカウントであることを確認してください。

以前に使用したものとは異なる資格情報のセットを使用している場合は、ターミナル ウィンドウで Disconnect-AzAccount コマンドを使用します。

警告: TenantId '<your tenant 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.

この警告が表示された場合は無視してください。 これらのリクエストにはサブスクリプションは必要ありません。

次の手順

PowerShell を使用して生産性を高めるための高度な機能と、Dataverse Web API を使用した Visual Studio Code について学習します。たとえば、次の方法があります。

• 再利用可能な関数を作成する
• 例外処理
• Dataverse サービス保護の制限を管理する
• Fiddler を使用したデバッグ
• Dataverse Web API CSDL $metadata ドキュメントをダウンロードする

PowerShell と Visual Studio Code と Dataverse Web API を使用する

PowerShell を使用して Dataverse Web API リクエストを認証して送信できるようになったので、他の Web API 操作を試すことができます。

サービス ドキュメントを理解することで、Dataverse Web API 機能の詳細を学びます。

Web API の種類および操作