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

Visual Studio Code で Dataverse Web API で PowerShell を使用する方法について説明します。 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 への要求を作成します。

Note

このクイックスタートでは、基本的な概念のみを紹介します。この概要は、基本的なテストに十分です。この記事の手順を完了したら、 Dataverse Web API で PowerShell と Visual Studio Code を使用する方法など、生産性を高める高度な機能について学習します。

この記事の手順は 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
$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 スクリプトの詳細について説明します。

認証

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

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

最後に、このスクリプトでは、get-AzAccessToken コマンドと -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

Troubleshooting

「インストールの確認」の説明に従って、必要なすべてのプログラムがインストールされていることを確認してください。

次の状況により、このクイックスタートの手順が失敗する可能性があります。

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

F ロック、Fn ロック、またはファンクション ロックキーを押して、キーボードでファンクションキーが有効になっていることを確認します。

代わりに、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 Web API で PowerShell と Visual Studio Code を使用する

PowerShell を使用して Dataverse Web API 要求を認証して送信できるようになったので、他の Web API 操作を試してください。

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

Web API の種類と操作

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-28