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

插入实体

Insert Entity操作在表中插入一个新实体。

请求

可以按如下所示构造 Insert Entity 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称,将 mytable 替换为表的名称。

方法 请求 URI HTTP 版本
POST https://myaccount.table.core.windows.net/mytable HTTP/1.1

模拟存储服务 URI

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

方法 请求 URI HTTP 版本
POST http://127.0.0.1:10002/devstoreaccount1/mytable HTTP/1.1

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

URI 参数

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

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

请求标头

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

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权对 Azure 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对 Azure 存储的请求
x-ms-version 可选。 指定用于此请求的操作的版本。 有关详细信息,请参阅 Azure 存储服务的版本控制
Content-Type 必需。 指定有效负载的内容类型。 可能的值是 application/atom+xml 2015-12-11 之前的 (版本,仅) 和 application/json

有关有效内容类型的详细信息,请参阅 表存储操作的有效负载格式
Content-Length 必需。 请求正文的长度。
Accept 可选。 指定响应负载已接受的内容类型。 可能的值为:

- application/atom+xml (2015-12-11 之前的版本仅)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

有关详细信息,请参阅 表存储操作的有效负载格式
Prefer 可选。 指定响应是否应包含负载中插入的实体。 可能值为 return-no-contentreturn-content。 有关详细信息,请参阅 设置首选标头以管理插入操作上的响应回显
x-ms-client-request-id 可选。 提供客户端生成的不透明值,其中包含 1-kibite (KiB) 配置日志记录时记录在日志中的字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅 监视 Azure 表存储

请求正文

操作 Insert Entity 发送要作为 OData 实体插入的实体,该实体是 JSON 或 Atom 源。 有关详细信息,请参阅 插入和更新实体

注意

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

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

下面是操作的示例 JSON 请求正文 Insert Entity

{  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey"  
}  

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

下面是操作的示例 Atom 请求正文 Insert Entity

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<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-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <id />  
  <content type="application/xml">  
    <m:properties>  
      <d:Address>Mountain View</d:Address>  
      <d:Age m:type="Edm.Int32">23</d:Age>  
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>  
      <d:BinaryData m:type="Edm.Binary" m:null="true" />  
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>  
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</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 状态代码、一组响应标头和响应正文。

状态代码

状态代码取决于 Prefer 标头的值。 如果 Prefer 标头设置为 return-no-content,则成功的操作将返回状态代码 204 (No Content)。 Prefer如果未指定标头,或者将其设置为 return-content,则成功的操作将返回状态代码 201 (Created) 。 有关详细信息,请参阅 设置首选标头以管理插入操作上的响应回显

有关状态代码的信息,请参阅 状态和错误代码表服务错误代码

响应头

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

响应标头 说明
x-ms-request-id 唯一标识发出的请求,可用于对请求进行故障排除。 有关详细信息,请参阅 API 操作故障排除
x-ms-version 指示用于运行请求的表存储的版本。 针对 2009-09-19 和更高版本发出的请求将返回此标头。
Date 指示启动响应的时间的 UTC 日期/时间值。 服务生成此值。
ETag ETag实体的 。
Preference-Applied 指示是否接受 Prefer 请求标头。 如果响应不包含此标头,则 Prefer 不遵循该标头。 如果返回此标头,其值将为 return-contentreturn-no-content

有关详细信息,请参阅 设置首选标头以管理插入操作上的响应回显
Content-Type 指示负载的内容类型。 该值取决于为 Accept 请求标头指定的值。 可能的值为:

- application/atom+xml
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

有关内容类型的详细信息,请参阅 表存储操作的有效负载格式
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果请求中存在,则此标头的值等于 标头的值 x-ms-client-request-id 。 该值最多为 1,024 个可见 ASCII 字符。 x-ms-client-request-id如果请求中不存在标头,则它不会出现在响应中。

响应正文

如果请求包含的 Prefer 标头具有值 return-no-content,则不返回响应正文。 否则,响应正文为 OData 实体集。

注意

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

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

下面是每个元数据级别的 JSON 响应示例:

无元数据:

{  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "Age":23,  
   "AmountDue":200.23,  
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",  
   "CustomerSince":"2008-07-10T00:00:00",  
   "IsActive":true,  
   "NumberOfOrders":"255"  
}  
  

最小元数据:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}  
  

完整元数据:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",  
   "odata.type":"myaccount.Customers",  
   "odata.id":" https://myaccount.table.core.windows.net/Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
   "odata.editLink":"Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",  
   "PartitionKey":"mypartitionkey",  
   "RowKey":"myrowkey",  
   "Timestamp@odata.type":"Edm.DateTime",  
   "Timestamp":"2013-08-22T01:12:06.2608595Z",  
   "Address":"Mountain View",  
   "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":true,  
   "NumberOfOrders@odata.type":"Edm.Int64",  
   "NumberOfOrders":"255"  
}  

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

下面是 Insert Entity 操作的示例 Atom 响应正文。

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<entry xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/"0x5B168C7B6E589D2"" xmlns="https://www.w3.org/2005/Atom">  
  <id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>  
  <title type="text"></title>  
  <updated>2008-09-18T23:46:19.3857256Z</updated>  
  <author>  
    <name />  
  </author>  
  <link rel="edit" title="mytable" href="mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')" />  
  <category term="myaccount.Tables" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
  <content type="application/xml">  
    <m:properties>  
      <d:PartitionKey>mypartitionkey</d:PartitionKey>  
      <d:RowKey>myrowkey1</d:RowKey>  
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:19.4277424Z</d:Timestamp>  
      <d:Address>Mountain View</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:00</d:CustomerSince>  
      <d:IsActive m:type="Edm.Boolean">true</d:IsActive>  
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>  
    </m:properties>  
  </content>  
</entry>  

授权

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

注解

在表中插入实体时,必须为 和 RowKey 系统属性指定值PartitionKey。 这些属性共同构成主键,并且必须在表中是唯一的。

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

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

表存储不会使 null 属性的值持久化。 指定具有 null 值的属性等效于在请求中省略该属性。

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

另请参阅

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