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

ナビゲーション プロパティの値として定義することで、相互に関連するエンティティを作成することができます。 これを ディープ挿入 と言います。 この方法には、2 つの利点があります。 より効率的に複数の簡単な作成および関連付け操作を 1 つの結合した操作に置き換えられます。 またこれは、アトミックで、操作全体が成功しすべての関連オブジェクトが作成される場合、または操作が失敗し何も作成されない場合に表示されます。

基本的な作製と同様に、応答 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 Function を使用して、テーブル間にリレーションシップのマッピングが存在する既存のレコードのコンテキスト内にレコードを新規作成することができます。 これらのマッピングの作成については、以下を参照してください。

注意

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

これは 2 ステップのプロセスです。 InitializeFrom 関数はレコードを作成しませんが、元のレコードからマップされた指定されたプロパティ値を使用して新しいレコードを作成するために使用できるデータを返します。 InitializeFrom で返された応答データを必要な変更と統合し、次に、新しいレコードを作成するためのデータを POST します。

次の例は、accountid00000000-0000-0000-0000-000000000001 と等しい既存の取引先企業レコードの値を使用して取引先企業レコードを作成する方法を示しています。

ステップ 1: InitializeFrom を使用してデータを取得する

要求

GET [Organization URI]/api/data/v9.0/InitializeFrom(EntityMoniker=@p1,TargetEntityName=@p2,TargetFieldType=@p3)?@p1={'@odata.id':'accounts(00000000-0000-0000-0000-000000000001)'}&@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(00000000-0000-0000-0000-000000000001)",
    "transactioncurrencyid@odata.bind": "transactioncurrencies(732e87e1-1d96-e711-80e4-00155db75426)",
    "address1_line1": "123 Maple St.",
    "address1_city": "Seattle",
    "address1_country": "United States of America"
}

ステップ 2 - 新しいレコードを作成する

InitializeFrom 関数から受けとった応答は、ソース テーブルとターゲット テーブル間でマッピングされた列と親レコードの GUID で構成されます。 リレーションシップがあるテーブル間の列マッピングは、別のテーブルでは異なり、カスタマイズできるため、InitializeFrom 関数要求からの応答は別の組織では異なる可能性があります。

次の例に示すように、他のプロパティ値を 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(00000000-0000-0000-0000-000000000001)",
        "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 分かかります。 個人データは収集されません (プライバシー ステートメント)。