Dataverse Web API で Insomnia を使用する

[アーティクル]
05/09/2024

Microsoft Dataverse 環境を認証して Web API 要求を作成して送信できるようにするクライアント API ツールは多数あります。これらのツールを使用すると、Dataverse Web API を使用して、アドホッククエリについて学び、テストし、実行するのが容易になります。

この記事には 2 つの目的があります。

マイクロソフトが提供するすべての Dataverse 環境用に事前に承認された Microsoft Entra アプリケーション (クライアント) ID を持つ Insomnia API クライアントを使用して Dataverse を認証し、接続する戦略を提示する。つまり、Dataverse Web API の使用を開始するためにアプリケーションを登録する必要はありません。
Insomnia API クライアントのコンテキストで Dataverse Web API を使用して実行できるいくつかの基本的なデータ操作を紹介します。このようにして、Insomnia を使用して実験を続け、Dataverse Web API について学ぶことができます。

プライバシー

クライアント API ツールを使用して送信する要求には、機密情報が含まれる可能性があります。多くの開発者は、この情報がクラウドサービスにアップロードされることを望んでいません。

Insomnia ローカルスクラッチパッドでは、アカウントを作成する必要はなく、送信した要求に関する情報は保存されません。ここで提供される手順では、Insomnia ローカルスクラッチパッドの使用方法のみを説明します。必要に応じて、アカウントを作成して、Insomnia のすべての機能を使用することもできます。アカウントを作成するオプションがなく、プライバシーに重点を置いたバージョンが必要な場合は、Insomnium を参照してください。

注意

Visual Studio Code を使って PowerShell を使用して、Insomnia か他の API クライアントへの認証として Dataverse Web API で認証します。 PowerShell と Visual Studio Code で Web API の使用を開始します。このメソッドは:

Azure AD アプリ登録を使用するため、アプリケーション (クライアント) ID を指定する必要はありません。
要求に関する情報はどこにも送信されません。

この記事の手順は、この記事が書かれた時点で Insomnia によって提供されたエクスペリエンスを表しています。ユーザーエクスペリエンスは時間の経過とともに変化する可能性があり、この記事は現在のエクスペリエンスに適合しない場合があります。この記事は、ここで説明されている手順を根本的になくす変更が発生した場合にのみ更新されます。詳細については、Insomnia のドキュメントをご覧ください

Insomnia をインストールする

Insomnia をインストールする手順に関する Insomnia 説明書を参照してください。手順は macOS、Windows、Linux で異なります。

Windows の場合、インストーラーはダウンロードして実行する実行可能ファイル (exe) です。インストールが完了すると、さまざまなオプションが提供される場合があります。これらのオプションは、この記事の手順に影響を与えるものではありませんが、変更される場合があります。この記事が書かれた時点では、次のオプションが提示されていました。

データをクラウドと同期する機能を有効にするオプションについては、ローカル Vault にローカルに保存し続けるを選択します。
アカウントを作成するオプションでは、ローカル Scratch Pad を使用する を選択します。 Insomnia Scratch Pad について詳しく見る

ベース環境の構成

Insomnia 環境を使用して環境変数を保存します。環境変数は、さまざまな目的で参照できるデータのキーと値のペアを含む JSON オブジェクトです。

ベース環境 は、すべてのワークスペースに割り当てられ、その中の変数はワークスペース全体からアクセスできます。

Insomnia を開いた後、ベース環境の横にある歯車アイコンを選択して、環境の管理 ダイアログを開きます。または、Ctrl + E のショートカットキーを使用できます。

次の JSON をコピーします。

{
   "url": "https://yourorg.api.crm.dynamics.com",
   "version": "9.2",
   "webapiurl": "{{ _.url }}/api/data/v{{ _.version }}/",
   "redirecturl": "https://localhost",
   "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{ _.url }}",
   "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
}

JSON をベース環境に貼り付けます。
url プロパティ値を編集し、Dataverse 環境の URL と一致する https://yourorg.api.crm.dynamics.com 値を置き換えます。

開発者リソースを表示するにある手順を使用して、環境の Web API エンドポイントを検索します。 Web API エンドポイント URL から /api/data/v9.2 を削除します。この URL は dynamics.com で終わる必要があります。

_.url 変数と _.version 変数への参照はすぐには解決されない可能性があるため、次のような警告が表示されます。

ただし、ウィンドウを閉じて再度開くと、変数が認識され、解決されたことがわかります。

サブ環境の作成 (オプション)

単一の Dataverse 環境にのみ接続する必要がある場合は、ベース環境のみを使用できます。複数の環境に接続する必要がある場合は、各 Dataverse 環境の*サブ環境* を作成できます。たとえば、開発およびテスト Dataverse 環境のサブ環境を作成できます。

ベース環境で実行した後、ベース環境の横にある歯車アイコンを選択して、環境の管理 ダイアログを開きます。または、Ctrl + E のショートカットキーを使用できます。
アイコンを選択して、新しい環境を作成します。環境は共有または プライベートにできます。 プライべート環境を選択します。
作成した 新しい環境 の名前をダブルクリックし、希望する名前に変更します。接続する Dataverse 環境の名前を使用するか、開発環境などの名前を使用します。

次の JSON をコピーします。

{
   "url": "https://yourdevorg.api.crm.dynamics.com"
}

JSON を作成した環境に貼り付けます。
基本環境の場合と同様に、url プロパティ値を編集して、他の環境の Web API エンドポイントを表します。

注意

サブ環境に url プロパティを含める必要があるだけです。サブ環境が選択されている場合、この値はベース環境で指定された url 値をオーバーライドします。必要に応じて、他の 5 つのプロパティのいずれかを含めることもできますが、url プロパティ値だけが Dataverse 環境ごとに異なります。

要求を構成する

ベース環境とサブ環境を構成したら、要求を構成する準備完了です。

新しい HTTP 要求 ボタンを選択するか Ctrl+N ショートカットキーを使用します。
HTTP メソッド、つまり既定の GET の後、_. を入力して少し待ちます。 Insomnia には、選択可能な変数の一覧が表示されます。
_.webapiurl 変数を選択します。 URL プレビュー フィールドには、選択した環境の url プロパティを使用した値が表示されます。
認証タブで、ドロップダウンを使用して OAuth 2.0 認証タイプを選択します。
作成した環境変数を使用して、次のテーブルに示すように認証構成を編集します。

フィールド価値

付与タイプ 暗黙

認証 URL _.authurl

クライアント ID _.clientid

リダイレクト URL _.redirecturl
送信を選択します。

環境の資格情報を入力するためのダイアログが開きます。

資格情報を入力すると、プレビュー ウィンドウで次のような結果が表示されます。
```
{
"@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
"value": [
   {
      "name": "aadusers",
      "kind": "EntitySet",
      "url": "aadusers"
   },
   {
      "name": "accounts",
      "kind": "EntitySet",
      "url": "accounts"
   },
   {
      "name": "aciviewmappers",
      "kind": "EntitySet",
      "url": "aciviewmappers"
   },
   {
      "name": "actioncards",
      "kind": "EntitySet",
      "url": "actioncards"
   },
   ...
```
この結果は、Web API サービスドキュメントです。 Web API サービス URL のルートに GET 要求を送信すると、サービスドキュメントを確認できます。 Dataverse 環境のすべてのテーブルのエンティティセット名が一覧表示されます。サービスドキュメントが表示されたら、Dataverse 環境に対する認証の成功です。

ヒント

これは、作業しているテーブルのエンティティセット名を検索または確認するのに便利な方法です。

フィールド	価値
付与タイプ	暗黙
認証 URL	`_.authurl`
クライアント ID	`_.clientid`
リダイレクト URL	`_.redirecturl`

CSDL $metadata ドキュメントを表示する

共通スキーマ定義言語 (CSDL) $metadata ドキュメントは、Web API に関連するすべての信頼できる情報源です。頻繁に参照することをお勧めします。

_.webapiurl 変数の後に $metadata?annotations=true を追加することで URL を編集します。 URL は、次である必要があります。

GET _.webapiurl $metadata?annotations=true
送信を選択します。

プレビュー ペインに、"5MB を超える応答はパフォーマンス上の理由から非表示になりました" というメッセージが表示され、ファイルに保存 と 表示するのオプションが表示されます。。ファイルは大きいですが、問題なくプレビューできます。

型の定義を検索する

CSDL $metadata ドキュメントは大きいです。 Insomnia プレビューでは、下部に応答フィルター処理ツールが提供されます。 XPath クエリを使用して応答をフィルター処理して、必要なものを見つけます。次のテーブルに 2 つの例を示します。

検索	XPath クエリ
すべてのエンティティの種類	`//*[local-name() = 'EntityType']`
アカウント EntityType	`//*[local-name() = 'EntityType'][@Name = 'account']`
すべての関数	`//*[local-name() = 'Function']`
WhoAmI 関数	`//*[local-name() = 'Function'][@Name = 'WhoAmI']`
すべてのアクション	`//*[local-name() = 'Action']`
CreateMultiple アクション	`//*[local-name() = 'Action'][@Name = 'CreateMultiple']`
複合型	`//*[local-name() = 'ComplexType']`
WhoAmIResponse 複合型	`//*[local-name() = 'ComplexType'][@Name = 'WhoAmIResponse']`
すべての列挙型	`//*[local-name() = 'EnumType']`
AccessRights 列挙型	`//*[local-name() = 'EnumType'][@Name = 'AccessRights']`

CSDL $metadata ドキュメントで定義されている種類の詳細について確認する

WhoAmI 要求を送信する

認証が完了したので、WhoAmI 関数を呼び出すように要求を変更します。 WhoAmI は関数であるため、GET メソッドを使用します。この関数にはパラメータがないので、簡単に使用できます。 Web API 関数の使用に関する詳細

_.webapiurl 変数の後に WhoAmI を追加することで URL を編集します。 URL は、次である必要があります。

GET _.webapiurl WhoAmI
要求ヘッダーを設定します。

HTTP ヘッダーで説明されているように、各 Web API 要求には特定の要求ヘッダーのセットが必要で、さまざまな動作に合わせてヘッダー値を変更する必要がある場合があります。

ヘッダー タブで、追加ボタンを選択して、次の共通ヘッダーをそれぞれ入力します。

ヘッダー価値

Accept application/json

OData-MaxVersion 4.0

OData-Version 4.0

If-None-Match null

Prefer odata.include-annotations="*"

これらのヘッダーは WhoAmI 関数の動作を変更しませんが、最初に追加することをお勧めします。

ヘッダー	価値
`Accept`	`application/json`
`OData-MaxVersion`	`4.0`
`OData-Version`	`4.0`
`If-None-Match`	`null`
`Prefer`	`odata.include-annotations="*"`

送信を選択します。

プレビュー ペインに、WhoAmIResponse 複合型に対応するデータが表示されます。

{
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId": "77164db8-dbc7-ee11-907a-00224803d046",
   "UserId": "e6b56e50-a3d5-ee11-9078-000d3a59a579",
   "OrganizationId": "100462a3-76cb-ee11-9075-00224806e300"
}

データの取得

Insomnia を使用してレコードを取得するには、リソースのエンティティセット名を設定する必要があります。

URL を変更して、_.webapiurl 変数の後に WhoAmI を削除し、アカウントエンティティタイプのエンティティセット名である accounts と置き換えます。 URL は、次である必要があります。

GET _.webapiurl accounts
パラメーター タブで、クエリのパラメーターを設定します。

追加ボタンを選択してパラメーターを個別に追加します。ただし、より簡単な 一括編集 オプションを選択することもできます。
1. 一括編集 オプションを選択します。
2. 次のパラメーターをコピーします。
```
$top: 3
$select: name,revenue,address1_city
$expand: primarycontactid($select=fullname)
$filter: address1_city eq 'Redmond'
```
このクエリは、レドモンド市にある上位 3 つの取引先企業レコードから選択された列を返し、取引先企業の取引先責任者として指定された関連する取引先担当者に関する情報が含まれます。
1. クエリパラメーター にこの値を貼り付けます。
  
  クエリは次のようになります。

送信を選択します。

プレビュー ペインで、次のような結果が表示されます。

{
"@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city,primarycontactid(fullname))",
"@Microsoft.Dynamics.CRM.totalrecordcount": -1,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
"@Microsoft.Dynamics.CRM.globalmetadataversion": "2341840",
"value": [
   {
      "@odata.etag": "W/\"2343103\"",
      "name": "City Power & Light (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
      "revenue": 100000.0,
      "address1_city": "Redmond",
      "accountid": "01eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Scott Konersmann (sample)",
      "contactid": "15eaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   },
   {
      "@odata.etag": "W/\"2343104\"",
      "name": "Contoso Pharmaceuticals (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$60,000.00",
      "revenue": 60000.0,
      "address1_city": "Redmond",
      "accountid": "03eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Robert Lyon (sample)",
      "contactid": "17eaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   },
   {
      "@odata.etag": "W/\"2343106\"",
      "name": "A. Datum Corporation (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
      "revenue": 10000.0,
      "address1_city": "Redmond",
      "accountid": "07eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Rene Valdes (sample)",
      "contactid": "1beaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   }
]
}

注意

WhoAmI 要求を送信するで設定された Prefer: odata.include-annotations="*" 要求ヘッダーは、すべての注釈を返すように設定されているため、これらの結果には、@OData.Community.Display.V1.FormattedValue などのたくさんの 注釈の値 を含まれます。特定の注釈を要求する方法について確認する

データのクエリ方法の詳細

レコードを作成する

Insomnia では、再利用できる複数の要求を定義できます。今ある構成を維持する新しい要求を作成する簡単な方法は、既存の要求を複製することです。このステップでは、データの取得セクションで定義された要求を複製し、レコードを作成するための新しい要求を作成します。

データの取得で作成した要求は、変更しない限り、既定の名前 新しい要求 になります。要求の名前を 取引先企業を取得に変更します。
取引先企業の取得 要求の上にマウスを移動し、ドロップダウンメニューを選択して複製を選択します。
要求の複製 ダイアログで、新しい名前 を 取引先企業の作成に設定します。
新しい 取引先企業の作成 要求で、HTTP メソッドを GET から POST に変更します。 URL は accounts エンティティセット名を使用するようにすでに設定されているため、ここで他に何も変更する必要はありません。 URL は、次である必要があります。

POST _.webapiurl accounts
パラメーター タブでは、作成操作には使用されないすべてのパラメーターを削除できます。
本文タブで、ドロップダウンを使用して テキスト グループから JSON を選択します。

次の JSON をコピーします。

{
   "name": "An Example Account record (sample)",
   "revenue": 10000.0,
   "address1_city": "Redmond"
}

本文フィールドに JSON を貼り付けます。

注意

送信を押してレコードを作成する前に、認証と ヘッダー タブのデータを確認してください。この要求は 取引先企業の取得 要求を複製して作成したため、以前に構成したすべての情報が再利用されます。
レコードを作成するには、送信をクリックします。

サービスが 204 コンテンツがありません を返したので、プレビュー ペインに表示するコンテンツがないことがわかります。

作成されたレコードの URL は、ヘッダー 一覧に表示されます。 odata-entityid 応答ヘッダーを検索する。値は、次のように表示されます。
```
https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
```
この URL には、作成されたレコードの主キーフィールド値 (この場合は accountid プロパティ値) が含まれています。

レコード作成の詳細情報

レコードを取得する

取引先企業レコードを作成し、主キーフィールドの値がわかったので、その値を使用してレコードを取得できます。まず、取引先企業の取得 要求を複製します。

取引先企業を取得要求を複製します。
取引先企業の取得と名前を付けます。
URL を編集して、エンティティセット名の後にかっこ内の accountid 値を追加します。レコードの作成で作成した取引先企業の accountid が 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 だった場合は、URL を次のように編集します。

GET _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
パラメーター タブで、$top、$expand、および $filter パラメーターを削除し、$select パラメーターのみを残して返される列の数を制限します。
ヘッダー タブで、Prefer ヘッダーの横のチェックボックスを選択して注釈が返されないようにします。

送信を選択します。

応答が 200 OKを返し、プレビュー ペインには次のようなデータが含まれている必要があります。

{
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city)/$entity",
   "@odata.etag": "W/\"2343128\"",
   "name": "An Example Account record (sample)",
   "revenue": 10000.0000000000,
   "address1_city": "Redmond",
   "accountid": "5b4ced1c-88e1-ee11-904c-6045bd05e9d4",
   "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
   "address1_composite": "Redmond"
}

レコード取得の詳細情報

レコードを削除する

主キー値を使用してレコードを作成して取得したので、レコードを削除できます。

取引先企業を取得要求を複製します。新しい要求に 取引先企業の削除 と名前を付けます。
HTTP メソッドを GET から DELETE に変更します。

URL には、以前に作成して取得したレコードの accountid を含むデータが含まれている必要があります。

DELETE _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)
削除操作には必要がないので、パラメーター タブで $select パラメーターを削除します。
送信を選択します。

サービスが 204 コンテンツがありません を返したので、プレビュー ペインに表示するコンテンツがないことがわかります。
取引先企業の取得 要求を今すぐ送信してみてください。404 お探しのページが見つかりませんでした が返され、プレビュー ペインに次のエラーが表示されます。
```
{
   "error": {
      "code": "0x80040217",
      "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
   }
}
```
取引先企業の取得 要求の Prefer のヘッダーをサイド有効にして、すべての注釈が返されるようにします。

要求を再度送信すると、多くの注釈が 404 お探しのページが見つかりませんでした の応答で返されることがわかります。

{
   "error": {
      "code": "0x80040217",
      "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionSourceKey": "Plugin/Microsoft.Crm.Common.ObjectModel.AccountService",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepKey": "81cbbb1b-ea3e-db11-86a7-000a3a5473e8",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiDepthKey": "1",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiActivityIdKey": "ef7da2d8-c3bc-40f3-b67f-9d2981341086",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiPluginSolutionNameKey": "System",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepSolutionNameKey": "System",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionCategory": "ClientError",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionMessageName": "ObjectDoesNotExist",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionHttpStatusCode": "404",
      "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040217&client=platform",
      "@Microsoft.PowerApps.CDS.InnerError.Message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
   }
}

問題は明らかであるため、これらの詳細はこのコンテキストでは役に立ちません。ただし、これらの詳細は他のシナリオで役立つ場合があります。エラーに詳細情報を含める方法を確認する

レコード削除に関する詳細情報

次の手順

Dataverse Web API で何ができるかについて詳細を確認する。

Web API タイプと操作について

Web API を使用して演算を実行する

注意

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

次の方法で共有

Dataverse Web API で Insomnia を使用する

プライバシー

Insomnia をインストールする

ベース環境の構成

サブ環境の作成 (オプション)

要求を構成する

CSDL $metadata ドキュメントを表示する

型の定義を検索する

WhoAmI 要求を送信する

データの取得

レコードを作成する

レコードを取得する

レコードを削除する

次の手順

その他のリソース