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

  • [アーティクル]

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

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

このトピックの内容

Web API URL およびバージョン

HTTP メソッド

HTTP ヘッダー

ステータス コードの確認

応答からのエラーの解析

Web API URL およびバージョン

Web API にアクセスするには、次の表にあるコンポーネントを使用して URL を構成する必要があります。

アイテム

内容

プロトコル

適切なプロトコルは、https:// または http:// です。

基本 URL

通常はこの URL を使用して Web アプリケーションを開きます。

  • Microsoft Dynamics 365 (オンライン) の場合: <tenant name>.crm.dynamics.com を使用します。

  • インターネットに接続する展開 (IFD) の場合: インスタンスに適した URL を使用します。 次のとおりです: <organization name>.<domain name>。

  • Dynamics 365 (設置型) の場合: <server name>/<organization name> を使用します。

Web API パス

Web API へのパスは /api/data/ です。

バージョン

バージョンは次のように表記されます: v[Major_version].[Minor_version][PatchVersion]/。 このリリースの有効なバージョンは次のとおりです。

  • v8.0/: Microsoft Dynamics CRM Online 2016 更新プログラム 0.1 と Microsoft Dynamics CRM 2016 更新プログラム 0.1

  • v8.1/: Microsoft Dynamics CRM Online 2016 更新プログラム 1 と Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ for Dynamics 365 用 2016 年 12 月の更新プログラム (オンラインおよび設置型)

このリリースでは、対応する更新プログラムまたはサービス パックを適用しているかぎり、使用する特定の値は重要ではありません。 詳細: バージョン互換性

リソース

使用するエンティティの名前、機能、またはアクション。

使用する URL は次のコンポーネントで構成されます: プロトコル + 基本 URL + Web API パス + バージョン + リソース。

バージョン互換性

このリリースでは、各更新プログラムまたはサービス パックで多くの追加的な変更が適用されました。 これらの更新プログラムが適用されると、それ以降のマイナー バージョンにも同じ機能が追加されます。 そのため、バージョン 8.2 を使用できる場合は、バージョン 8.1 および 8.0 にも同じ機能があります。 これは、すべての変更が追加的であるため、または Microsoft Dynamics 365 Web API の制限 に記載されている項目を対象としたバグ修正であるため可能となっています。 大きな変更は行われていません。

注意

次のメジャー バージョン (v9) では、そのバージョンを使用する場合にのみ利用できる機能が含まれています。 それ以降のマイナー バージョンには追加機能が提供されるかもしれませんが、以前のマイナー バージョンには遡って適用されない可能性があります。 v8.x を対象として作成したコードは、使用する URL で v8.2 を参照すると v9.x でも引き続き機能します。

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-Version および OData-MaxVersion ヘッダーの両方を使用します。

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

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

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

Content-Type: application/json

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

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

    注意

    この機能は Dynamics 365 用 2016 年 12 月の更新プログラム (オンラインおよび設置型) を使用して追加されました。

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

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

  • 別のユーザーを偽装するには (呼び出し元がこれを行う権限を持っている場合)、MSCRMCallerID ヘッダーと、偽装する対象となるユーザーの systemuserid 値を追加します。詳細:Web API を使用して別のユーザーを偽装する。

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

  • POST 要求について重複データ検出を有効にするには、MSCRM.SuppressDuplicateDetection: false ヘッダーを使用できます。詳細:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

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

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

ステータス コードの確認

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

コード

内容

種類​​

200 OK

操作で応答本文にデータが返されるときに発生します。

成功

201 Created

エンティティの POST 操作が成功し、要求に return-representation 基本設定を指定した場合は、これが発生します。

注意

この機能は Dynamics 365 用 2016 年 12 月の更新プログラム (オンラインおよび設置型) を使用して追加されました。

成功

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

クライアント エラー

500 Internal Server Error

エンティティを作成する POST 要求で重複データ検出が有効化であり、作成するエンティティが重複している場合に、これが期待されます。詳細:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

サーバー エラー

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>", "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>" } } }

関連項目

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

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権