使用 REST API 查詢 Azure Cosmos DB 資源

Azure Cosmos DB 是全域散發的多模型資料庫，並可支援多個 API。 本文說明如何使用 REST 來使用 SQL API 查詢資源。

如何使用 REST 查詢資源？

若要在資源上執行 SQL 查詢，請執行下列作業：

• POST使用 JSON 對資源路徑執行方法， query 並將 屬性設定為 SQL 查詢字串，並將 「parameters」 屬性設定為選擇性參數值的陣列。
• 將 x-ms-documentdb-isquery 標頭設定為 True。
• 將 Content-Type 標頭設定為 application/query+json。

如需示範如何使用 .NET 對資源執行 SQL 查詢的範例，請參閱 .NET 範例中的 REST。

範例

以下是文件資源的範例 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 資源上的存取控制。

要求標頭

下表包含用來執行查詢作業的一般標頭。

標準標頭	描述
授權	必要。 驗證類型和簽章權杖。 主要金鑰語彙基元允許這項作業。 如需詳細資訊，請參閱Cosmos DB 資源上的存取控制。
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) 表示。 2015 年 4 月 8 日星期五 03:52:31 GMT。
x-ms-documentdb-isquery	必要。 這個屬性必須設定為 true。
x-ms-max-item-count	選擇項。 若要透過結果集分頁，請將此標頭設定為要在單一頁面中傳回的最大項目數。
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	選擇項。 對於未針對單一資料分割索引鍵進行篩選的任何查詢，都必須設定為 true。 針對單一資料分割索引鍵值進行篩選的查詢只會針對單一分割區執行，即使此設定為 true 也一樣。
x-ms-documentdb-populatequerymetrics	選擇項。 必須設定為 True 才能傳回查詢計量

要求本文

要求主體應該是有效的 JSON 文件，其中包含 SQL 查詢和參數。 如果輸入的格式不正確或是無效的 SQL 語法，作業會因為「400 不正確的要求」錯誤而失敗。

如果 閘道無法提供查詢，您也會收到 400 錯誤的要求。

屬性	Description
查詢	必要。 查詢的 SQL 查詢字串。 如需詳細資訊，請參閱 Azure Cosmos DB SQL 語法參考。
參數	必要。 指定為名稱值組之參數的 JSON 陣列。 參數陣列可以包含從零到許多參數。每個參數都必須有下列值：name：參數的名稱。 參數名稱必須是有效的字串常值，並以 '@' 開頭。value：參數的值。 可以是任何有效的 JSON 值 (字串、數字、物件、陣列、布林值或 null)。

要求範例

下列範例會使用 的 @author 字串參數建立參數化 SQL 要求。

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 確定	作業成功。
400 不正確的要求	SQL 陳述式的語法不正確。
401 未經授權	未設定 Authorization 或 x-ms-date 標頭。 當 Authorization 標頭設為無效的授權權杖時，也會傳回 401。
403 禁止	授權權杖已過期。
404 找不到	集合不再是資源。 例如，資源可能已遭刪除。

回應標頭

此作業會傳回下列常見的標頭。 可能會傳回其他的標準和一般標頭。

標準標頭	描述
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 以及包含可供投射和選取之資源屬性的資源陣列所組成。 根據此範例，如果在集合的 docs 路徑上執行查詢 (_rid 為 XP0mAJ3H-AA=)，則回應如下所示：

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

屬性	描述
_擺脫	查詢中使用的集合資源識別碼。
_計數	傳回的項目數。
資源陣列	含有查詢結果的陣列。

建置查詢要求主體

查詢要求必須是有效的 JSON 文件，其中包含 query 屬性 (包含有效的 SQL 查詢字串) 和 parameters 屬性 (包含選擇性參數陣列)。 每一個參數都應該有查詢中指定之參數的 name 和 value 屬性。 參數名稱必須以 "@" 字元開頭。 值可以是任何有效的 JSON 值 – 字串、整數、布林值和 null。

它只能指定 查詢 文字中指定的參數子集。 參考這些未指定參數的運算式會評估為 undefined。 這也適用於指定未使用於 query 文字的其他參數。

有效查詢要求的一些範例如下所示。 例如，下列查詢具有單一參數 @id 。

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

下列範例有兩個參數，一個具有字串值，另一個具有整數值。

{  
    "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"}  
     ]  
}  

閘道無法提供的查詢

閘道無法提供需要跨接續狀態的任何查詢。 這包括：

• 頂端
• 排序依據
• 位移限制
• 彙總
• 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 request 標頭的分頁。 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 值會使用最後處理的文件資源識別碼 (_rid) 來追蹤執行的進度。 因此，如果在擷取頁面之間刪除並重新插入檔，則檔可能會從任何查詢批次中排除。 不過，在未來的服務更新中 x-ms-continuation 標頭的行為和格式可能會變更。

另請參閱

• Azure Cosmos DB
• Azure Cosmos DB SQL API
• Azure Cosmos DB SQL API SDK
• 來自 .NET 的 REST 範例