Create a table row using the Web API

文章
06/28/2022
3 分鐘後閱讀

Note

Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

Use a POST request to send data to create a table row (entity record). You can create multiple related table rows in a single operation using deep insert. You also need to know how to set values to associate a new table row to existing tables using the @odata.bind annotation.

Note

For information about how to create and update the table (entity) definitions using the Web API, see Create and update table definitions using the Web API.

Basic Create

This example creates a new account entity record. The response OData-EntityId header contains the Uri of the created entity.

Request


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
}

Response


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(7eb682f1-ca75-e511-80d4-00155d2a68d1)

To create a new entity record you must identify the valid property names and types. For all system entities and attributes (table columns), you can find this information in the topic for that entity in the About the Table Reference. For custom entities or attributes, refer to the definition of that entity in the CSDL $metadata document. More information: Web API EntityTypes

Create with data returned

You can compose your POST request so that data from the created record will be returned with a status of 201 (Created). To get this result, you must use the return=representation preference in the request headers.

To control which properties are returned, append the $select query option to the URL to the entity set. You may also use $expand to return related entities.

When an entity is created in this way the OData-EntityId header containing the URI to the created record is not returned.

This example creates a new account entity and returns the requested data in the response.

Request


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
}

Response


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

You can create entities related to each other by defining them as navigation properties values. This is known as deep insert. This approach has two advantages. It is more efficient, replacing multiple simpler creation and association operations with one combined operation. Also, it is atomic where either the entire operation succeeds and all the related objects are created, or the operation fails and none are created.

As with a basic create, the response OData-EntityId header contains the Uri of the created entity. The URIs for the related entities created aren't returned. You can get the primary key values of the records if you use the Prefer: return=representation header so it returns the values of the created record. More information: Create with data returned

For example, the following request body posted to the accounts entity set will create a total of four new entities in the context of creating an account.

A contact is created because it is defined as an object property of the single-valued navigation property primarycontactid.
An opportunity is created because it is defined as an object within an array that is set to the value of a collection-valued navigation property opportunity_customer_accounts.
A task is created because it is defined an object within an array that is set to the value of a collection-valued navigation property Opportunity_Tasks.

Note

When creating a new table row, it is not possible to combine the row creation with the insert of a non-primary image. For a non-primary image to be added, the row must already exist.

Request

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

Response


HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.0/accounts(3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

Associate table rows on create

To associate new entities to existing entities when they are created you must set the value of navigation properties using the @odata.bind annotation.

The following request body posted to the accounts entity set will create a new account associated with an existing contact with the contactid value of 00000000-0000-0000-0000-000000000001 and two existing tasks with activityid values of 00000000-0000-0000-0000-000000000002 and 00000000-0000-0000-0000-000000000003.

Note

This request is using the Prefer: return=representation header so it returns the values of the created record. More information: Create with data returned

Request


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

Response


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

Check for duplicate records

By default, duplicate detection is suppressed when you are creating records using the Web API. You must include the MSCRM.SuppressDuplicateDetection: false header with your POST request to enable duplicate detection. Duplicate detection only applies when 1) the organization has enabled duplicate detection, 2) the entity is enabled for duplicate detection, and 3) there are active duplicate detection rules being applied. More information: Detect duplicate data using code

See Detect duplicate data using Web API for more information on how to check for duplicate records during Create operation.

Create a new record from another record

Use the InitializeFrom Function to create a new record in the context of an existing record where a mapping exists for the relationship between the tables. For information about creating these mappings, see:

Note

To determine whether two entities can be mapped, use this query:
GET [Organization URI]/api/data/v9.1/entitymaps?$select=sourceentityname,targetentityname&$orderby=sourceentityname

This is a two step process. The InitializeFrom function doesn't create the record, but it returns data you can use to create a new record with specified property values mapped from the original record. You will combine the response data returned in the InitializeFrom function with any changes you want to make and then POST the data to create the new record.

The following example shows how to create an account record using the values of an existing account record with accountid value equal to 00000000-0000-0000-0000-000000000001.

Step 1: Get the data using InitializeFrom

Request

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

Response

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

Step 2: Create the new record

The response received from InitializeFrom function consists of values of mapped columns between the source table and target table and the GUID of the parent record. The column mapping between tables that have an relationship is different for different tables and is customizable, so the response from InitializeFrom function request may vary for different organizations.

Other property values can also be set and/or modified for the new record by adding them in the JSON request body, as shown in the example below.

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

Create documents in storage partitions

If you are creating large numbers of entities that contain documents, you can create the entities in storage partitions to speed up access to those entity records.

More information: Access documents faster using storage partitions

Create a table row using the Web API

Basic Create

Create with data returned

Associate table rows on create

Check for duplicate records

Create a new record from another record

Step 1: Get the data using InitializeFrom

Step 2: Create the new record

Create documents in storage partitions

See also

意見反映

Create a table row using the Web API

Basic Create

Create with data returned

Create related table rows in one operation

Associate table rows on create

Check for duplicate records

Create a new record from another record

Step 1: Get the data using InitializeFrom

Step 2: Create the new record

Create documents in storage partitions

See also

意見反映