REST API を使用した Azure Cosmos DB リソースのクエリ

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

Azure Cosmos DB は、グローバル分散型のマルチモデルデータベースであり、複数の API でサポートされています。この記事では、REST を使用して SQL API を使用してリソースにクエリを実行する方法について説明します。

REST を使用してリソースに対してクエリを実行する方法

リソースに対して SQL クエリを実行するには、次の手順に従います。

プロパティが POST SQL クエリ文字列に設定され、"parameters" プロパティが省略可能なパラメーター値の配列に設定された JSON query を使用して、リソースパスに対してメソッドを実行します。
x-ms-documentdb-isquery ヘッダーを True に設定します。
Content-Type ヘッダーを application/query+json に設定します。

.NET を使用してリソースに対して SQL クエリを実行する方法を示すサンプルについては、「 REST from .NET Sample」を参照してください。

例

次のコード例は、ドキュメントリソースに対する REST クエリ操作を示しています。この例では、著者が "Don" になっているすべてのドキュメントを検索します。

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}

要求の詳細

方法	要求 URI
POST	[必須] 。認証の種類と署名トークン。この操作には、マスターキートークンのみを使用できます。詳細については、「Cosmos DB リソースのAccess Control」を参照してください。

要求ヘッダー

次の表に、クエリ操作の実行に使用する一般的なヘッダーを示します。

標準ヘッダー	説明
承認	[必須] 。認証の種類と署名トークン。この操作には、マスターキートークンのみを使用できます。詳細については、「Cosmos DB リソースのAccess Control」を参照してください。
Content-Type	[必須] 。 application/query+json に設定する必要があります。
受容	オプション。現時点では、Cosmos DB は常に標準の JSON 形式で応答ペイロードを返します。クライアントは、標準の JSON 形式で応答本文を受け入れることができる必要があります。
User-Agent	オプション。要求を実行するユーザーエージェントです。推奨される形式は {ユーザーエージェント名}/{バージョン} です。たとえば、SQL API .NET SDK では、User-Agent 文字列を Microsoft.Document.Client/1.0.0.0 に設定します。

カスタムヘッダー	説明
x-ms-date	[必須] 。 RFC 1123 で指定されている要求の日付。たとえば、日付形式は協定世界時 (UTC) で表されます。たとえば、「Fri, 08 Apr 2015 03:52:31 GMT」です。
x-ms-documentdb-isquery	[必須] 。このプロパティは true に設定する必要があります。
x-ms-max-item-count	オプション。結果セットを改ページするには、このヘッダーを 1 つのページに返す最大項目数に設定します。
x-ms-continuation	オプション。次の項目ページに移動するには、このヘッダーを次のページの継続トークンに設定します。
x-ms-version	オプション。 Cosmos DB REST サービスのバージョン。ヘッダーが指定されていない場合、最新バージョンが使用されます。詳細については、「 Azure Cosmos DB REST API リファレンス」を参照してください。
x-ms-documentdb-query-enable-scan	オプション。型の正しいインデックスパスが利用できない場合、インデックススキャンを使用してクエリを処理します。
x-ms-session-token	オプション。要求のセッショントークン。セッションの一貫性のために使用されます。
x-ms-partition-key	オプション。指定した場合、クエリはヘッダーのパーティションキー値と一致するドキュメントでのみ実行されます。
x-ms-documentdb-query-enablecrosspartition	オプション。 1 つのパーティションキーに対してフィルター処理しないクエリの場合は、true に設定する必要があります。 1 つのパーティションキー値に対してフィルター処理するクエリは、true に設定されている場合でも、1 つのパーティションに対してのみ実行されます。
x-ms-documentdb-populatequerymetrics	オプション。クエリメトリックを返すには、をに `True` 設定する必要があります

要求本文

要求本文は、SQL クエリとパラメーターを含む有効な JSON ドキュメントである必要があります。入力が正しくないか、無効な SQL 構文である場合、操作は 400 無効な要求のエラーで失敗します。

ゲートウェイでクエリを処理できない場合は、400 の無効な要求も受け取ります。

プロパティ	説明
query	[必須] 。クエリの SQL クエリ文字列。詳細については、「 Azure Cosmos DB SQL 構文リファレンス」を参照してください。
parameters	[必須] 。名前と値のペアとして指定されたパラメーターの JSON 配列。パラメーター配列には、0 から多数のパラメーターを含めることができます。各パラメーターには、次の値が必要です:name: パラメーターの名前。パラメーター名は有効な文字列リテラルで、'@' で始まる必要があります。value: パラメーターの値。有効な JSON 値 (文字列、数値、オブジェクト、配列、ブール値、または null) を指定できます。

プロパティ

説明

query

[必須] 。クエリの SQL クエリ文字列。詳細については、「 Azure Cosmos DB SQL 構文リファレンス」を参照してください。

parameters

[必須] 。名前と値のペアとして指定されたパラメーターの JSON 配列。パラメーター配列には、0 から多数のパラメーターを含めることができます。各パラメーターには、次の値が必要です:name: パラメーターの名前。パラメーター名は有効な文字列リテラルで、'@' で始まる必要があります。value: パラメーターの値。有効な JSON 値 (文字列、数値、オブジェクト、配列、ブール値、または null) を指定できます。

要求の例

次の例では、の文字列パラメーターを使用してパラメーター化された SQL 要求を @author作成します。

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}

SQL クエリの詳細については、「 Azure Cosmos DB の SQL クエリ」を参照してください。

応答の詳細

この操作によって返される一般的な状態コードを次に示します。エラー状態コードの詳細については、「 Azure Cosmos DB の HTTP 状態コード」を参照してください。

コード	説明
200 OK	操作が成功しました。
400 Bad Request	SQL ステートメントの構文が正しくありません。
401 Unauthorized	Authorization または x-ms-date ヘッダーが設定されていません。 401 は、Authorization ヘッダーが無効な認証トークンに設定されている場合にも返されます。
403 Forbidden	認証トークンの有効期限が切れています。
404 Not Found	コレクションはリソースではなくなりました。たとえば、リソースが削除されている可能性があります。

レスポンスヘッダー

この操作は、次の一般的なヘッダーを返します。その他の標準ヘッダーや一般的なヘッダーが返されることもあります。

Standard ヘッダー	説明
Content-Type	Content-Type は application/json です。 Cosmos DB は、常に標準の JSON 形式で応答本文を返します。
日付	応答操作の日時。この日時形式は、UTC で表現される [RFC1123] 日付時刻形式に準拠しています。

カスタムヘッダー	説明
x-ms-item-count	操作によって返される項目数です。
x-ms-continuation	これは、クエリで取得する項目が多い可能性がある場合に返される不透明な文字列です。 x-ms-continuation を後続の要求に要求ヘッダーとして含めることで、クエリの実行を再開できます。
x-ms-request-charge	これは、操作によって消費される要求ユニット (RU) の数です。要求ユニットの詳細については、「 Azure Cosmos DB の要求ユニット」を参照してください。
x-ms-activity-id	操作の一意識別子です。 Cosmos DB 要求の実行をトレースするために使用できます。
x-ms-session-token	後続の要求に使用するセッショントークン。セッションの一貫性のために使用されます。

応答本文

クエリ操作の応答本文は、クエリ対象のリソースの親リソースの _rid と、射影と選択のリソースプロパティを含むリソース配列から構成されます。例として、_rid of XP0mAJ3H-AA= を使用してコレクションの docs パスに対してクエリを実行した場合、応答は次のようになります。

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}

プロパティ	説明
_rid	クエリ内で使用されるコレクションのリソース ID。
_カウント	返される項目数です。
リソースの配列	クエリの結果を含む配列。

クエリの要求本文を構築する

クエリの要求は有効な JSON ドキュメントであり、その中に有効な SQL クエリ文字列を含むクエリ プロパティと、一連の任意パラメーターを含むパラメーター プロパティが含まれている必要があります。各パラメーターには、クエリ内に指定されているパラメーターの名前と値のプロパティが含まれている必要があります。パラメーターの名前は「@」文字で始める必要があります。値は有効な JSON 値、つまり、文字列、整数、ブール値、null のいずれかになります。

クエリ テキストで指定されたパラメーターのサブセットのみを指定すると有効です。これらの指定されていないパラメーターを参照する式は未定義として評価されます。 クエリテキスト内で使用されない追加パラメーターを指定するのにも有効です。

以下は有効なクエリの要求の例です。たとえば、次のクエリには 1 つのパラメーターがあります @id。

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}

次の例にはパラメーターが 2 つあります。1 つには文字列値が入り、もう 1 つには整数値が入ります。

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}

次の例では、SELECT 句内のパラメーターと、パラメーターとしてパラメーター名を介してアクセスされるプロパティが使用されます。

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}

ゲートウェイで処理できないクエリ

継続の間で状態を必要とするクエリは、ゲートウェイで処理できません。これには次のものが含まれます

TOP
ORDER BY
OFFSET LIMIT
集計
DISTINCT
GROUP BY

ゲートウェイで提供できるクエリは次のとおりです。

単純なプロジェクション
フィルター

ゲートウェイで処理できないクエリに対する応答が返されると、状態コード 400 (BadRequest) と次のメッセージが含まれます。

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

クエリ結果の改ページ

クエリ結果は、x-ms-max-item-count 要求ヘッダーと x-ms-continuation 要求ヘッダーに夜改ページをサポートします。 x-ms-max-item-count ヘッダーは、クエリ実行により返すことができる値の最大数を指定します。これは 1 ～ 1000 から指定できます。既定を 100 として設定されます。

クエリは、ゼロから最大 (実行の結果として生成される) x-ms-max-item-count 値までを返します。クエリの結果には、クエリにより返されるドキュメントの実際の数を指定する x-ms-item-count ヘッダーが含まれています。クエリから追加の結果を取得できる場合、応答には x-ms-continuation ヘッダーの空ではない値が含まれます。

クライアントは、別の要求として x-ms-continuation ヘッダーをエコーすることで結果の後続ページをフェッチできます。すべての結果を読むには、空の x-ms-continuation が返されるまで、クライアントはこのプロセスを繰り返す必要があります。

Cosmos DB クエリの実行はサーバー側ではステートレスであり、 x-ms-continuation ヘッダーを使用していつでも再開できます。 x-ms-continuation 値は最後に処理されたドキュメントリソース ID (_rid) を使用し、実行の進行状況を追跡します。したがって、ドキュメントが削除され、ページのフェッチの間に再挿入された場合、ドキュメントがクエリバッチから除外される可能性があります。ただし、x-ms-continuation ヘッダーの動作と形式は将来のサービス更新で変更される場合があります。

次の方法で共有

REST API を使用した Azure Cosmos DB リソースのクエリ

REST を使用してリソースに対してクエリを実行する方法

例

要求の詳細

要求ヘッダー

要求本文

要求の例

応答の詳細

レスポンスヘッダー

応答本文

クエリの要求本文を構築する

ゲートウェイで処理できないクエリ

参照

その他のリソース

次の方法で共有

REST API を使用した Azure Cosmos DB リソースのクエリ

REST を使用してリソースに対してクエリを実行する方法

例

要求の詳細

要求ヘッダー

要求本文

要求の例

応答の詳細

レスポンス ヘッダー

応答本文

クエリの要求本文を構築する

ゲートウェイで処理できないクエリ

クエリ結果の改ページ

参照

その他のリソース

レスポンスヘッダー