HTTP 要求の作成とエラーの処理

  • [アーティクル]

HTTP 要求を作成および送信することによって、Web API を操作します。 適切な HTTP ヘッダーの設定方法を理解し、応答にエラーが含まれている場合は、エラーを処理する必要があります。

Web API URL およびバージョン

環境の Web API URL を見つけるには:

  1. Power Apps にサインインしてから、右上隅で環境を選択します。

  2. 右上隅の設定ボタンを選択してから、開発者リソースを選択します。

    開発者リソース メニュー

    ここから、Web API エンドポイントの値をコピーできます。 詳細: 開発者リソースの表示

次の表に、URL の部分を説明します。

部分 説明設定
プロトコル https://
Environment Name 環境に適用される一意の名前。 会社名が Contoso である場合、contoso となる可能性があります。
Region 環境は通常、お住いの地理的に近いデータ センターで利用できます。 北米の場合は crm です。 南米の場合は crm2、日本の場合は crm7 です。 完全なリストについては、データセンター リージョン を参照してください
ベース URL これは通常 dynamics.com. ですが、一部のデータセンターでは異なる値を使用しています。 データ センターのリージョンを参照してください。
Web API パス Web API へのパスは /api/data/ です。
Version バージョンは次のように表記されます: v[Major_version].[Minor_version][PatchVersion]/。 現在のバージョンは v9.2 です。
リソース テーブルの EntitySetName、または使用する関数やアクションの名前です。

使用する URL は次の部分で構成されています。

プロトコル + 環境名 + リージョン + ベース URL + Web API パス + バージョン + リソース。

URL の最大長

許容される URL の最大長は 32 KB (32768 文字) です。 これは、FetchXml を使うクエリのような非常に長い文字列クエリ パラメーターが必要な、一部の GET 操作を除くほとんどの種類の要求に対して適切である必要があります。 $batch 要求の本文内に要求を送信する場合、最大で 64KB (65,536 文字) URL のある要求を送信できます。 $batch 要求内で FetchXml の送信についての詳細.

バージョン互換性

このリリースでは以前のバージョンでは使用できない機能を導入しています。 それ以降のマイナー バージョンにはより多くの機能が提供されることがありますが、以前のマイナー バージョンに遡っては追加されません。 v9.0 を対象として作成したコードは、URL で v9.0 を参照する場合には将来のバージョンでも引き続き機能します。

新しい機能が導入されると、以前のバージョンと競合する可能性があります。 これらの破壊的変更は、サービスがより良いパフォーマンスをするために必要です。 通常は、機能はバージョン間で変わりませんが、変わらないのが当然だと考えるべきではありません。

注意

v8.x のマイナー リリースとは異なり、将来のバージョンに追加される新しい機能、またはその他の変更は以前のバージョンに適用されません。 使用しているバージョンを変更したら、コードを使用およびテストするサービスのバージョンに注意してください。

HTTP メソッド

次の表に、Dataverse Web API で使用できる HTTP メソッドを示します。

メソッド 使い方
GET 関数を呼び出すときを含め、データを取得するときに使用します。 取得が成功した場合に期待されるステータス コードは、200 OK です。
POST エンティティを作成するとき、またはアクションを呼び出すときに使用します。
PATCH エンティティを更新するとき、または upsert 操作を実行するときに使用します。
DELETE エンティティまたはエンティティの個々のプロパティを削除するときに使用します。
PUT エンティティの個々のプロパティを更新するために、限られた状況で使用します。 このメソッドは、ほとんどのエンティティを更新する場合には推奨できません。 テーブル定義を更新するときに PUT を使用します。 詳細: テーブル定義のある Web API を使用する

HTTP ヘッダー

すべての HTTP 要求には、少なくとも以下のヘッダーを含める必要があります。

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

OData プロトコルでは JSON と ATOM の両方の形式を使用できますが、Web API では JSON のみがサポートされています。 すべての要求には、Accept ヘッダー値として application/json を含める必要があります。予期される応答がない場合でも、含める必要があります。 応答でエラーが返される場合、エラーは JSON として返されます。 このヘッダーが含まれていなくてもコードは動作しますが、ベスト プラクティスとしてこのヘッダーを含めることが推奨されます

現在の OData バージョンの 4.0 ですが、今後のバージョンで新機能が使用できるようになる可能性があります。 将来コードに適用される OData バージョンについてのあいまいさをなくすため、現在の OData バージョンとコードに適用する最大バージョンを表す明示的なステートメントを必ず含める必要があります。 4.0 の値に設定された OData-Version と OData-MaxVersion の両方を使用します。

コレクション値ナビゲーション プロパティを展開するクエリは、最新の変更を反映しないそれらのプロパティのキャッシュされたデータを返すことがあります。 Web API要求のブラウザのキャッシュを上書きするためには、要求の本体に If-None-Match: null ヘッダーを含めます。 詳細: HTTP/1.1 ハイパーテキスト トランスファー プロトコル (HTTP/1.1) : 条件要求 3.2: If-None-Match。

要求本文に JSON データが含まれるすべての要求に、application/json を値に持つ Content-Type ヘッダーを含める必要があります。

Content-Type: application/json

その他のヘッダーを使用して特定の機能を有効にすることができます。

Prefer ヘッダー

以下の値を持つ Prefer ヘッダーを使用して、設定を指定できます。

Prefer 値 説明設定
return=representation エンティティに対して作成 (POST) または更新 (PATCH) 操作でデータを返すには、この基本設定を使用します。 この基本設定を POST 要求に適用する場合、正常な応答として、201 Created というステータスが表示されます。 PATCH 要求の場合は、正常な応答として、200 OK. というステータスが表示されます。この基本設定を適用しない場合、既定では応答の本文メッセージにはデータが返されないことを反映して、両方の操作に対して、204 No Content というステータスが返されます。 詳細情報: 返されたデータで作成する & 返されるデータでの更新
odata.include-annotations 注釈の要求 を参照してください
odata.maxpagesize この基本設定を使用して、クエリで返すページ数を指定します。 詳細情報: ページの結果
odata.track-changes 変更の追跡機能を使用することで、データが最初に抽出された後、あるいはデータが最後に同期された後で変更されたデータを検出し、データの同期を効率的に維持することができます。 詳細については: 変更の追跡を使用して、データを外部システムと同期する
respond-async 要求は非同期に処理されるべきだと指定します。 詳細: バックグラウンド操作 (プレビュー)

注意

カンマ区切り値を使用して、複数の Prefer ヘッダーを指定できます。例: Prefer: respond-async,odata.include-annotations="*"

注釈の要求

Prefer: odata.include-annotations 要求ヘッダーを使用して結果とともに返される、さまざまな OData 注釈データを要求できます。 注釈をすべて返すか、特定の注釈を指定するかを選択できます。 次のテーブルに、Dataverse Web API が対応している注釈を示します。

注釈 Description
OData.Community.Display.V1.FormattedValue アプリケーションで使用できる書式設定した文字列値を返します。 詳細情報: 書式設定された値
Microsoft.Dynamics.CRM.associatednavigationproperty
Microsoft.Dynamics.CRM.lookuplogicalname		 関連する検索列に関する情報を返します。 詳細情報: 検索プロパティ データ
Microsoft.Dynamics.CRM.totalrecordcount
Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded		 $count クエリ オプションを使用すると、@odata.count 注釈でレコード数を確認できますが、一度に返されるのは 5000 件のレコードのみです。 Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded に要求し、クエリと一致するレコードの総数が 5000 件を超えるかどうかを示すブール値を取得します。 詳細情報: 行数をカウントする
Microsoft.Dynamics.CRM.globalmetadataversion この注釈は要求で返され、アプリケーションでキャッシュできます。 スキーマの変更が発生すると、アプリケーションがキャッシュしたスキーマ データを更新することが必要な場合があることを示し値に変化します。 詳細情報: スキーマ データのキャッシュ
Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus
Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode
Microsoft.PowerApps.CDS.HelpLink
Microsoft.PowerApps.CDS.TraceText
Microsoft.PowerApps.CDS.InnerError.Message		 これらの注釈は、エラーが返された場合の詳細を提供します。 詳細: エラーのある追加の詳細を含める

特定の注釈のみが必要な場合は、コンマ区切り値として要求できます。 また、ワイルドカードとして '*' 文字を使用できます。 たとえば、次の Prefer 要求ヘッダーは、形式設定された値と追加のエラー詳細注釈のみを含みます。

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

ヒント

すべての注釈を返すには、ただ Prefer: odata.include-annotations="*" 要求ヘッダーを使用するのが一般的です。

その他のヘッダー

ヘッダー 価値 Description
CallerObjectId ユーザー Microsoft Entra ID オブジェクト ID 呼び出し元がそうする権限を持っている場合、このヘッダーを使用して別のユーザーを偽装します。 なりすますユーザーの Microsoft Entra ID Object ID に値を設定します。 このデータは、ユーザー (SystemUser) テーブル/エンティティ の AzureActiveDirectoryObjectId 属性 (列) にあります。 詳細情報: Web API を使用して別のユーザーを偽装する
If-Match Etag 値
または *		 このヘッダーを使用してオプティミスティック同時実行を適用し、レコードを取得した後に他のユーザーがサーバーに適用した変更を上書きしないようにします。 詳細: オプティミスティック同時実行の適用および If-Match
このヘッダーを * と同時に使用し、PATCH 層さがレコードを作成しないようにすることもできます。 詳細: upsert での作成の阻止
If-None-Match null
または *		 このヘッダーは、HTTP ヘッダー で説明されているように、値 null を持つすべてのリクエストで使用する必要がありますが、POST 操作が更新を実行しないようにするためにも使用できます。 詳細: upsert での更新の阻止および If-None-Match
MSCRM.SolutionUniqueName ソリューションの一意名 ソリューション コンポーネントを作成し、それをアンマネージド ソリューションに関連付ける場合は、このヘッダーを使用します。 詳細情報: Web API を使用してテーブルの定義を作成・更新する
MSCRM.SuppressDuplicateDetection false このヘッダーを値 false とともに使用し、レコードの作成または更新時に重複データ検出を有効にします。 詳細: 重複レコードの確認
MSCRM.BypassCustomPluginExecution true カスタム プラグイン コードをバイパスする必要があり、呼び出し元が prvBypassCustomPlugins 権限を持っている場合、このヘッダーを使用します。 詳細: カスタム ビジネス ロジックを回避する
Consistency Strong キャッシュされたアイテムの最新バージョンが必要な場合は、このヘッダーを使用します。 キャッシュされたアイテムには、メタデータ定義、ラベル、ユーザー権限、およびチーム権限が含まれます。 たとえば、一部のメタデータ定義、ラベル、またはアクセス許可に変更を適用し、変更から 30 秒以内に最新の定義を使用する必要があるコードがある場合、このヘッダーを使用して最新バージョンを確実に取得できます。 このヘッダーを使用することでパフォーマンスがわずかに低下するため、常に使用することはしないでください。

バッチ操作を実行する場合、要求では本文で送信される部分ごとに多数の異なるヘッダーを適用する必要があります。 詳細: Web API を使用してバッチ操作を実行する。

ステータス コードの確認

HTTP 要求が成功したか失敗したかにかかわらず、応答にはステータス コードが含まれます。 次の表で、Microsoft Dataverse Web API が返すステータス コードについて説明します。

コード Description タイプ
200 OK この応答コードは操作で応答本文にデータが返されるときに発生します。 Success
201 Created エンティティの POST 操作が成功し、要求に return=representation 基本設定を指定した場合は、この状態コードが発生します。 Success
204 No Content この状態コードは操作が成功した際に発生しますが、応答本文ではデータが返されません。 Success
304 Not Modified この状態コードは、エンティティが最後に取得されてから以降に変更されたかどうかをテストするときに発生します。 詳細: 条件付き検索 リダイレクト
403 Forbidden この状態コードは次のような種類のエラーの場合に発生します。

- AccessDenied
- AttributePermissionReadIsMissing
- AttributePermissionUpdateIsMissingDuringUpdate
- AttributePrivilegeCreateIsMissing
- CannotActOnBehalfOfAnotherUser
- CannotAddOrActonBehalfAnotherUserPrivilege
- CrmSecurityError
- InvalidAccessRights
- PrincipalPrivilegeDenied
- PrivilegeCreateIsDisabledForOrganization
- PrivilegeDenied
- unManagedinvalidprincipal
- unManagedinvalidprivilegeedepth		 クライアント エラー
401 Unauthorized この状態コードは次のような種類のエラーの場合に発生します。

- BadAuthTicket
- ExpiredAuthTicket
- InsufficientAuthTicket
- InvalidAuthTicket
- InvalidUserAuth
- MissingCrmAuthenticationToken
- MissingCrmAuthenticationTokenOrganizationName
- RequestIsNotAuthenticated
- TamperedAuthTicket
- UnauthorizedAccess
- UnManagedInvalidSecurityPrincipal		 クライアント エラー
413 Payload Too Large この状態コードは要求の長さが長すぎるときに発生します。 クライアント エラー
400 BadRequest この状態コードは引数が無効である場合に発生します。 クライアント エラー
404 Not Found この状態コードはリソースが存在しない場合に発生します。 クライアント エラー
405 Method Not Allowed このエラーは、メソッドとリソースの組み合わせが正しくない場合に発生します。 たとえば、DELETE や PATCH をエンティティのコレクションに対して使用することはできません。

次のような種類のエラーの場合に発生します。

- CannotDeleteDueToAssociation
- InvalidOperation
- NotSupported		 クライアント エラー
412 Precondition Failed この状態コードは次のような種類のエラーの場合に発生します。

- ConcurrencyVersionMismatch
- DuplicateRecord		 クライアント エラー
429 Too Many Requests この状態コードは、API 制限を超えた場合に発生します。 詳しくは：サービス保護APIの制限を参照してください。 クライアント エラー
501 Not Implemented この状態コードは、一部の要求の操作が実装されていない場合に発生します。 サーバー エラー
503 Service Unavailable この状態コードは、Web API サービスを使用できない場合に発生します。 サーバー エラー

応答からのエラーの解析

エラーに関する詳細は、応答で次のような JSON 形式で含まれています。

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}

エラーのある追加の詳細を含める

一部のエラーには、注釈 を使用して追加の詳細を含めることができます。 要求に Prefer: odata.include-annotations="*" ヘッダーが含まれている場合、応答にはすべての注釈が含まれ、エラーに関する詳細と、エラーの具体的なガイダンスに導く URL が含まれます。

これらの詳細の一部は、プラグインを作成する開発者が設定できます。たとえば、InvalidPluginExecutionException(OperationStatus, Int32, String) コンストラクターを使用してエラーをスローするプラグインがあるとします。 このコンストラクターにより、OperationStatus 値、カスタム整数エラー コード、およびエラー メッセージを渡すことができます。

単純なプラグインは次のようになります:

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

このプラグインがアカウント エンティティのメッセージ作成時に登録され、アカウント作成の要求に odata.include-annotations="*" 基本設定が含まれている場合は、要求と応答は次の例のようになります。

要求:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.1/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

応答:

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

次の表では、応答内の注釈について説明します。

注釈および説明 価値
@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus
InvalidPluginExecutionException(OperationStatus, Int32, String) コンストラクターによって設定された OperationStatus の値。		 1
@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode
InvalidPluginExecutionException(OperationStatus, Int32, String) コンストラクターによって設定された SubErrorCode の値。		 12345
@Microsoft.PowerApps.CDS.HelpLink
エラーの対処方法についてのガイダンスにリダイレクトする 可能性のある エラーの詳細を含む URL。		 http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform
@Microsoft.PowerApps.CDS.TraceText
ITracingService.Trace(String, Object[]) メソッドを使用してプラグイン トレース ログに書き込まれるコンテンツ。 プラグインの作成者が記録したため、この注釈にはプラグインのスタックトレースが含まれます。		 [MyNamespace: MyNamespace.MyClass ]
[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass :Create of account]

Entering MyClass plug-in.
StackTrace:
at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)
@Microsoft.PowerApps.CDS.InnerError.Message
InnerError にある例外のエラー メッセージ。 このメッセージは、内部でのみ使用される特定の特殊な場合を除いて、エラー メッセージと同じです。		 Example Error Message.

注意

@Microsoft.PowerApps.CDS.HelpLink がすべてのエラーのガイダンスを提供するとは限りません。 ガイダンスは、事前に提供される場合がありますが、一般的には、リンクが使用される頻度に基づいて提供されます。 リンクを使用してください。 ガイダンスが提供されていない場合は、リンクを使用すると、ユーザーがエラーに関するガイダンスをより必要としていることを追跡できます。 ユーザーが最も必要とするエラーのガイダンスを含めることを優先させることができます。 リンクは、ドキュメント、コミュニティ リソースへのリンク、または外部サイトなどのリソースに導くかもしれません。

応答ですべての注釈を受け取りたくない場合は、受け取る注釈を指定できます。 Prefer: odata.include-annotations="*" を使用する代わりに以下の値を使用して、エラーが発生した場合にデータとヘルプリンクを取得する操作のフォーマットされた値のみを受け取ることができます: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink"。

詳細情報: 注釈の要求

Web API から共有変数を追加する

SharedVariables コレクションの ExecutionContext 内のプラグインが利用できる文字列の値を設定できます。 詳細情報:

参照

Web API を使用して演算を実行する
Web API を使用したデータのクエリ
Web API を使用してテーブル行を作成する
Web API を使用してテーブルの行を取得する
Web API を使用したテーブル行の更新と削除
Web API を使用したテーブル行の関連付けと関連付け解除
Web API 関数の使用
Web API アクションの使用
Web API を使用してバッチ操作を実行する
Web API を使用して別のユーザーを偽装する
Web API を使用する条件付き演算を実行する

注意

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

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