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

插入或替换实体

操作 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 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对 Azure 存储的请求
x-ms-version 必需。 必须设置为 2011-08-18 或更高版本。 指定用于此请求的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
Content-Type 必需。 指定有效负载的内容类型。 可能值为 application/atom+xmlapplication/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。 这些属性共同构成主键,并且必须在表中是唯一的。

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

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

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

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

另请参阅

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