Dataverse Web API で Insomnia を使用する

多くの API クライアントツールを使用して、Microsoft Dataverse 環境に対する認証を行い、Web API 要求を作成して送信することができます。これらのツールを使用すると、Dataverse Web API を使用してアドホッククエリを簡単に学習、テスト、実行できます。

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

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

注意

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

プライバシー

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

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

その他のオプション

代わりに、Visual Studio Code で PowerShell を使用して Dataverse Web API で認証することもできます。 PowerShell と Visual Studio Code で Web API の使用を開始します。

Visual Studio Code を使用した PowerShell:

Azure AD アプリ登録を使用するため、アプリケーション (クライアント) ID を指定する必要はありません。
要求に関する情報はどこにも送信されません。
実行できる包括的な一連の Web API サンプルの開始点です。

Insomnia をインストールする

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

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

データをクラウドと同期する機能を有効にするオプションについては、ローカル Vault にローカルに保存し続けるを選択します。
アカウントを作成するオプションでは、ローカル 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 つのプロパティのいずれかを含めることもできますが、dataverse 環境ごとに異なるのは url プロパティ値だけです。

要求を構成する

基本環境とサブ環境を構成したら、要求を構成する準備が整います。

新しい 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 環境に対して正常に認証されました。

チップ

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

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

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

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

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

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

型の定義を検索する

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

検索	XPath クエリ
すべてのエンティティの種類	`//*[local-name() = '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 Functions の使用について詳しくは、こちらをご覧ください。

WhoAmI 変数の後に _.webapiurl を追加することで 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": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
   "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
   "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

データの取得

不眠症を使用してレコードを取得するには、リソースのエンティティセット名を設定します。

url を変更して、WhoAmI変数の後の_.webapiurlを削除します。これを、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 要求を送信する で設定された @OData.Community.Display.V1.FormattedValue 要求ヘッダーは、すべての注釈を返すように設定されているため、これらの結果には、Prefer: odata.include-annotations="*" などのたくさんの注釈の値を含まれます。特定の注釈を要求する方法について説明します。

データのクエリを実行する方法の詳細を確認します。

レコードを作成する

不眠症を使用すると、再利用できる複数の要求を定義できます。構成を保持する新しい要求を作成する簡単な方法は、既存の要求を複製することです。この手順では、[ データの取得 ] セクションで定義されている要求を複製し、レコードを作成する新しい要求を作成します。

データの取得で作成した要求は、変更しない限り、既定の名前 新しい要求 になります。要求の名前を アカウントを取得に変更します。
アカウントの取得 要求の上にカーソルを合わせ、ドロップダウンメニューを開き、複製を選択します。
要求の複製 ダイアログで、新しい名前をアカウントの作成に設定します。
新しい アカウント作成 要求で、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 Not Found が返され、[プレビュー] ウィンドウに次のエラーが表示されます。
```
{
   "error": {
      "code": "0x80040217",
      "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
   }
}
```
アカウント取得要求のヘッダーを再び有効にして、すべての注釈を返すようにします。

要求をもう一度送信します。 404 Not Found 応答で返される多くの注釈を確認できるようになりました。

{
   "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 を使用して演算を実行する

フィードバック

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

Last updated on 2026-03-14

次の方法で共有

Dataverse Web API で Insomnia を使用する

プライバシー

その他のオプション

Insomnia をインストールする

ベース環境の構成

サブ環境の作成 (省略可能)

要求を構成する

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

型の定義を検索する

WhoAmI 要求を送信する

データの取得

レコードを作成する

レコードを取得する

レコードを削除する

次の手順

フィードバック

その他のリソース