次の方法で共有


Table Service 操作のペイロード形式

テーブル サービス REST API は、Atom と JSON を OData ペイロード形式としてサポートします。 ATOM プロトコルは Azure ストレージ サービスのすべてのバージョンでサポートされていますが、JSON プロトコルはバージョン 2013-08-15 以降でのみサポートされます。

  • JSON は推奨されるペイロード形式です。 JSON はバージョン 2013-08-15 以降でサポートされています。 バージョン 2015-12-11 以降では JSON を使用する必要があります。

  • ATOM は、2015-12-11 より前のバージョンでサポートされています。

注意

次の REST API 操作は OData API ではなく、現在 JSON をサポートしていません。 テーブル ACL の取得テーブル ACL の設定テーブル サービスのプロパティの取得、および Table Service プロパティの設定です。

JSON または ATOM 形式を指定するには、 ヘッダーと Accept ヘッダーに適切な値をContent-Type指定します (後述)。 次の制約に注意してください。

  • Content-Type ヘッダーは、OData ペイロードが含まれるすべての要求に必要です。

  • Accept ヘッダーが指定されていない場合、応答のコンテンツの種類は既定で application/atom+xml になります。

  • $format URI パラメーターを指定した場合、OData データ サービス バージョンが 3.0 に設定されていると、Accept 要求ヘッダーに指定された値がオーバーライドされます。 OData サービスのバージョンの詳細については、「OData Data Service バージョン ヘッダーの設定」を参照してください。

ペイロード形式を指定するには、次の表に従って 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/08/15 以降)
QueryTables

CreateTable

[テーブルの削除]

エンティティのクエリ

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

エンティティの更新

エンティティの統合

エンティティの削除
JSON application/json application/json;odata=nometadata

application/json;odata=minimalmetadata

application/json;odata=fullmetadata

詳細については、この後の「JSON 形式」を参照してください。
3.0 (2013/08/15 以降) QueryTables

CreateTable

[テーブルの削除]

エンティティのクエリ

Insert Entities

Insert Or Merge Entity

Insert Or Replace Entity

エンティティの更新

エンティティの統合

エンティティの削除
XML application/xml application/xml 該当なし Get Table ACL

Set Table ACL

Get Table Service Properties

Set Table Service Properties

JSON 形式 (application/json) (バージョン 2013-08-15 以降)

OData は、既に説明した Atom 形式に似た名前と値のペアに関する一般的な規則を定義して、JSON 形式を拡張します。 OData は、制御情報 (ID、型、リンクなど) の標準的な注釈のセットを定義します。 JSON 形式の詳細については、「JSON の 概要」を参照してください。

OData の JSON 形式を使用する主な利点は、ペイロードの予測可能な部分を削除してペイロードのサイズを小さくできることにあります。 このデータを受信側で再構成するには、式を使用して、不足しているリンク、型情報、および制御データを計算します。 ペイロードから削除する内容を制御するために、Accept ヘッダーの一部として次の 3 つのレベルを指定できます。

  • 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、システム プロパティ (つまりPrimaryKeyRowKey、および 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 JSON 形式では、開かれたプロパティの型を判定するために odata.type 注釈が使用されます。 この注釈は、次に示す条件がすべて満たされた場合に存在します。

  • JSON 制御レベルが、「JSON 形式」で説明した odata=minimalmetadata または odata=fullmetadata に設定されている。

  • プロパティがカスタム プロパティである。 Azure テーブルの場合、PartitionKey プロパティ、RowKey プロパティ、および Timestamp プロパティのみがシステム プロパティで、その型情報は $metadata 内で宣言されます。 これらのプロパティの型の注釈は、制御レベルが odata=fullmetadata に設定されている場合にのみ存在します。 詳細については、「 Table Service データ モデルについて」を参照してください。

  • 次の表に説明する型検出ヒューリスティックでプロパティの型を判定できない。

Edm 型 odata.type 注釈が必要 JSON 型
Edm.Binary はい String
Edm.Boolean いいえ リテラル
Edm.DateTime はい String
Edm.Double いいえ 数値 (小数点を含む)
Edm.Guid はい String
Edm.Int32 いいえ 数値 (小数点を含まない)
Edm.Int64 はい String
Edm.String いいえ String
N/A いいえ [Null]

Table サービスでは、プロパティの値は保持 null されません。 エンティティを記述する場合、 null odata.type 注釈の有無にかかわらず値を指定できます。値を null 持つプロパティは、要求にそのプロパティが含まれていないかのように処理されます。 Null プロパティ値は、エンティティに対してクエリを実行するときに返されることはありません。

Edm.Double の場合、値 NaNInfinity-Infinity は型 Stringを使用して JSON で表され、odata.type 注釈が必要です。 Table サービスでは、 の負のNaNバージョンはサポートされていません。JSON 形式では、正と負のゼロを区別しません (として0.0扱われます-0.0)。

次の JSON エンティティに、これらの 8 つのプロパティ型の例を示します。

{  
  "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 エントリは、Azure Table Storage にエンティティを挿入するための要求として送信される 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 Table Storage 内の一連のエンティティに対してクエリを実行すると、サービスは JSON ペイロードで応答します (クエリ操作の詳細については、「 クエリ エンティティ 」を参照してください)。 フィードには、3 つのレベルの情報 (メタデータなし、最小のメタデータ、完全なメタデータ) のいずれかを含めることができます。 それぞれのレベルの例を次に示します。

メタデータなし:

{  
  "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 形式 (application/atom+xml) (2015-12-11 より前のバージョンのみ)

Atom は、 フィードと呼ばれる関連情報のコレクションを記述する XML ベースのドキュメント形式です。 フィードは、"エントリ" と呼ばれる複数の項目で構成されます。 AtomPub では、エントリとフィードの追加の形式コンストラクトを定義して、それらが表すリソースを簡単に分類、グループ化、編集、検出できるようにします。 ただし、Atom はフィードで構造化データをエンコードする方法を定義していないため、 OData は、OData に基づくサービスによる構造化コンテンツの転送を可能にするために、Atom フィードで構造化データを表す一連の規則を定義します。

たとえば、次のサンプル OData エントリは、REST API を使用して Azure Table Storage にエンティティを挿入する要求を通じて送信される Atom 形式を示しています (挿入操作の詳細については、「 エンティティの挿入 」を参照してください)。

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

クライアントが Table Storage 内の一連のエンティティに対してクエリを実行すると、サービスは 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) 型にどのようにマップされるかについては、「 Table Service データ モデルについて」を参照してください。

プロパティには、明示的なデータ型を指定することも指定しないこともできます。 型を省略すると、 プロパティはデータ型 として自動的に作成されます Edm.String

プロパティを明示的な型で作成した場合、エンティティを返すクエリに Atom フィード内のその型が含まれるので、必要に応じて既存のプロパティの型を確認できます。 プロパティの型を知ることは、そのプロパティをフィルター処理するクエリを作成するときに重要です。 詳細については、「 テーブルとエンティティのクエリ」を参照してください。

プロパティの場合 Double 、Atom では、値 NaNINF、および -INF がそれぞれ数値、正の無限大、負の無限大を示すために使用されます。 フォーム Infinity-Infinity も受け入れられます。 Table サービスでは、 の負の NaNバージョンはサポートされていません。 Atom 形式では、正と負の 0 を区別します。

参照

OData Data Service のバージョン ヘッダーの設定
Azure Storage サービスのバージョン管理
テーブル サービスの概念