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

表服务操作的有效负载格式

  • 项目

表服务 REST API 支持 ATOM 和 JSON 作为 OData 负载格式。 虽然所有版本的 Azure 存储服务都支持 ATOM 协议，但 JSON 协议仅支持版本 2013-08-15 及更新版本。

  • JSON 是建议的有效负载格式。 版本 2013-08-15 及更新版本支持 JSON。 必须将 JSON 与版本 2015-12-11 及更高版本一起使用。

  • 2015-12-11 之前的版本支持 ATOM。

注意

以下 REST API 操作不是 OData API，目前不支持 JSON： 获取表 ACL、 设置表 ACL、 获取表服务属性和 设置表服务属性。

若要指定 JSON 或 ATOM 格式，请为 Content-Type 和 Accept 标头指定适当的值， (下面) 。 注意以下限制：

  • Content-Type 标头是包含 OData 负载的所有请求所必需的。

  • 如果不提供 Accept 标头，则响应的内容类型将默认为 application/atom+xml。

  • 当 OData 数据服务版本设置为 3.0 时，指定 $format URI 参数将会替代 Accept 请求标头中指定的值。 有关 OData 服务版本的详细信息，请参阅设置 OData 数据服务版本标头。

若要指定负载格式，请根据下表设置 Content-Type 和 Accept 请求标头：

负载格式 内容类型标头 Accept 标头 数据服务版本（REST API 版本） 受支持的 API
Atom application/atom+xml application/atom+xml 1.0（任何版本）

2.0 (2011-08-18 或更高版本)

3.0（2013/8/15 或更高版本）		 查询表

CreateTable

删除表

查询实体

插入实体

插入或合并实体

插入或替换实体

更新实体

合并实体

删除实体
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

有关详细信息，请参见下面的“JSON 格式”部分。		 3.0（2013/8/15 或更高版本） 查询表

CreateTable

删除表

查询实体

插入实体

插入或合并实体

插入或替换实体

更新实体

合并实体

删除实体
XML application/xml application/xml 空值 获取表 ACL

设置表 ACL

获取表服务属性

设置表服务属性

JSON 格式 (应用程序/json) (版本 2013-08-15 及更高版本)

OData 通过为这些名称-值对定义常规惯例来扩展 JSON 格式，与上面描述的 ATOM 格式类似。 OData 为 ID、类型和链接等控制信息定义一组规范化注释。 有关 JSON 格式的详细信息，请参阅 JSON 简介。

使用 OData 的 JSON 格式的主要优势是可以省略负载的可预测部分以减小负载大小。 若要在接收端重新组建此数据，可使用表达式计算缺失的链接、类型信息和控制数据。 若要控制省略负载中的哪些信息，可在 Accept 标头中指定三种级别：

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

Azure 表服务支持以下 ODATA 注释：

  • odata.metadata：集合、实体、基元值或服务文档的元数据 URL。

  • odata.id：实体 ID，通常为资源的 URL。

  • odata.editlink：用于编辑/更新条目的链接，前提是实体可更新并且 odata.id 不表示可用于编辑实体的 URL。

  • odata.type：容器对象的类型名称。

  • odata.etag：实体的 ETag。

  • 用于自定义属性的 PropertyName@odata.type：目标属性的类型名称。

  • 用于系统属性的 PropertyName@odata.type（例如，PrimaryKey、RowKey 和 Timestamp 属性）：目标属性的类型名称。

下表总结了每个级别包含的信息：

Annotations odata=fullmetadata odata=minimalmetadata odata=nometadata
odata.metadata 是 是 否
odata.id 是 否 否
odata.editlink 是 否 否
odata.type 是 否 否
odata.etag 是 否 否
用于自定义属性的 PropertyName@odata.type 是 是 否
用于系统属性的 PropertyName@odata.type 是 否 否

JSON 馈送中的属性类型

odata.type 注释在 OData JSON 格式中使用以确定开放式属性的类型。 当满足以下所有条件时，将会存在该注释：

  • JSON 控制级别设置为 odata=minimalmetadata 或 odata=fullmetadata，如“JSON 格式”部分所述。

  • 该属性是自定义属性。 请注意，对于 Azure 表，只有 PartitionKey、RowKey 和 Timestamp 属性是系统属性，它们的类型信息在 $metadata 中声明。 仅当控制级别设置为 odata=fullmetadata 时，这些属性的类型注释才会存在。 有关详细信息 ，请参阅了解表服务数据模型。

  • 无法通过下表中总结的启发式类型检测方法来确定属性的类型。

Edm 类型 需要 odata.type 注释 JSON 类型
Edm.Binary 是 String
Edm.Boolean 否 文本
Edm.DateTime 是 String
Edm.Double 否 Numeric（包括小数点）
Edm.Guid 是 String
Edm.Int32 否 Numeric（不包括小数点）
Edm.Int64 是 String
Edm.String 否 String
不适用 否 Null

表服务不保留 null 属性的值。 编写实体时， null 可以使用或不使用 odata.type 注释指定值，并且处理任何具有 null 值的属性，就好像请求不包含该属性一样。 Null 查询实体时，永远不会返回属性值。

对于 Edm.Double，值 NaN、 Infinity 和 -Infinity 使用类型 String以 JSON 表示，并且需要 odata.type 注释。 表服务不支持负版本的 NaN，在 JSON 格式中，它不区分正零和负零 (它被视为 -0.00.0) 。

以下 JSON 实体提供八种不同属性类型中每一种类型的示例：

{  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey",  
  "DateTimeProperty@odata.type":"Edm.DateTime",  
  "DateTimeProperty":"2013-08-02T17:37:43.9004348Z",  
  "BoolProperty":false,  
  "BinaryProperty@odata.type":"Edm.Binary",  
  "BinaryProperty":"AQIDBA==",  
  "DoubleProperty":1234.1234,  
  "GuidProperty@odata.type":"Edm.Guid",  
  "GuidProperty":"4185404a-5818-48c3-b9be-f217df0dba6f",  
  "Int32Property":1234,  
  "Int64Property@odata.type":"Edm.Int64",  
  "Int64Property":"123456789012",  
  "StringProperty":"test"  
}

由于 PartitionKey 和 RowKey 是系统属性，这意味着所有表行都必须定义这些属性，它们的类型注释不出现在实体中。 这些属性被预定义为类型 Edm.String。 但是，其他属性是自定义属性，因此包含与上表中支持的基元类型之一对应的类型信息。

示例：

以下示例 OData 条目演示了作为请求发送的 JSON 格式，以将实体插入 Azure 表存储 (有关插入操作) 的详细信息，请参阅 插入实体 ：

{  
  "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,  
  "NumOfOrders@odata.type":"Edm.Int64",  
  "NumOfOrders":"255",  
  "PartitionKey":"mypartitionkey",  
  "RowKey":"myrowkey1",  
}

当客户端查询 Azure 表存储中的一组实体时，服务将使用 JSON 有效负载进行响应 (有关查询操作) 的详细信息，请参阅查询 实体 。 馈送可以包含三种信息级别之一：无元数据、最少元数据或完整元数据。 以下示例分别演示各种类别：

无元数据：

{  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

最小元数据：

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers,  
  "value":[  
    {  
      "PartitionKey":"Customer03",  
      "RowKey":"Name",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

完整元数据：

{  
  "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
  "value":[  
    {  
      "odata.type":"myaccount.Customers",  
      "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')",  
      "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
      "odata.editLink":"Customers(PartitionKey='Customer03',RowKey='Name')",  
      "PartitionKey":"Customer03,  
      "RowKey":"Name",  
      "Timestamp@odata.type":"Edm.DateTime",  
      "Timestamp":"2013-08-09T18:55:48.3402073Z",  
      "CustomerSince@odata.type":"Edm.DateTime",  
      "CustomerSince":"2008-10-01T15:25:05.2852025Z",  
    }  
}

若要了解有关 OData JSON 格式的详细信息，请参阅 OData JSON 格式版本 4.0 规范以及 [MS-ODATAJSON]：OData 协议 JSON 格式标准支持文档。

Atom Format (application/atom+xml) (版本低于 2015-12-11 仅)

Atom 是一种基于 XML 的文档格式，用于描述称为 源的相关信息集合。 馈送由许多称为“条目”的项组成。 AtomPub 为条目和源定义其他格式构造，以便可以轻松对它们表示的资源进行分类、分组、编辑和发现。 但是，由于 Atom 不定义如何使用源编码结构化数据， 因此 OData 定义了一组用于表示 Atom 源中的结构化数据的约定，以便允许基于 OData 的服务传输结构化内容。

例如，以下示例 OData 条目演示了通过请求发送的 Atom 格式，以使用 REST API 将实体插入 Azure 表存储 (有关插入操作) 的详细信息，请参阅 插入实体 ：

<?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 />  
  <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>

当客户端查询表存储中的一组实体时，服务将使用 Atom 源进行响应，该源是 Atom 条目的集合 (有关查询操作) 的详细信息，请参阅 查询实体 ：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>  
<feed 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" xmlns="https://www.w3.org/2005/Atom">  
  <title type="text">Customers</title>  
  <id>https://myaccount.table.core.windows.net/Customers</id>  
  <link rel="self" title="Customers" href="Customers" />  
  <entry m:etag="W/"0x5B168C7B6E589D2"">  
  <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer03',RowKey='Name')</id>  
    <title type="text"></title>  
    <updated>2008-10-01T15:26:13Z</updated>  
    <author>  
      <name />  
    </author>  
    <link rel="edit" title="Customers" href="Customers (PartitionKey='Customer03',RowKey='Name')" />  
    <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
    <content type="application/xml">  
      <m:properties>  
        <d:PartitionKey>Customer03</d:PartitionKey>  
        <d:RowKey>Name</d:RowKey>        <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
      </m:properties>  
    </content>  
  </entry>  
</feed>

Atom 馈送中的属性类型

属性数据类型由 OData 协议规范定义。 该规范定义的数据类型并不都受表服务支持。 有关支持的数据类型以及它们如何映射到公共语言运行时 (CLR) 类型的信息，请参阅 了解表服务数据模型。

属性可以用（也可以不用）显式数据类型指定。 如果省略类型，则属性会自动创建为数据类型 Edm.String。

如果用显式类型创建了一个属性，返回该实体的查询将在 Atom 馈送中包括该类型，以便你在需要时确定现有属性的类型。 当你在构造基于一个属性进行筛选的查询时，知道该属性的类型是很重要的。 有关详细信息，请参阅 查询表和实体。

对于 Double 属性，Atom 中的值 NaN、 INF和 -INF 分别用于指示非数字、正无穷大和负无穷大。 Infinity表单 和 -Infinity 也被接受。 表服务不支持 的 NaN负版本。 在 Atom 格式中，它区分正零和负零。

另请参阅

设置 OData 数据服务版本标头
Azure 存储服务的版本控制
表服务概念