你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

插入或替换实体

项目
05/04/2024

操作 Insert Or Replace Entity 将替换现有实体，或者插入新实体（如果表中不存在）。由于此操作可以插入或更新实体，因此它也称为 更新插入 操作。

请求

可以按如下所示构造 Insert Or Replace Entity 请求。建议使用 HTTPS。将以下值替换为你自己的值：

将 myaccount 替换为你的存储帐户名称
将 mytable 替换为你的表名称
myPartitionKey 以及 myRowKey 要更新的实体的分区键和行键的名称

方法	请求 URI	HTTP 版本
`PUT`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

模拟存储服务

针对模拟存储服务发出请求时，将模拟器主机名和 Azure 表存储端口指定为 127.0.0.1：10002，后跟模拟存储帐户名称。

方法	请求 URI	HTTP 版本
`PUT`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='myPartitionKey', RowKey='myRowKey')`	HTTP/1.1

存储模拟器中的表存储在多个方面与 Azure 表存储不同。有关详细信息，请参阅存储模拟器与 Azure 存储服务之间的差异。

URI 参数

可以在请求 URI 上指定以下附加参数。

参数	说明
`timeout`	可选。 `timeout` 参数以秒表示。有关详细信息，请参阅设置表存储操作的超时。

请求标头

下表介绍必需的和可选的请求标头。

请求标头	说明
`Authorization`	必需。指定授权方案、帐户名称和签名。有关详细信息，请参阅授权对 Azure 存储的请求。
`Date` 或 `x-ms-date`	必需。指定请求的协调世界时 (UTC)。有关详细信息，请参阅授权对 Azure 存储的请求。
`x-ms-version`	必需。必须设置为 2011-08-18 或更高版本。指定用于此请求的操作的版本。有关详细信息，请参阅 Azure 存储服务的版本控制。
`Content-Type`	必需。指定有效负载的内容类型。可能值为 `application/atom+xml` 和 `application/json`。有关有效内容类型的详细信息，请参阅表存储操作的有效负载格式。
`Content-Length`	必需。请求正文的长度。
`x-ms-client-request-id`	可选。提供客户端生成的不透明值，其中包含 1-kiB (KiB) 配置日志记录时记录在日志中的字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息，请参阅监视 Azure 表存储。

请求正文

操作 Insert Or Replace Entity 发送要作为 OData 实体集插入的实体。此实体集可以是 JSON 或 Atom 源。有关详细信息，请参阅插入和更新实体。

注意

JSON 是建议的有效负载格式，并且是版本 2015-12-11 及更高版本支持的唯一格式。

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作将返回状态代码 204（无内容）。有关状态代码的信息，请参阅状态和错误代码以及表存储错误代码。

响应头

响应包含以下标头。响应还可以包含其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范。

响应标头	说明
`ETag`	`ETag`实体的。
`x-ms-request-id`	唯一标识发出的请求，可用于对请求进行故障排除。有关详细信息，请参阅 API 操作疑难解答。
`x-ms-version`	指示用于运行请求的表存储版本。针对 2009-09-19 和更高版本发出的请求将返回此标头。
`Date`	一个 UTC 日期/时间值，该值指示启动响应的时间。服务生成此值。
`x-ms-client-request-id`	可用于对请求和相应响应进行故障排除。如果请求中存在此标头的值，则此标头的值等于该标头的值 `x-ms-client-request-id` 。该值最多为 1,024 个可见 ASCII 字符。 `x-ms-client-request-id`如果请求中不存在标头，则它不会出现在响应中。

响应正文

无。

授权

帐户所有者可以执行此操作。此外，具有共享访问签名且有权执行此操作的任何人都可以执行此操作。

示例请求和响应

以下示例演示使用 JSON 和 Atom 源的示例请求。

注意

JSON 是建议的有效负载格式，并且是版本 2015-12-11 及更高版本支持的唯一格式。

JSON (版本 2013-08-15 及更高版本)

下面是使用 JSON 的示例请求和响应。

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

请求与以下标头一起发送：

x-ms-version: 2013-08-15  
Content-Type: application/json  
x-ms-date: Tue, 30 Aug 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

请求与以下 JSON 正文一起发送：

{  
   "Address":"Santa Clara",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode@odata.type":"Edm.Guid",  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince@odata.type":"Edm.DateTime",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":false,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}

在发送请求后，将返回以下响应：

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 30 Aug 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

Atom 源 (2015-12-11 之前的版本)

下面是使用 Atom 的示例请求和响应。

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey')

请求与以下标头一起发送：

x-ms-version: 2013-08-15  
Accept: application/atom+xml,application/xml  
Accept-Charset: UTF-8  
Content-Type: application/atom+xml  
x-ms-date: Tue, 12 Nov 2013 18:10:24 GMT  
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=  
Content-Length: 1135  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx

请求与以下 XML 正文一起发送：

<?xml version="1.0" encoding="utf-8"?>  
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="https://www.w3.org/2005/Atom">  
  <title />  
  <updated>2013-11-12T18:09:37.168836Z</updated>  
  <author>  
    <name />  
  </author>  
<id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Santa Clara</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
    </m:properties>  
  </content>  
</entry>

在发送请求后，将返回以下响应：

HTTP/1.1 204 No Content  
  
Connection: Keep-Alive  
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d  
Content-Length: 0  
Cache-Control: no-cache  
Date: Tue, 12 Nov 2013 18:12:54 GMT  
ETag: W/"0x5B168C7B6E589D2"  
DataServiceVersion: 1.0;NetFx  
MaxDataServiceVersion: 2.0;NetFx  
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

注解

操作 Insert Or Replace Entity 不使用 If-Match 标头。必须使用 2011-08-18 或更高版本调用此操作。这些属性将此操作与更新实体操作区分开来。

如果使用 Insert Or Replace Entity 操作替换实体，则如果新实体未定义这些属性，则会删除上一个实体中的任何属性。还会删除具有 null 值的属性。

调用Insert or Replace Entity操作时，必须为和 RowKey 系统属性指定值PartitionKey。这些属性共同构成主键，并且必须在表中是唯一的。

PartitionKey和 RowKey 值必须是字符串值。 PartitionKey 和 RowKey 值的大小最多可为 1024 个字符。如果使用整数值作为键值，则应将该整数转换为固定宽度的字符串。这是因为它们是按 Canonic 方式排序的。例如，将值 1 转换为 0000001，以确保正确排序。

若要显式键入属性，请通过在 Atom 馈送中的属性定义中设置属性来m:type指定适当的OData数据类型。有关键入属性的详细信息，请参阅插入和更新实体。

可以授权和发送 HTTP PUT 请求的任何应用程序都可以插入或替换实体。

有关执行批处理更新插入操作的信息，请参阅执行实体组事务。

另请参阅

授权对 Azure 存储的请求
 设置 OData 数据服务版本标头
 插入和更新实体
 状态和错误代码
 表存储错误代码

通过