查詢文件
您可以針對 Cosmos DB 中的 「colls」 資源執行 post，以查詢集合中的任意 JSON 檔。 Cosmos DB 的 sql 語法提供階層式、關聯式和空間查詢運算子來查詢和專案檔案。 如需在 Cosmos DB 中查詢資源的詳細資訊，請參閱查詢資源。
要求
| 方法 | 要求 URI | Description |
|---|---|---|
| post | HTTPs://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs | 請注意，{databaseaccount} 是您訂用帳戶下建立的 Cosmos DB 帳戶名稱。 {db-id} 值是使用者產生的資料庫名稱/識別碼，而不是系統產生的識別碼 (rid) 。 {coll-id} 值是集合的名稱。 |
標題
如需所有 Cosmos DB 要求所使用的標頭，請參閱常見的 Azure Cosmos DB REST 要求標頭 。
| 標頭 | 必要 | 類型 | Description |
|---|---|---|---|
| x-ms-documentdb-isquery | 必要 | Boolean | 必須設定為 True，表示 POST 是查詢。 |
| Content-Type | 必要 | String | 必須設定為 application/query+json的字串。 |
| x-ms-max-item-count | 選擇性 | 數字 | 整數，表示每個頁面要傳回的專案數目上限。 查詢不會傳回每個頁面指定的專案數目，但根據集合效能層級及其大小可能會較少。 您可以指定 -1 的 x-ms-max-item-count，讓服務判斷最佳的專案計數。 這是 x-ms-max-item-count 的建議組態值。 |
| x-ms-continuation | 選用 | String | 如果有更多結果可供讀取，則針對查詢和讀取摘要作業傳回的字串權杖。 用戶端可以重新提交要求，並將 x-ms-continuation 要求標頭設定為此值，以擷取下一頁的結果。 |
| x-ms-documentdb-query-enablecrosspartition | 選擇性 | Boolean | 如果集合已分割，則必須將此設定為 True，以允許跨多個分割區執行。 針對單一分割區索引鍵篩選的查詢，或針對單一資料分割集合篩選的查詢不需要設定標頭。 |
| x-ms-consistency-level | 選用 | String | 這是一致性層級覆寫。 有效值為：強式、限定、會話或最終 (，以最強到最弱) 。 覆寫必須與帳戶設定的一致性層級相同或較弱。 |
| x-ms-session-token | 選用 | String | 搭配工作階段層級一致性使用的字串權杖。 用戶端必須在會話一致性的讀取要求期間回應此標頭的最新讀取值。 |
重要
Content-Type對於 標頭，請勿包含 charset (，也就是 「application/query+json;charset-utf-8「) 。 標頭必須完全如上所示。
主體
| 屬性 | 必要 | 類型 | Description |
|---|---|---|---|
| 查詢 | 必要 | String | 包含 SQL 查詢文字。 如需文法，請參閱 SQL 文法。 |
| parameters | 必要 | Array | 查詢的參數值陣列。 |
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
回應
傳回符合所要求查詢的檔陣列。
標題
如需所有 Cosmos DB 回應所傳回的標頭，請參閱 常見的 Azure Cosmos DB REST 回應標頭 。 重要的回應標頭如下：
| 屬性 | 類型 | Description |
|---|---|---|
| x-ms-continuation | String | 傳回權杖，以從作業擷取更多結果。 用戶端可以使用包含此值的 x-ms-continuation 要求標頭重新提交要求，以繼續執行。 |
| x-ms-request-charge | 數字 | 作業所耗用的要求單位數目。 |
狀態碼
下表列出此作業所傳回的常見狀態碼。 如需狀態碼的完整清單，請參閱 HTTP 狀態碼。
| HTTP 狀態碼 | Description |
|---|---|
| 200 確定 | 作業成功。 |
| 400 不正確的要求 | 指定的要求是以不正確的 SQL 語法指定，或遺漏必要的標頭。 |
主體
| 屬性 | Description |
|---|---|
| _擺脫 | 這是系統為文件所在的集合所產生的資源識別碼。 |
| _計數 | 這是清單作業所傳回的文件數目。 |
| 文件 | 作業所傳回的文件陣列。 |
檔的屬性
| 屬性 | 描述 |
|---|---|
| id | 這是識別檔的唯一名稱，也就是兩份檔都不能共用相同的 識別碼。 識別碼 不能超過 255 個字元。 |
| <custom> | 任何使用者定義的 JSON。 |
| _擺脫 | 這是 系統產生的屬性。 資源識別碼 (_rid) 是資源模型上每個資源堆疊也是階層式的唯一識別碼。 它是在內部用來放置和導覽文件資源。 |
| _Ts | 這是系統產生的屬性。 代表資源的上次更新時間戳記。 值為時間戳記。 |
| _自我 | 這是系統產生的屬性。 代表資源的唯一可定址 URI。 |
| _Etag | 這是系統產生的屬性，指定開放式並行存取控制所需的資源 etag 。 |
| _附件 | 這是系統產生的屬性，代表權限資源的可定址路徑。 |
{
"_rid": "1KtjAImkcgw=",
"Documents": [
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}
],
"_count": 1
}
範例
POST https://querydemo.documents.azure.com/dbs/1KtjAA==/colls/1KtjAImkcgw=/docs HTTP/1.1
x-ms-continuation:
x-ms-documentdb-isquery: True
x-ms-documentdb-query-enablecrosspartition: True
x-ms-date: Tue, 29 Mar 2016 02:28:32 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3drOlOhFh9plfC0ggZfmHtS3XepVitiIRsd6i1d9PnuW8%3d
Cache-Control: no-cache
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0
x-ms-version: 2015-12-16
Accept: application/json
Content-Type: application/query+json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=604; x-ms-session-token=604
Content-Length: 170
Expect: 100-continue
{
"query": "SELECT * FROM Families f WHERE f.id = @id AND f.Address.City = @city",
"parameters": [
{
"name": "@id",
"value": "AndersenFamily"
},
{
"name": "@city",
"value": "Seattle"
}
]
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT
etag: "00003200-0000-0000-0000-56f9e84d0000"
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/testdb/colls/testcoll
x-ms-quorum-acked-lsn: 602
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 12.38
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668
x-ms-session-token: 0:603
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=
x-ms-gatewayversion: version=1.6.52.5
Date: Tue, 29 Mar 2016 02:28:30 GMT
{
"id": "AndersenFamily",
"LastName": "Andersen",
"Parents": [
{
"FamilyName": null,
"FirstName": "Thomas"
},
{
"FamilyName": null,
"FirstName": "Mary Kay"
}
],
"Children": [
{
"FamilyName": null,
"FirstName": "Henriette Thaulow",
"Gender": "female",
"Grade": 5,
"Pets": [
{
"GivenName": "Fluffy"
}
]
}
],
"Address": {
"State": "WA",
"County": "King",
"City": "Seattle"
},
"IsRegistered": true,
"_rid": "1KtjAImkcgwBAAAAAAAAAA==",
"_self": "dbs/1KtjAA==/colls/1KtjAImkcgw=/docs/1KtjAImkcgwBAAAAAAAAAA==/",
"_etag": "\"00003200-0000-0000-0000-56f9e84d0000\"",
"_ts": 1459218509,
"_attachments": "attachments/"
}