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

[アーティクル]
08/05/2023

テーブルサービス 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、システムプロパティ (つまり、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 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 の場合、値 NaN、 Infinity と -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"  
}

PartitionKey と RowKey は (すべてのテーブル行で定義する必要がある) システムプロパティのため、型の注釈はエンティティに示されません。これらのプロパティは、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 では、値 NaN、 INF、および -INF がそれぞれ数値、正の無限大、負の無限大を示すために使用されます。フォーム Infinity と -Infinity も受け入れられます。 Table サービスでは、の負の NaNバージョンはサポートされていません。 Atom 形式では、正と負の 0 を区別します。

参照

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

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

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

JSON フィードにおけるプロパティの型

例:

Atom 形式 (application/atom+xml) (2015-12-11 より前のバージョンのみ)

Atom フィードにおけるプロパティの型

参照

その他のリソース