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

[アーティクル]
02/01/2024

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

注意

Web API を使用してテーブル (エンティティ) 定義を作成および更新する方法については、Web API を使用してテーブル定義を作成および更新するを参照してください。

基本的な作成

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

要求:


POST [Organization URI]/api/data/v9.0/accounts
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)

レコードを作成するには、有効なエンティティセット名、プロパティ名、および型を識別する必要があります。すべてのシステムテーブルと属性 (テーブル列) については、Web API エンティティタイプ参照のそのエンティティの記事でこの情報を確認することができます。ユーザー定義テーブルまたは列については、CSDL $metadata ドキュメントにあるそのテーブルの定義を参照してください。詳細情報: Web API EntityTypes

主キー値の設定

各テーブルには、行を作成するときに指定できる一意の識別子主キー列があります。ほとんどの場合、システムによって生成された値は最良なパフォーマンスに最適化されているため、システムがこの属性を設定できるようにする必要があります。

エラスティックテーブルを使用すると、重複する主キー値と異なる partitionid 値を持つレコードを作成できます。ただし、このパターンはモデル駆動型またはキャンバス Power Apps と互換性がありません。エラスティックテーブルを使用した主キー値の設定について学習します

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

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

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

コレクション値ナビゲーションプロパティで入れ子になった $expand は、return=representation の基本設定で使用した場合、データを返しません。詳細情報: コレクション値のナビゲーションプロパティで入れ子になった $expand

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

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

要求:


POST [Organization URI]/api/data/v9.0/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon
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
}

応答:


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

1 つの要求で複数のレコードを作成する

1 つの要求で同じタイプの複数のレコードを作成する最も速い方法は、CreateMultiple アクションを使用することです。 CreateMultiple アクションの作成時点。すべての標準テーブルがこのアクションをサポートしているわけではありませんが、すべてのエラスティックテーブルはサポートしています。

詳細情報:

標準テーブルを使用して、ナビゲーションプロパティの値として定義することで、相互に関連するエンティティを作成することができます。このパターンを ディープ挿入 と言います。この方法には、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
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-000000000002 と 00000000-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)
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 ヘッダーを含めて、重複データ検出を有効にする必要があります。重複データ検出は、次の条件が当てはまる場合にのみ適用されます:

組織で重複検知を有効にしました。
重複検出が可能なエンティティです。
アクティブな重複データ検出ルールが適用されます。

詳細情報:

別のレコードからレコードを作成する

InitializeFrom 関数を使用して、テーブル間にリレーションシップのマッピングが存在する既存のレコードのコンテキスト内にレコードを新規作成することができます。これらのマッピングの作成については、以下を参照してください。

二つのエンティティをマッピング可能かどうか判断するには、このクエリを使用します:

GET [Organization URI]/api/data/v9.1/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

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

次の例は、accountid が 00000000-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'
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
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 関数
 Web API を使用して演算を実行する
 HTTP 要求の作成とエラーの処理
 Web API を使用したデータのクエリ
 Web API を使用してテーブルの行を取得する
 Web API を使用したテーブル行の更新と削除
 Web API を使用したテーブル行の関連付けと関連付け解除
 Web API 関数の使用
 Web API アクションの使用
 Web API を使用してバッチ操作を実行する
 Web API を使用して別のユーザーを偽装する
 Web API を使用する条件付き演算を実行する

注意

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

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

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

基本的な作成

主キー値の設定

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

1 つの要求で複数のレコードを作成する

作成時にテーブル行を関連付ける

重複レコードの確認

別のレコードからレコードを作成する

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

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

ストレージパーティション内のドキュメントを作成する

参照

フィードバック

その他のリソース

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

基本的な作成

主キー値の設定

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

1 つの要求で複数のレコードを作成する

1 回の操作で関連するテーブル行を作成する

作成時にテーブル行を関連付ける

重複レコードの確認

別のレコードからレコードを作成する

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

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

ストレージ パーティション内のドキュメントを作成する

参照

フィードバック

その他のリソース

ストレージパーティション内のドキュメントを作成する