次の方法で共有


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

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 を使用 する」を参照して、次のような生産性を向上させる高度な機能について学習します。

この記事の手順は Windows、Linux、および macOS で動作するはずですが、これらの手順は Windows でのみテストされています。 変更が必要な場合は、この記事の下部にある フィードバック セクションを使用してお知らせください。

[前提条件]

次の各前提条件が満たされていることを確認せずに続行しないでください。

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

インストールを検証する

  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+選択して新しいファイルを開きます。

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

  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
    $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 スクリプトが自動的に検出されます。

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

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

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

  5. 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"
    }
    
  6. ターミナル ウィンドウで、「 cls 」と入力して、ターミナルの内容をクリアします。

  7. 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 コマンドレットUriMethod、および 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-LockFn 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 を使用して生産性を高める高度な機能について説明します。次のような方法があります。

PowerShell を使用して Dataverse Web API 要求を認証して送信する機能が得たので、他の Web API 操作を試すことができます。

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