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

[アーティクル]
02/01/2024

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 を使用して使うに移動して詳細を確認してください。

この記事の手順は 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+N で新しいファイルを開きます。

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

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

$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 スクリプトであることを自動的に検出する必要があります。

$environmentUrl 変数値 (https://yourorg.crm.dynamics.com/) を Dataverse 環境 URL と一致するように編集します。
F5 を押すか、Visual Studio Code実行 > デバッグ開始 メニューコマンドを使います。

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

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"
}

ターミナルウィンドウで、cls と入力して、端末のコンテンツをクリアします。
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 について学習します。たとえば、次の方法があります。

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

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

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

Web API の種類および操作

Share via

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

前提条件

以下をインストールするか、インストールされていることを確認する

インストールを検証する

さらに必要なこと

試用する

動作方法

認証

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

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

Set headers

要求を送信する

トラブルシューティング

`F5` を押しても何も起こりません

そのようなホストは知られていません

ユーザーが組織のメンバーではありません

警告: TenantId '<your tenant id>' には複数のアクティブなサブスクリプションが含まれています

次の手順

フィードバック

その他のリソース

Share via

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

前提条件

以下をインストールするか、インストールされていることを確認する

インストールを検証する

さらに必要なこと

試用する

動作方法

認証

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

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

Set headers

要求を送信する

トラブルシューティング​​

F5 を押しても何も起こりません

そのようなホストは知られていません

ユーザーが組織のメンバーではありません

警告: TenantId '<your tenant id>' には複数のアクティブなサブスクリプションが含まれています

次の手順

フィードバック

その他のリソース

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

トラブルシューティング

`F5` を押しても何も起こりません