銷售: 1-800-867-1380

表格服務作業的裝載格式

更新日期: 2014年8月

表格服務 REST API 支援以 ATOM 和 JSON 做為 OData 裝載格式。雖然所有 Azure 儲存體服務版本皆支援 ATOM 通訊協定,但只有 2013-08-15 以上的版本支援 JSON 通訊協定。

note附註
下列 REST API 作業不是 OData API,且目前不支援 JSON:取得資料表 ACL設定資料表 ACL取得表格服務屬性設定表格服務屬性

若要指定 ATOM 或 JSON 格式,請為 Content-TypeAccept 標頭指定適當值 (如下所述)。請注意下列條件約束:

  • 所有包含 OData 裝載的要求都需要 Content-Type 標頭。

  • 如果未提供 Accept 標頭,則回應的內容類型預設為 application/atom+xml

  • 當 OData 資料服務版本設定為 3.0 時,指定 $format URI 參數會覆寫在 Accept 要求標頭中指定的值。如需 OData 服務版本的詳細資訊,請參閱<設定 OData Data Service 版本標頭>。

若要指定裝載格式,請根據下表設定 Content-TypeAccept 要求標頭:

 

裝載格式 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

取得資料表 ACL

設定資料表 ACL

取得表格服務屬性

設定表格服務屬性

Atom 是描述相關資訊集合的 XML 文件格式,這些相關資訊集合稱為「摘要」(Feed)。摘要是由一些項目 (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="http://www.w3.org/2005/Atom">
  <title />
  <updated>2008-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>
      <d:Timestamp m:type="Edm.DateTime">0001-01-01T00:00:00</d:Timestamp>
    </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="http://www.w3.org/2005/Atom">
  <title type="text">Customers</title>
  <id>https://myaccount.table.core.windows.net/Customers</id>
  <updated>2008-10-01T15:26:13Z</updated>
  <link rel="self" title="Customers" href="Customers" />
  <entry m:etag="W/&quot;0x5B168C7B6E589D2&quot;">
  <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>

屬性資料類型是以 OData 通訊協定規格進行定義。表格服務並沒有支援所有依規格定義的資料類型。如需了解支援的資料類型,以及資料類型如何對應至 Common Language Runtime (CLR) 類型之相關資訊,請參閱<了解表格服務資料模型>。

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

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

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:目標屬性的類型名稱。

  • 系統屬性 (亦即 PrimaryKeyRowKeyTimestamp 屬性) 的 PropertyName@odata.type:目標屬性的類型名稱。

下表摘要說明每個層級所包含的資訊:

 

Annotations

odata=fullmetadata

odata=minimalmetadata

odata=nometadata

odata.metadata

odata.id

odata.editlink

odata.type

odata.etag

自訂屬性的 PropertyName@odata.type

系統屬性的 PropertyName@odata.type

odata.type 註解可用於 OData JSON 格式,以判斷開啟屬性的類型。當符合下列所有條件時,則存在此註解:

  • JSON 控制層級設定為 odata=minimalmetadataodata=fullmetadata (如<JSON 格式>一節所述)。

  • 屬性為自訂屬性。請注意,就 Azure 資料表而言,只有 PartitionKeyRowKeyTimestamp 屬性為系統屬性,且其類型資訊會在 $metadata 中宣告。只有控制層級設定為 odata=fullmetadata 時,才存在這些屬性的類型註解。如需詳細資訊,請參閱了解表格服務資料模型

  • 下表摘要說明無法透過類型偵測啟發學習法判斷的屬性類型。

 

Edm 類型

需要 odata.type 註解

JSON 類型

Edm.Binary

字串

Edm.Boolean

常值

Edm.DateTime

字串

Edm.Double

數值 (含小數點)

Edm.Guid

字串

Edm.Int32

數值 (不含小數點)

Edm.Int64

字串

Edm.String

字串

下列 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"
}

由於 PartitionKeyRowKey 是系統屬性 (亦即所有資料表資料列都必須定義這些屬性),因此其類型註解不會出現在實體中。這些屬性會預先定義為 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",
  "Timestamp":"0001-01-01T00:00:00"
}

當用戶端查詢 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 格式標準支援文件>。

另請參閱

本文對您有任何幫助嗎?
(剩餘 1500 個字元)
感謝您提供意見
顯示:
© 2014 Microsoft