使用 Web API 创建表行

向 Web API 实体集资源发送请求 POST ，以在 Microsoft Dataverse 中创建表行（实体记录）。可以使用 深度插入在单个作中创建多个相关表行。还需要了解如何设置值，以使用 @odata.bind 批注将新表行与现有表相关联。

注释

有关如何使用 Web API 创建和更新表（实体）定义的信息，请参阅使用 Web API 创建和更新表定义。

基本创建

此示例创建新的帐户实体记录。 accounts 是帐户 EntityType 的实体集名称。响应 OData-EntityId 标头包含已创建的实体的 URI。

请求：


POST [Organization URI]/api/data/v9.2/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.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

若要创建记录，必须标识有效的实体集名称、属性名称和类型。

注释

在 Power Apps 中，查看表列表时，选择 “高级>工具”。选择 “复制集名称 ”以复制表的实体集名称。

还可以选择 表数据的 API 链接 ，在浏览器中查看前 10 行数据。如果安装了 JSON 格式化程序等浏览器扩展来设置返回的 JSON 文本数据的格式，此功能效果最佳。

实体集名称并不总是与表的集合名称或复数名称相同。它存储在名为 EntitySetName 的单独属性中。

创建新表行时，不能同时插入非主图像。若要添加非主映像，该行必须已存在。详细了解主要图像。

对于所有系统表和属性（表列），可以在 Web API 实体类型引用中该实体的文章中找到此信息。有关自定义表或列，请参阅 CSDL $metadata 文档中该表的定义。详细信息： Web API EntityTypes。

设置主键值

每个表都有一个唯一标识符主键列，你可以在创建行时指定该列。在大多数情况下，你应该允许系统为你设置此值，因为系统生成的值已针对最佳性能进行优化。

Dataverse 将主键数据存储在遥测中，以帮助维护服务。如果指定自定义的主键值，请不要在这些值中使用敏感信息。

通过使用弹性表，可以创建具有重复主键值和不同 partitionid 值的记录。但是，此模式与模型驱动型或画布型 Power Apps 不兼容。了解如何使用弹性表设置主键值。

使用返回的数据创建

你可以撰写 POST 请求，使其返回从创建的记录中提取的数据，状态为 201 (Created)。若要获取此结果，必须在请求标头中使用 return=representation 首选项。

若要控制返回哪些属性，请将 $select 查询选项追加到实体集的 URL。您还可以使用 $expand 来返回相关实体。

嵌套$expand在集合值导航属性return=representation上与首选项一起使用时，不能返回数据。有关详细信息，请参阅集合值导航属性的嵌套$expand。

使用此方法创建实体时， OData-EntityId 不会返回包含所创建记录的 URI 的标头。

以下示例创建一个新的帐户实体，并在响应中返回请求的数据。

请求：


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

在单个请求中创建多个记录

若要在单个请求中快速创建同一类型的多个记录，请使用 CreateMultiple 操作。在撰写本文时，并不是所有标准表都支持CreateMultiple操作，但所有弹性表都支持此操作。

有关详细信息，请参见:

通过使用标准表，可以通过将实体定义为导航属性值来创建相互关联的实体。此模式称为 深度插入。此方法有两个优点。它更高效，因为它用一个组合的原子操作替换了多个简单的创建和关联操作。原子操作要么完全成功，要么完全失败。

与基本创建一样，响应 OData-EntityId 标头包含已创建的实体的 URI。不会返回所创建相关实体的 URI。可以使用 Prefer: return=representation 头文件来获取记录的主键值，以便返回所创建记录的主键值。详细了解如何使用返回的数据创建记录。

例如，向实体集 accounts 提交的以下请求正文在创建帐户的过程中共创建四条记录。

创建联系人，并使用firstname和lastname值，因为你将其定义为名为primarycontactid的单值导航属性的对象属性。
创建了与帐户相关的机会，因为你将其定义为数组中的对象，该对象设置为名为 opportunity_customer_accounts集合值导航属性的值。
创建与机会相关的任务，因为您将其定义为数组对象，并将该对象设置为名为Opportunity_Tasks的集合值导航属性的值。

请求：

POST [Organization URI]/api/data/v9.2/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.2/accounts(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

在创建时关联表行

若要在创建新记录时将新记录与现有记录相关联，请使用 @odata.bind 批注设置导航属性的值。

发布到accounts实体集的以下请求正文创建了一个帐户，该帐户与现有联系人的值00000000-0000-0000-0000-000000000001相关，并且与两个具有值00000000-0000-0000-0000-000000000002和00000000-0000-0000-0000-000000000003的现有任务相关联。

此请求使用 Prefer: return=representation 标头，以便返回所创建记录的值。有关详细信息，请参阅 “使用返回的数据创建”。

请求：


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

检查重复记录

默认情况下，系统在创建记录时取消重复检测。若要启用重复检测，请将 MSCRM.SuppressDuplicateDetection: false 标头包含在请求 POST 中。仅当以下条件为 true 时，才会应用重复检测：

组织已启用重复检测。
实体已启用重复检测。
应用活动重复检测规则。

有关详细信息，请参见:

从另一条记录创建记录

使用 InitializeFrom 函数在已映射的表关系的上下文中，从现有记录中创建新记录。有关创建这些映射的信息，请参阅：

若要确定是否可以映射两个实体，请使用以下查询：

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

从另一条记录创建新记录的过程分为两步。首先，使用 InitializeFrom 函数返回从原始记录映射的属性值。然后，将 InitializeFrom 函数中返回的响应数据与要进行的任何更改以及 POST 要创建记录的数据组合在一起。

下面的示例展示了如何使用一个现有的帐户记录（其accountid值等于00000000-0000-0000-0000-000000000001）的值来创建一个新的帐户记录。

步骤 1：使用 InitializeFrom 获取数据

请求：

GET [Organization URI]/api/data/v9.2/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.2/$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.2/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.2/$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 进行条件操作

反馈

此页面是否有帮助？

Last updated on 2026-03-11

通过

使用 Web API 创建表行

基本创建

设置主键值

使用返回的数据创建

在单个请求中创建多个记录

在一次操作中创建相关表行

在创建时关联表行

检查重复记录

从另一条记录创建记录

步骤 1：使用 InitializeFrom 获取数据

步骤 2：创建新记录

在存储分区中创建文档

另请参阅

反馈

其他资源