資料表服務作業的承載格式

發行項
08/05/2023

表格服務 REST API 支援以 ATOM 和 JSON 做為 OData 裝載格式。雖然所有 Azure 儲存體服務版本都支援 ATOM 通訊協定，但 JSON 通訊協定僅支援 2013-08-15 版和更新版本。

JSON 是建議的承載格式。 2013-08-15 版和更新版本支援 JSON。您必須搭配 2015-12-11 版和更新版本使用 JSON。
2015-12-11 之前的版本支援 ATOM。

注意

下列 REST API 作業不是 OData API，目前不支援 JSON：取得資料表 ACL、設定資料表 ACL、取得資料表服務屬性和設定資料表服務屬性。

若要指定 JSON 或 ATOM 格式，請為 Content-Type 下列) 所述的和 Accept 標頭指定適當的值 (。請注意下列條件約束：

所有包含 OData 裝載的要求都需要 Content-Type 標頭。
如果未提供 Accept 標頭，則回應的內容類型預設為 application/atom+xml。
當 OData 資料服務版本設定為 3.0 時，指定 $format URI 參數會覆寫在 Accept 要求標頭中指定的值。如需 OData 服務版本的詳細資訊，請參閱設定 OData 資料服務版本標頭。

若要指定裝載格式，請根據下表設定 Content-Type 和 Accept 要求標頭：

裝載格式	Content-Type 標頭	Accept 標頭	資料服務版本 (REST API 版本)	支援的 API
`Atom`	`application/atom+xml`	`application/atom+xml`	1.0 (任何版本) 2.0 (2011-08-18 或更新版本) 3.0 (2013/8/15 或更新版本)	QueryTables CreateTable 刪除資料表查詢實體插入實體插入或合併實體插入或取代實體更新實體合併實體刪除實體
`JSON`	`application/json`	`application/json;odata=nometadata` `application/json;odata=minimalmetadata` `application/json;odata=fullmetadata` 如需詳細資訊，請參閱以下的＜JSON 格式＞一節。	3.0 (2013/8/15 或更新版本)	QueryTables CreateTable 刪除資料表查詢實體插入實體插入或合併實體插入或取代實體更新實體合併實體刪除實體
`XML`	`application/xml`	`application/xml`	N/A	取得資料表 ACL 設定資料表 ACL 取得表格服務屬性設定表格服務屬性

JSON 格式 (應用程式/json) (2013-08-15 版和更新版本)

OData 可透過定義這些名稱-值組的一般慣例來擴充 JSON 格式，類似於上述的 ATOM 格式。 OData 為控制資訊 (例如識別碼、類型和連結) 定義一組標準註解。如需 JSON 格式的詳細資訊，請參閱 JSON 簡介。

使用 OData 之 JSON 格式的主要優點是可省略裝載的可預測部分，以減少裝載量。若要在接收端重新組成此資料，請使用運算式來計算遺漏連結、類型資訊和控制資料。您可以將下列三個層級指定為 Accept 標頭的一部分，以控制要從裝載中省略的部分：

application/json;odata=nometadata
application/json;odata=minimalmetadata
application/json;odata=fullmetadata

Azure 表格服務支援下列 ODATA 註解：

odata.metadata：集合、實體、基本值或服務文件的中繼資料 URL。
odata.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`	Yes	是	No
`odata.id`	是	No	No
`odata.editlink`	是	No	No
`odata.type`	是	No	No
`odata.etag`	是	No	No
自訂屬性的 `PropertyName@odata.type`	Yes	是	No
系統屬性的 `PropertyName@odata.type`	是	No	No

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`	No	常值
`Edm.DateTime`	是	String
`Edm.Double`	No	數值 (含小數點)
`Edm.Guid`	是	String
`Edm.Int32`	No	數值 (不含小數點)
`Edm.Int64`	是	String
`Edm.String`	No	String
n/a	No	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 專案示範以要求將實體插入 Azure 資料表儲存體的 JSON 格式， (如需插入作業的詳細資料，請參閱插入實體) ：

{  
  "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 為基礎的檔案格式，描述稱為摘要的相關資訊集合。摘要是由一些項目 (Item) 所組成，這些項目稱為「項目」(Entry)。 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 通訊協定規格所定義。表格服務並沒有支援所有依規格定義的資料類型。如需支援資料類型及其對應至 Common Language Runtime (CLR) 類型的相關資訊，請參閱瞭解資料表服務資料模型。

指定屬性時，不一定要指定明確的資料類型。如果省略類型，則會自動將屬性建立為資料類型 Edm.String。

如果以明確的類型建立屬性，則傳回實體的查詢會將該類型包含在 Atom 摘要中，以便您在必要時可以判斷現有屬性的類型。當您建構可篩選屬性的查詢時，了解屬性類型是很重要的。如需詳細資訊，請參閱查詢資料表和實體。

對於 Double 屬性，值 NaN 、 INF 和 -INF 分別用於 Atom 中表示數位、正無限大和負無限大。 Infinity表單和 -Infinity 也會被接受。資料表服務不支援的負版本 NaN 。在 Atom 格式中，它會區分正零和負零。

另請參閱

設定 OData Data Service 版本標頭
 Azure 儲存體服務的版本設定 $英文$
資料表服務概念