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

注意

エンティティとテーブルの違いがわかりませんか? Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

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

Web API URL およびバージョン

Web API にアクセスするには、次の表にある部分を使用して URL を構成する必要があります。

部分 説明
プロトコル https://
環境名 環境に適用される一意の名前。 会社名が Contoso である場合、contoso となる可能性があります。
地域 環境は通常、地理的に近いデータ センターで利用できます。
北米: crm
南米: crm2
カナダ: crm3
ヨーロッパ、中東、およびアフリカ (EMEA): crm4
アジア太平洋地域 (APAC): crm5
オセアニア: crm6
日本: crm7
インド: crm8
北米 2: crm9
英国: crm11
フランス: crm12
新しいデータ センター領域が開かれるにつれて、より多くの値が追加されます。
基本 URL dynamics.com.
Web API パス Web API へのパスは /api/data/ です。
[バージョン] バージョンは次のように表記されます: v[Major_version].[Minor_version][PatchVersion]/。 このリリースの有効なバージョンは v9.1 です。
リソース 使用するエンティティ (テーブル) の名前、機能、またはアクションです。

使用する URL は次のコンポーネントで構成されます: プロトコル + 環境名 + 地域 + 基本 URL + Web API パス + バージョン + リソース。 上記の表に記載されているこれらの値は、ブラウザを Power Apps ポータル に移動して見つけることができ、上部のツールバーの設定 (歯車) アイコンを選択し、メニューで 開発者向けリソース を選びます。

バージョン互換性

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

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

注意

v8.xの小さいリリースとは違い、将来のバージョンに追加される新しい機能またはそのほかの変更は以前のバージョンに適用されません。 使用しているバージョンを変更したら、コードを使用するおよびテストするサービスのバージョンに注意を払う必要があります。

HTTP メソッド

HTTP 要求では、さまざまなメソッドを適用できます。 Web API を使用する場合、次の表に記載されているメソッドのみを使用します。

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

HTTP ヘッダー

OData プロトコルでは JSON と ATOM の両方の形式を使用できますが、Wb API では JSON のみがサポートされています。 したがって、次のヘッダーは適用可能です。

すべての要求には、Accept ヘッダー値として application/json を含める必要があります。予期される応答がない場合でも、含める必要があります。 応答でエラーが返される場合、エラーは JSON として返されます。 このヘッダーが含まれていなくてもコードは動作しますが、ベスト プラクティスとしてこのヘッダーを含めることが推奨されます

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

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

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

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

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

Content-Type: application/json  

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

  • エンティティに対して作成 (POST) または更新 (PATCH) 操作でデータを返すには、return=representation 基本設定を含めます。 この基本設定を POST リクエストに適用する場合、正常な応答として、201 (Created) というステータスが表示されます。 PATCH リクエストの場合は、正常な応答として、200 (OK) というステータスが表示されます。 この基本設定を適用しない場合、既定では応答の本文メッセージにはデータが返されないことを反映して、両方の操作に対して、204 (No Content) というステータスが返されます。

  • クエリで書式設定された値を返すには、Prefer ヘッダーを使用して odata.include-annotations プリファレンスを Microsoft.Dynamics.CRM.formattedvalue に設定して含めます。 詳細: 書式設定値を含める

  • また、Prefer ヘッダーと odata.maxpagesize オプションを使用して、返されるページ数を指定することもできます。 詳細: ページに戻すエンティティ (テーブル) 数を指定する

  • 別のユーザーを偽装するには (呼び出し元がこれを行う権限を持っている場合)、 CallerObjectId ヘッダーと、偽装する対象となるユーザーの Azure Active Directory オブジェクト ID 値を追加します。 このデータは SystemUser テーブル/エンティティ AzureActiveDirectoryObjectId属性 (列) にあります。 詳細情報: Web API を使用して別のユーザーを偽装する

  • オプティミスティック同時実行を適用するには、If-Match ヘッダーと Etag 値を適用できます。 詳細: オプティミスティック同時実行の適用

  • upsert 操作でエンティティを実際に作成または更新するかどうかを制御するために、If-Match および If-None-Match ヘッダーを使用することもできます。 詳細: テーブル (エンティティ) の Upsert

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

  • ソリューション コンポーネントを作成し、それをソリューションに関連付ける場合は、MSCRM.SolutionUniqueName 要求ヘッダーを使って、値をソリューションの一意の名前に設定します。

  • 新しいエンティティ レコードを作成するときに重複データ検出を有効にする場合、MSCRM.SuppressDuplicateDetection 要求ヘッダー値を false に設定します。 詳細: 重複レコードの確認

  • カスタム プラグイン コードをバイパスする必要があり、呼び出し元が prvBypassCustomPlugins 権限を持っている場合、MSCRM.BypassCustomPluginExecution 要求ヘッダーを true に設定します。 詳細: カスタム ビジネス ロジックを回避する

ステータス コードの確認

http 要求が成功したか失敗したかにかかわらず、応答にはステータス コードが含まれます。 Microsoft Dataverse Web API で返されるステータス コードには、次が含まれます。

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

- AccessDenied
- AttributePermissionReadIsMissing
- AttributePermissionUpdateIsMissingDuringUpdate
- AttributePrivilegeCreateIsMissing
- CannotActOnBehalfOfAnotherUser
- CannotAddOrActonBehalfAnotherUserPrivilege
- CrmSecurityError
- InvalidAccessRights
- PrincipalPrivilegeDenied
- PrivilegeCreateIsDisabledForOrganization
- PrivilegeDenied
- unManagedinvalidprincipal
- unManagedinvalidprivilegeedepth
クライアント エラー
401 承認されていません 次のような種類のエラーの場合に発生します。

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

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

- CannotDeleteDueToAssociation
- InvalidOperation
- NotSupported
クライアント エラー
412 前提条件失敗 次のような種類のエラーの場合に発生します。

- ConcurrencyVersionMismatch
- DuplicateRecord
クライアント エラー
429 リクエストが多すぎます API 制限を超えた場合に発生します。 詳しくは:サービス保護APIの制限を参照してください。 クライアント エラー
501 実装されていません 要求した何らかの操作が実装されていない場合に発生します。 サーバー エラー
503 サービスは利用できません これは 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>"  
 }  
}  

重要

エラーメッセージの構造が変更しています。 この変更は、2020 年 8 月から 2020 年 10 月にかけて、さまざまな地域に展開される予定です。

この変更前は、返されたエラーは次の形式でした。

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>",  
  "innererror": {  
   "message": "<A message describing the error, this is frequently the same as the outer message>",  
   "type": "Microsoft.Crm.CrmHttpException",  
   "stacktrace": "<Details from the server about where the error occurred>"  
  }  
 }  
}  

弊社はエラーメッセージの innererror プロパティを削除しています。 このプロパティの解析が必要なコードはすべて削除する必要があります。

OData エラー応答ガイダンス状態 "この内部エラーの名前と値のペアは、情報開示に関する潜在的なセキュリティの懸念から保護するために、開発環境でのみ使用しなければなりません"。 このガイダンスに合わせるために、弊社ではこのプロパティを削除しています。

この変更がデプロイされた後、使用しているアプリケーションがこのプロパティに依存していることが判明した場合は、サポートに連絡して、環境の変更を一時的に削除するように要求できます。 これは、アプリケーション開発者がこの依存関係を削除するために適切な変更を行う時間を提供します。

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

一部のエラーには、注釈 を使用して追加の詳細を含めることができます。 リクエストに 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."
    }
}

この応答には、次の注釈が含まれています:

注釈および説明 Value
@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 を使用してこの値を渡すには、tag クエリ オプションを使用します。

例: ?tag=This is a value passed.

webhook を使用して送信した場合、SharedVariables コレクション内で次の値になります。

{
"key": "tag",
"value": "This is a value passed."
}

これは、組織サービスを使用して実行することもできます :組織サービスから共有変数を追加する

関連項目

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

注意

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

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