Web API を使用してエンティティ レコードを作成する

注意

2020 年 11 月発効:

  • Common Data Service は Microsoft Dataverse に名称が変更されました。 詳細情報
  • Microsoft Dataverse に関して、用語を一部変更しています。 たとえば、エンティティテーブル に、フィールド に変わりました。 詳細情報

この記事は間もなく更新され、最新の用語が反映されます。

POST 要求を使用してエンティティを作成するデータを送信します。 deep insert を使用して 1 回の操作で複数の関連するエンティティ レコードを作成できます。 また、@odata.bind コメントを使用して、新しいエンティティ レコードを既存のエンティティに関連付ける値の設定方法も知っておく必要があります。

注意

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

基本的な作成

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

要求


POST [Organization URI]/api/data/v9.0/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: [Organization URI]/api/data/v9.0/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

新しいエンティティ レコードを作成するには、有効なプロパティの名前と型を識別する必要があります。 すべてのシステム エンティティと属性の詳細については、エンティティの参照について にある、そのエンティティのトピックでこの情報を見つけることができます。 ユーザー定義エンティティまたは属性については、CSDL $metadata ドキュメント にあるそのエンティティの定義を参照してください。 詳細: エンティティの種類

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

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

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

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

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

要求


POST [Organization URI]/api/data/v9.0/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": "[Organization URI]/api/data/v9.0/$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"
}

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

基本的な作製と同様に、応答 OData-EntityId ヘッダーには、作製したエンティティの URI が含まれています。 作成された関連するエンティティの URI は返されません。 Prefer: return=representation ヘッダを使用すると、レコードの主キーの値を取得できるので、作成したレコードの値が返されます。 詳細情報 : 返されたデータで作成する

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

  • 取引先担当者が作成されます。これは、取引先担当者が単一値のナビゲーション プロパティ primarycontactid のオブジェクト プロパティとして定義されているためです。

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

  • タスクが作成されます。これは、タスクが、コレクション値を持つナビゲーション プロパティ Opportunity_Tasks の値に設定された配列内のオブジェクトとして定義されているためです。

要求

POST [Organization URI]/api/data/v9.0/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: [Organization URI]/api/data/v9.0/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

作成時にエンティティ レコードを関連付ける

新しいエンティティが作成された際に、既存のエンティティに新しいエンティティを関連付けるには、@odata.bind コメントを使用してナビゲーション プロパティの値を設定する必要があります。

accounts のエンティティ セットに投稿された以下の要求本文は、contactid の値が 00000000-0000-0000-0000-000000000001 の既存の連絡先と、activityid の値が 00000000-0000-0000-0000-00000000000200000000-0000-0000-0000-000000000003 の2つの既存のタスクに関連付けられた新しいアカウントを作成します。

注意

このリクエストは Prefer: return=representation のヘッダーを使用しているため、作成されたレコードの値を返します。 詳細情報 : 返されたデータで作成する

要求


POST [Organization URI]/api/data/v9.0/accounts?$select=name&$expand=primarycontactid($select=fullname),Account_Tasks($select=subject) HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: return=representation

{
    "name": "Sample Account",
    "primarycontactid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
    "Account_Tasks@odata.bind": [
        "/tasks(00000000-0000-0000-0000-000000000002)",
        "/tasks(00000000-0000-0000-0000-000000000003)"
    ]
}

回答


HTTP/1.1 201 Created
OData-Version: 4.0
Preference-Applied: return=representation

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#accounts(name,primarycontactid(fullname),Account_Tasks(subject))/$entity",
    "@odata.etag": "W/\"36236432\"",
    "name": "Sample Account",
    "accountid": "00000000-0000-0000-0000-000000000004",
    "primarycontactid": {
        "@odata.etag": "W/\"28877094\"",
        "fullname": "Yvonne McKay (sample)",
        "contactid": "00000000-0000-0000-0000-000000000001"
    },
    "Account_Tasks": [
        {
            "@odata.etag": "W/\"36236437\"",
            "subject": "Task 1",
            "activityid": "00000000-0000-0000-0000-000000000002"
        },
        {
            "@odata.etag": "W/\"36236440\"",
            "subject": "Task 2",
            "activityid": "00000000-0000-0000-0000-000000000003"
        }
    ]
}

重複レコードの確認

既定では、Web API を使用したレコードの作成時には重複データ検出が実行されません。 重複データ検出を有効にするには、POST 要求に MSCRM.SuppressDuplicateDetection: false ヘッダを含める必要があります。 重複データ検出は、組織が重複データ検出を有効にし、エンティティが重複データ検出に対応しており、アクティブな重複データ検出ルールが適用されている場合にのみ適用されます。 詳細: コードを使用した重複データの検出

作成操作中に重複データを検出する方法の詳細については、「Web API を使用した重複データの検出」を参照してください。

別のエンティティから新しいエンティティ レコードを作成する

InitializeFrom 関数を使用して、レコードが属するエンティティ間にマッピングが存在する既存のレコードのコンテキストで新たなレコードを作成します。

次の例では、c65127ed-2097-e711-80eb-00155db75426 と等しい値の accountid を持つ取引先企業エンティティの既存レコードの属性値を使用して、取引先企業レコードを作成する方法を示します。

要求

GET [Organization URI]/api/data/v9.0/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?@p1={'@odata.id':'accounts(c65127ed-2097-e711-80eb-00155db75426)'}&@p2='account'&@p3=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate' HTTP/1.1
If-None-Match: null
OData-Version: 4.0
OData-MaxVersion: 4.0
Content-Type: application/json
Accept: application/json

回答

{
    "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
    "@odata.type": "#Microsoft.Dynamics.CRM.account",
    "parentaccountid@odata.bind": "accounts(c65127ed-2097-e711-80eb-00155db75426)",
    "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
    "address1_line1": "123 Maple St.",
    "address1_city": "Seattle",
    "address1_country": "United States of America"
}

InitializeFrom の要求で受信した応答は、送信元エンティティと送信先エンティティの間にマッピングされた属性の値と、親レコードの GUID で構成されます。 エンティティの関連付けを持つエンティティ間の属性マッピングは、エンティティ セットごとに異なり、カスタマイズ可能であるため、 InitializeFrom の関数要求からの応答は、エンティティや組織ごとに異なる可能性があります。 この応答が新しいレコードの作成要求のボディに渡されるとき、これらの属性値は新しいレコードで複製されます。 カスタム マッピングした属性の値も、プロセス中に新しいレコード内のセットを取得します。

注意

二つのエンティティをマッピング可能かどうか判断するには、このクエリを使用します。
GET [Organization URI]/api/data/v9.1/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

また、以下の例に示すように、他の属性値を JSON 要求のボディ内に追加することにより、新しいレコードのために他の属性値をセットしたり修正したりすることができます。

POST [Organization URI]/api/data/v9.0/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    {
        "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts/$entity",
        "@odata.type": "#Microsoft.Dynamics.CRM.account",
        "parentaccountid@odata.bind": "accounts(c65127ed-2097-e711-80eb-00155db75426)",
        "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
        "name":"Contoso Ltd",
        "numberofemployees":"200",
        "address1_line1":"100 Maple St.",
        "address1_city":"Seattle",
        "address1_country":"United States of America",
        "fax":"73737"
    }
}

関連項目

Web API 基本操作のサンプル (C#)
Web API 基本操作のサンプル (クライアント側の JavaScript)
InitializeFrom Function
Web API を使用して演算を実行する
HTTP 要求の作成とエラーの処理
Web API を使用したクエリ データ
Web API を使用してエンティティを取得する
Web API を使用したエンティティの更新と削除
Web API を使用したエンティティの関連付けと関連付け解除
Web API 関数の使用
Web API アクションの使用
Web API を使用してバッチ操作を実行する
Web API を使用して別のユーザーを偽装する
Web API を使用する条件付き演算を実行する

注意

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

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