Web API を使用してエンティティを作成する

[アーティクル]
10/31/2017

公開日: 2017年1月

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

POST 要求を使用して、エンティティを作成するデータを送信します。 "ディープ挿入" を使用して 1 回の操作で複数の関連するエンティティを作成できます。また、@odata.bind 注釈を使用して既存のエンティティに新しいエンティティを関連付けるために値を設定する方法を知る必要があります。

注意

Web API を使用したエンティティメタデータの作成と更新の方法については、Web API を使用してエンティティ定義を作成および更新を参照してください。

このトピックの内容

基本的な作成

1 回の操作で関連するエンティティを作成する

作成時にエンティティを関連付ける

返されるデータで作成する

基本的な作成

この例では、新しい取引先企業エンティティを作成します。応答 OData-EntityId ヘッダーには、作成したエンティティの URI が含まれています。

要求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

新しいエンティティを作成するには、有効なプロパティの名前と型を識別する必要があります。すべてのシステムエンティティと属性について、「Web API EntityType Reference」にあるそのエンティティのトピックで、この情報を見つけることができます。ユーザー定義エンティティまたは属性については、d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdlにあるそのエンティティの定義を参照してください。詳細:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_entityTypes

1 回の操作で関連するエンティティを作成する

ナビゲーションプロパティの値として定義することで、相互に関連するエンティティを作成することができます。これをディープ挿入と言います。

基本的な作成と同様に、応答 OData-EntityId ヘッダーには、作成したエンティティの Uri が含まれています。作成された関連するエンティティの URI は返されません。

たとえば、Account エンティティセットに投稿された次の要求本文は、アカウントの作成のコンテキストで合計 4 つの新しいエンティティを作成します。

取引先担当者が作成されます。これは、取引先担当者が単一値のナビゲーションプロパティ primarycontactid のオブジェクトプロパティとして定義されているためです。
営業案件が作成されます。これは、営業案件が、コレクション値を持つナビゲーションプロパティ opportunity_customer_accounts の値に設定された配列内のオブジェクトとして定義されているためです。
タスクが作成されます。これは、タスクが、コレクション値を持つナビゲーションプロパティ Opportunity_Tasks の値に設定された配列内のオブジェクトとして定義されているためです。

要求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "John",
     "lastname": "Smith"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

作成時にエンティティを関連付ける

新しいエンティティを作成するときに、新しいエンティティを既存のエンティティに関連付けるには、@odata.bind 注釈を使用して、単一値ナビゲーションプロパティの値を設定する必要があります。

取引先企業エンティティセットに投稿された次の要求本文は、00000000-0000-0000-0000-000000000001 の値を持つ contactid を使用して、既存の取引先担当者に関連付けられた新しい取引先企業を作成します。

要求

POST cc_WebAPI_ServiceURI/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
"name":"Sample Account",
"primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"
}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000002)

注意

コレクション値を持つナビゲーションプロパティを使用してこの方法でエンティティを関連付けることは、Web API ではサポートされていません。

返されるデータで作成する

注意

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

POST 要求を作成すると、作成されたレコードのデータは 201 (Created) のステータスで返されます。結果を取得するには、要求のヘッダーで return=representation の基本設定を使用する必要があります。

どのプロパティが返されるかを制御するには、$select クエリオプションを URL に、そしてエンティティセットに追加します。$expand クエリオプションは、使用すると無視されます。

エンティティがこのように作成されると、作成されたレコードへの URL を含む OData-EntityId ヘッダーは返されません。

この例では、新しい取引先企業エンティティを作成し、応答で必要なデータを返します。

要求

POST cc_WebAPI_ServiceURI/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

応答

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536530\"",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Sample Account",
    "createdon": "2016-09-28T22:57:53Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Web API を使用してエンティティを作成する

このトピックの内容

基本的な作成

1 回の操作で関連するエンティティを作成する

作成時にエンティティを関連付ける

返されるデータで作成する

関連項目

その他のリソース