Web API を使用してテーブル行を作成する

注意

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

POST 要求を使用してテーブル行 (エンティティ レコード) を作成するデータを送信します。 詳細な挿入 を使用して、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 ドキュメント にあるそのエンティティの定義を参照してください。 詳細情報: Web API EntityTypes

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

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 ヘッダを含める必要があります。 重複データ検出は、1) 組織が重複データ検出を有効にし、2) エンティティが重複データ検出に対応しており、3) アクティブな重複データ検出ルールが適用されている場合にのみ適用されます。 詳細: コードを使用した重複データの検出

作成操作中に重複データを検出する方法の詳細については、「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 分かかります。 個人データは収集されません (プライバシー ステートメント)。