エンティティのクエリ

[アーティクル]
06/27/2023

Query Entities 操作は、テーブル内のエンティティをクエリします。$filter オプションと $select オプションがあります。

要求

クエリオプションを使用 $select する要求の場合は、バージョン 2011-08-18 以降を使用する必要があります。また、DataServiceVersion ヘッダーと MaxDataServiceVersion ヘッダーを 2.0 に設定する必要があります。

プロジェクションを使用するには、バージョン 2013-08-15 以降を使用して要求を行う必要があります。ヘッダーと MaxDataServiceVersion ヘッダーは DataServiceVersion に設定する3.0必要があります。詳細については、「 OData データサービスのバージョンヘッダーを設定する」を参照してください。

要求は Query Entities 次のように構築できます。 HTTPS をお勧めします。 myaccount をストレージアカウントの名前に置き換え、mytable をテーブルの名前に置き換えます。

Method	要求 URI	HTTP バージョン
`GET`	`https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>`	HTTP/1.1

クエリを実行するエンティティセットのアドレスは、要求 URI のさまざまな形式を使用する場合があります。詳細については、「クエリテーブルとエンティティ」を参照してください。

エミュレートされたストレージサービス URI

エミュレートされたストレージサービスに対して要求を行うときは、エミュレーターのホスト名とテーブルサービスのポートをとして 127.0.0.1:10002指定します。その情報に従って、エミュレートされたストレージアカウントの名前を指定します。

Method	要求 URI	HTTP バージョン
`GET`	`http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>` `http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>`	HTTP/1.1

ストレージエミュレーターの Table サービスは、Azure Table Storage といくつかの点で異なります。詳細については、「ストレージエミュレーターと Azure Storage サービスの違い」を参照してください。

URI パラメーター

この操作では Query Entities 、 OData プロトコル仕様で定義されているクエリオプションがサポートされます。

要求ヘッダー

次の表では、必須および省略可能な要求ヘッダーについて説明します。

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	省略可能。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
`Accept`	省略可能。応答ペイロードの受け入れられたコンテンツの種類を指定します。次のいずれかの値になります。 - `application/atom+xml` (2015-12-11 より前のバージョンのみ) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 詳細については、「 Table Storage 操作のペイロード形式」を参照してください。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。

要求本文

[なし] :

要求のサンプル

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Response

応答には、HTTP 状態コード、一連の応答ヘッダー、および応答本文が含まれています。

status code

操作に成功すると、状態コード 200 (OK) が返されます。

状態コードの詳細については、「状態とエラーコード」および「Table Storage のエラーコード」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。応答には、追加の標準 HTTP ヘッダーも含まれる場合があります。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

応答ヘッダー	説明
`x-ms-continuation-NextPartitionKey` `x-ms-continuation-NextRowKey`	次のことが示されます。 - 返されるエンティティの数が 1,000 を超えています。 - サーバーのタイムアウト間隔を超えています。 - クエリが複数のサーバーに分散したデータを返す場合は、サーバー境界に達します。継続トークンの使用の詳細については、「クエリのタイムアウトと改ページ」を参照してください。
`x-ms-request-id`	行われた要求を一意に識別します。これを使用して、要求のトラブルシューティングを行うことができます。詳細については、「 API 操作のトラブルシューティング」を参照してください。
`x-ms-version`	要求の実行に使用された Table Storage のバージョンを示します。このヘッダーはバージョン 2009-09-19 以降で行った要求に対して返されます。
`Date`	サービスが応答を送信した時刻を示す UTC 日付/時刻値。
`Content-Type`	ペイロードのコンテンツの種類を示します。このヘッダーの値は、`Accept` 要求ヘッダーの値によって異なります。次のいずれかの値になります。 - `application/atom+xml` (2015-12-11 より前のバージョンのみ) - `application/json;odata=nometadata` - `application/json;odata=minimalmetadata` - `application/json;odata=fullmetadata` 有効なコンテンツタイプの詳細については、「 Table Storage 操作のペイロード形式」を参照してください。
`x-ms-client-request-id`	要求と対応する応答のトラブルシューティングに使用できます。このヘッダーの値は、要求に存在し、その値が最大 1,024 文字の可視 ASCII 文字である場合、ヘッダーの値 `x-ms-client-request-id` と等しくなります。ヘッダーが `x-ms-client-request-id` 要求に存在しない場合、このヘッダーは応答に存在しません。

応答のサンプル

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

応答本文

この操作は Query Entities 、テーブル内のエンティティの一覧を OData エンティティセットとして返します。エンティティの一覧は、要求のヘッダーに Accept 応じて、JSON 形式または Atom フィードのいずれかになります。

注意

ペイロード形式として JSON をお勧めします。バージョン 2015-12-11 以降でサポートされている唯一の形式です。

JSON (バージョン 2013-08-15 以降)

顧客のテーブルに対する操作の Query Entities サンプル要求 URI を次に示します。

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

メタデータのない JSON の応答ペイロードを次に示します。

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

最小限のメタデータを含む JSON の応答ペイロードを次に示します。

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

完全なメタデータを含む JSON の応答ペイロードを次に示します。

{  
   "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=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Atom フィード (2015-12-11 より前のバージョン)

顧客のテーブルに対する操作の Query Entities サンプル要求 URI を次に示します。

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

操作の Atom 応答の例を次に Query Entities 示します。

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

承認

この操作を実行できるのは、アカウント所有者と、この操作を実行するアクセス許可を持つ共有アクセス署名を使用する任意のユーザーです。

注釈

Table Storage に対するクエリでは、一度に最大 1,000 個のエンティティを返し、最大 5 秒間実行できます。応答には、次のいずれかの場合に継続トークンのセットを含むカスタムヘッダーが含まれます。

結果セットに 1,000 件を超えるエンティティが含まれている。
クエリが 5 秒以内に終了しませんでした。
クエリがパーティション境界を越えている。

継続トークンを使用して、データの次のページに対する後続の要求を作成できます。継続トークンの詳細については、「クエリのタイムアウトと改ページ」を参照してください。

注意

継続トークンを含む後続の要求を行う場合は、要求で元の URI を必ず渡してください。たとえば、元の要求の一部として、$select、または $top クエリオプションを指定$filterした場合は、後続の要求にそのオプションを含めます。そうしないと、後続の要求で予期しない結果が返される可能性があります。

この場合のクエリオプションは $top 、ページあたりの結果の最大数を指定します。応答セット全体の結果の最大数は指定されません。

詳細については、「クエリテーブルとエンティティ」を参照してください。

クエリオプションを使用するプロジェクション要求の $select 場合、バージョンは 2011-08-18 以降である必要があります。返されるプロパティの最大数は 255 です。プロパティが返されるエンティティの一部ではない場合でも、応答本文にはすべての投影プロパティが含まれます。

たとえば、射影されたエンティティに含まれないプロパティが要求に含まれている場合、欠落しているプロパティは null 属性としてマークされます。前のサンプル応答本文には、プロパティが含まれています Address 。これは、投影されたエンティティの一部ではありません。したがって、プロパティの値は null です。 <d:Address m:null="true" />

クエリのスケジュール設定と処理の要求に割り当てられた合計時間は 30 秒です。この合計には、クエリ実行の 5 秒が含まれます。

クエリ式の右側は定数である必要があることに注意してください。式の右側にあるプロパティを参照することはできません。クエリ式の構築の詳細については、「クエリテーブルとエンティティ」を参照してください。

クエリ式に値を含 null めることはできません。クエリ文字列で使用する場合は、次の文字をエンコードする必要があります。

スラッシュ (/)
疑問符 (?)
コロン (:)
アットマーク (@)
アンパサンド (&)
等号 (=)
プラス記号 (+)
コンマ (,)
ドル記号 ($)

HTTP GET 要求を承認および送信できるアプリケーションは、テーブル内のエンティティに対してクエリを実行できます。

LINQ を使用して Table Storage に対してサポートされているクエリ操作の詳細については、「 Table Storage でサポートされるクエリ演算子」および「Table Storage に対する LINQ クエリの記述」を参照してください。

こちらもご覧ください

Table Storage のエラーコード
 Azure Storage への要求を承認する
 状態コードとエラーコード
 Table Storage リソースのアドレス指定
 テーブルとエンティティのクエリ
 OData データサービスのバージョンヘッダーを設定する
 エンティティの挿入
 エンティティの更新
 エンティティの削除