次の方法で共有

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

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

Web API URL およびバージョン

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

  1. Power Apps にサインインし、右上隅にある環境を選択します。

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

    Power Apps の設定の [開発者向けリソース] メニューのスクリーンショット。

    ここから、Web API エンドポイントの値をコピーできます。 詳細については、「 開発者向けリソースの表示」を参照してください。

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

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

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

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

URL の最大長

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

OData セグメントの最大長

OData 要求内の個々のセグメントの最大長は 260 文字です。 OData 要求の 1 つのセグメントの長さが 260 文字を超える場合、要求は 400 Bad Request - Invalid URLを返します。 セグメントは URL の "リソース" 部分であり、エンドポイントとインライン パラメーターを記述するために必要なすべての文字が含まれています。

たとえば、要求が api/data/v9.2/MyApi(MyParameter='longvalue')されている場合、 MyApi(MyParameter='longvalue') は 260 文字を超えることはできません。 OData 関数では常にパラメーター エイリアスを使用します。 たとえば、関数を /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' と構成すると、セグメントを MyApi(MyParameter=@alias) だけに短縮できます。 Web API 関数でのパラメーター エイリアスの使用の詳細について説明します。

バージョン互換性

このリリースでは、以前のバージョンではサポートされていない機能が導入されています。 それ以降のマイナー バージョンでは、以前のマイナー バージョンではサポートされていないより多くの機能が提供される場合があります。 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 のみがサポートされています。 すべての要求には、応答本文が予期されていない場合でも、application/json のAccept ヘッダー値を含める必要があります。 Web API は、応答内のエラーを JSON として返します。 このヘッダーが含まれていない場合でもコードは機能しますが、ベスト プラクティスとして含めます。

現在の OData バージョンは 4.0 ですが、今後のバージョンでは新しい機能が導入される可能性があります。 コードに適用される OData バージョンに関するあいまいさがないように、常に現在の OData バージョンと最大バージョンの明示的なステートメントを含めます。 OData-Version と OData-MaxVersion の両方のヘッダーを 4.0 の値に設定してください。

コレクション値ナビゲーション プロパティを展開するクエリは、最近の変更を反映しないプロパティのキャッシュ データを返す場合があります。 Web API要求のブラウザのキャッシュを上書きするためには、要求の本体に If-None-Match: null ヘッダーを含めます。 詳細については、「 ハイパーテキスト転送プロトコル (HTTP/1.1): 条件付き要求 3.2 : If-None-Match」を参照してください。

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

Content-Type: application/json

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

優先ヘッダー

設定を指定するには、次の値で 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 が対応している注釈を示します。

注釈 説明
OData.Community.Display.V1.FormattedValue アプリケーションで使用できる書式設定した文字列値を返します。 詳細情報: 書式設定された値
Microsoft.Dynamics.CRM.associatednavigationproperty
Microsoft.Dynamics.CRM.lookuplogicalname		 関連する検索列に関する情報を返します。 詳細情報: ルックアップ プロパティ データ と 複数テーブル参照
Microsoft.Dynamics.CRM.totalrecordcount
Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded		 $count クエリ オプションを使用すると、@odata.count注釈によってレコードの数が示されますが、一度に返すことができる標準テーブル レコードは 5,000 個のみです。 エラスティック テーブルの場合、ページ サイズの制限は 500 です。 クエリに一致するレコードの合計数が、使用しているテーブルの種類の最大ページ サイズ制限を超えているかどうかを示すブール値を取得するには、 Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded 注釈を要求します。 詳細情報: 行数をカウントする
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="*" 要求ヘッダーを使用します。

その他のヘッダー

ヘッダー 価値 説明
CallerObjectId ユーザー Microsoft Entra ID オブジェクト ID 呼び出し元がそうする権限を持っている場合、このヘッダーを使用して別のユーザーを偽装します。 なりすます対象のユーザーの Microsoft Entra ID Object ID に値を設定します。 このデータは、ユーザー (SystemUser) テーブル/エンティティAzureActiveDirectoryObjectId 属性 (列) にあります。 詳細情報: Web API を使用して別のユーザーを偽装する。
If-Match Etag 値
または *		 このヘッダーを使用してオプティミスティック同時実行を適用し、レコードを取得した後に他のユーザーがサーバーに適用した変更を上書きしないようにします。 詳細情報: オプティミスティック コンカレンシー と If-Match を適用します。
このヘッダーを * と同時に使用して、PATCH 操作がレコードを作成しないようにすることもできます。 詳細情報: アップサートでの作成を禁止します。
If-None-Match null
または *		 このヘッダーは、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 が返すステータス コードについて説明します。

Code 説明 タイプ
200 OK このステータスコードは、操作によって応答本文にデータが返されるときに予期されます。 成功
201 Created エンティティの POST 操作が成功し、要求に return=representation 基本設定を指定した場合は、この状態コードが発生します。 成功
204 No Content この状態コードは操作が成功した際に発生しますが、応答本文ではデータが返されません。 成功
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.2/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
OperationStatus InvalidPluginExecutionException(OperationStatus, Int32, String)コンストラクターによって設定された の値。		 1
@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode
SubErrorCode の値は InvalidPluginExecutionException(OperationStatus, Int32, String) コンストラクターによって設定されたものです。		 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 から共有変数を追加する

ExecutionContext コレクション内のSharedVariables内のプラグインで使用できる文字列値を設定できます。 詳細については、以下を参照してください:

参照

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

  • Last updated on