通过

使用 Web API 更新和删除表行

修改数据的作是 Web API 的核心部分。 除基础更新和删除操作外，您可对单个表列（实体属性）执行操作，并组合 upsert 请求——该请求将根据数据是否存在执行更新或插入操作。

基本更新

更新操作使用 HTTP PATCH 动词。 传递一个 JSON 对象，其中包含要更新到表示记录的 URI 的属性。 如果更新成功，则返回状态为 204 No Content 的响应消息。

If-Match: * 标头可确保您不会因意外执行 upsert 操作而创建新记录。 更多信息：防止 upsert 操作创建记录。

重要

更新实体时，仅包括请求正文中正在更改的属性。 只需更新之前检索的实体的属性，并在请求中包括该 JSON，即使值相同，也会更新每个属性。 这可能触发系统事件，进而激活预期值已变更的业务逻辑。 这可能会导致属性似乎已在审核数据中更新，实际上它们实际上尚未更改。

更新 statecode 属性时，请务必始终设置所需的 statuscode属性。 statecode 并 statuscode 具有从属值。 给定 statecode 值可以有多个有效的 statuscode 值，但每个 statecode 列都配置了一个 DefaultStatus 值。 在不指定值statecode的情况下更新statuscode时，系统将设置默认状态值。 此外，当在表格和 statuscode 列上启用审核时，statuscode 列的更改值如果没有在更新操作中明确指定，则不会在审核数据中捕获。

注释

属性的定义包括一个 RequiredLevel 属性。 如果设置为此值 SystemRequired，则不能将这些属性设置为 null 值。 详细信息： 属性要求级别

此示例更新值为 000000000-0000-0000-0000-0000000000001 的现有帐户记录 accountid 。

请求：

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

响应：

HTTP/1.1 204 No Content  
OData-Version: 4.0

注释

有关在更新时关联和取消关联实体的信息，请参阅 使用单值导航属性 。

使用返回的数据进行更新

若要检索更新实体中的数据，可以编写 PATCH 请求，以便将创建的记录的数据返回，状态为 200 (OK)。 若要获取此结果，必须使用 Prefer: return=representation 请求标头。

若要控制返回的属性，请将 $select 查询选项追加到实体集的 URL。 如果使用 $expand 查询选项，该选项将被忽略。

此示例更新帐户实体，并在响应中返回请求的数据。

请求：

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$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
If-Match: * 
  
{"name":"Updated Sample Account"}

响应：

HTTP/1.1 200 OK  
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/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

在单个请求中更新多个记录

在单个请求中更新同一类型的多个记录的最快方法是使用UpdateMultiple 操作。 截至本文撰写时，UpdateMultiple 操作。 并非所有标准表都支持此操作，但所有弹性表都支持。

详细信息：

更新单个属性值

当您想要更新单个属性值时，请使用在实体 URI 上追加属性名称的 PUT 请求。

以下示例将现有 account 行中的 name 属性更新为 accountid 值00000000-0000-0000-0000-000000000001。

请求：

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

响应：

HTTP/1.1 204 No Content  
OData-Version: 4.0

删除单个属性值

要删除单个属性的值，请使用包含该属性名称并追加到实体 URI 的DELETE请求。

以下示例删除帐户实体description中具有值00000000-0000-0000-0000-000000000001的属性accountid的值。

请求：

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

响应：

HTTP/1.1 204 No Content  
OData-Version: 4.0

注释

无法使用单值导航属性来解除两个实体之间的关联。 有关替代方法，请参阅 取消与单值导航属性的关联 。

表行插入或更新操作

upsert 操作类似于更新操作。 它使用 PATCH 请求并使用 URI 来引用特定记录。 区别在于，如果记录不存在，则会被创建。 如果已存在，则会更新它。

在外部系统之间同步数据时，Upsert 非常有用。 外部系统可能不包含对 Dataverse 表主键的引用，因此可以使用外部系统中唯一标识两个系统上记录的值来配置 Dataverse 表的备用键。 详细信息：定义备用键以引用行

可以在$metadata服务文档中实体类型的批注中看到为表定义的任何备用键。 详细信息： 备用密钥。

在下面的示例中，有一个名为 sample_thing 的表具有一个备用键，该备用键引用了两列：sample_key1 和 sample_key2，这两列都被定义为存储整数值。

请求：

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

对于创建或更新操作，您将获得相同的响应。 请注意响应标头如何使用 OData-EntityId 密钥值，而不是记录的 GUID 主键标识符。

响应：

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

由于响应相同，因此无法知道该操作是表示Create操作还是Update操作。

如果需要知道，可以使用 Prefer: return=representation 请求标头。 使用此标头，可以在创建记录时获得 201 Created 响应，并在 200 OK 更新记录时获得响应。 此选项将添加一个 Retrieve 操作，该操作对性能产生影响。 如果使用 Prefer: return=representation 请求标头，请确保 $select 包含最少的数据量，最好只包含主键列。 详细信息： 使用返回的数据进行更新 ， 并使用返回的数据创建。

使用备用密钥时，不应在请求正文中包含备用键值。

  • 当 upsert 表示一个 Update时，将忽略这些备用键值。 使用备用键值标识记录时，无法更新备用键值。
  • 当 upsert 操作表示 Create 时，若 URL 中的键值未出现在请求主体中，则会为记录设置这些键值。 因此，无需将它们包含在请求正文中。

详细信息： 使用 Upsert 创建或更新记录

注释

创建新记录时，通常会让系统为主键分配 GUID 值。 这是最佳做法，因为系统会生成针对索引进行优化的键，从而提高性能。 但是，如果需要创建具有特定主键值的记录，例如，当密钥 GUID 值由外部系统生成时，该 upsert 作提供了执行此作的方法。

通过 upsert 防止创建或更新

有时，你可能想要执行某个 upsert操作，但你想要阻止其中一项操作：创建或更新。 可以使用If-Match标头或If-None-Match标头来实现这一点。 有关更多信息，请参阅限制插入或更新操作。

基本删除

删除操作非常简单。 将 DELETE 谓词与要删除的实体的 URI 一起使用。 此示例消息删除主键 accountid 值等于 00000000-0000-0000-00000-000000000001 的帐户实体。

请求：

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

响应：

如果实体存在，则会收到状态为 204 的正常响应，指示删除成功。 如果未找到实体，则会收到状态为 404 的响应。

HTTP/1.1 204 No Content  
OData-Version: 4.0

检查重复记录

有关如何在更新作期间检查重复记录的详细信息，请参阅 使用 Web API 在更新作期间检测重复记录。

在单个请求中删除多个记录

删除相同类型多条记录的最快方法是在单个请求中使用DeleteMultiple操作。 在撰写本文时，该DeleteMultiple 操作是一个预览功能。 标准表不支持此操作，但所有动态表都支持此操作。

注释

对于标准表，我们建议使用 BulkDelete作，以便异步删除与查询匹配的记录。 详细信息： 批量删除数据

详细信息：

更新和删除存储分区中的文档

如果要更新或删除存储在分区中的弹性表数据，请确保在访问该数据时指定分区键。

详细信息： 选择 PartitionId 值

另请参阅

Web API 基本作示例 （C#）
Web API 基本作示例 （客户端 JavaScript）
使用 Web API 执行操作
撰写 Http 请求并处理错误
使用 Web API 查询数据
使用 Web API 创建表行
使用 Web API 检索表行
使用 Web API 关联和取消关联表行
使用 Web API 函数
使用 Web API 操作
使用 Web API 执行批处理作
使用 Web API 模拟其他用户
使用 Web API 进行条件操作