常見的 Azure Cosmos DB REST 要求標頭

發行項
01/29/2025

您可以使用 SQL API 執行的所有工作都使用下列要求標頭：

頁眉	必填	類型	描述
授權	必填	字串	要求的授權令牌。如需產生有效授權令牌的詳細資訊，請參閱 Cosmos DB 資源上的訪問控制
內容類型	必要專案（在 PUT、PATCH 和 POST 上）	字串	針對查詢作業上的 POST，它必須應用程式/query+json。針對 PATCH 作業，它必須 application/json_patch+json。對於附件，必須設定為附件的Mime類型。如需Mime類型的詳細資訊，請參閱建立附件對於所有其他工作，必須是 application/json。
If-Match	選擇性（僅適用於 PUT 和 DELETE）	字串	用來設定開放式並行存取的條件式作業。此值應該是資源的 etag 值。
If-None-Match	選擇性（僅適用於 GET）	字串	只有在資源已變更時，才讓作業有條件地執行。此值應該是資源的 etag。
if-modified-since	選擇性（僅適用於 GET）	日期	傳回 RFC 1123 格式的指定日期之後修改的資源 etag。指定 if-None-Match 時，會忽略
User-Agent	自選	字串	字串，指定執行要求的用戶端使用者代理程式。建議的格式為 {user agent name}/{version}。例如，官方 SQL API .NET SDK 會將 User-Agent 字串設定為 Microsoft.Document.Client/1.0.0.0。自定義使用者代理程式可能類似 ContosoMarketingApp/1.0.0。
x-ms-activity-id	自選	字串	用戶端為作業提供識別碼，此作業會在伺服器回應中回應。建議的值是唯一標識碼。
x-ms-consistency-level	自選	字串	針對檔和附件讀取選項的一致性層級覆寫。有效值為：強式、限定性、會話或最終值（以最強到最弱的順序）。覆寫必須與帳戶設定的一致性層級相同或較弱。
x-ms-continuation	自選	字串	如果有更多要讀取的結果，則為查詢和讀取摘要作業傳回的字串令牌。用戶端可以重新提交要求，並將 x-ms-continuation 要求標頭設定為此值，以擷取下一頁的結果。
x-ms-date	必填	日期	每個 RFC 1123 日期格式的要求日期，以國際標準時間表示，例如，2015 年 4 月 8 日 03：52：31 GMT。
x-ms-max-item-count	自選	數	整數，表示每個頁面要傳回的項目數目上限。您可以指定 -1 的 x-ms-max-item-count，讓服務判斷最佳的項目計數。這是 x-ms-max-item-count 的建議組態值
x-ms-documentdb-partitionkey	自選	陣列	所要求檔或附件作業的數據分割索引鍵值。當集合定義包含分割區索引鍵定義時，針對檔和附件的作業需要。此值可用來將查詢範圍限定於符合分割區索引鍵準則的檔。根據設計，它是單一數據分割查詢。 API 2015-12-16 版和更新版本支援。目前，SQL API 支援單一分割區索引鍵，因此這是只包含一個值的數位。
x-ms-documentdb-query-enablecrosspartition	自選	布爾	當此標頭設定為 true，且您的查詢沒有分割區索引鍵時，Azure Cosmos DB 會跨分割區將查詢扇出。向所有分割區發出個別查詢，以完成展開。若要讀取查詢結果，用戶端應用程式應該取用 FeedResponse 的結果，並檢查 ContinuationToken 屬性。若要讀取所有結果，請持續查看數據，直到 ContinuationToken 為 null 為止。
x-ms-session-token	必要專案（僅限會話一致性）	字串	搭配會話層級一致性使用的字串令牌。如需詳細資訊，請參閱在 Cosmos DB 中使用一致性層級
x-ms-version	必填	字串	Cosmos DB REST 服務的版本。如需支援的 API 版本清單，請參閱 Azure Cosmos DB REST API 參考
A-IM	自選	字串	表示變更摘要要求。必須設定為「累加摘要」，否則省略。
x-ms-documentdb-partitionkeyrangeid	自選	數	用於變更摘要要求。用於讀取數據的數據分割索引鍵範圍標識碼。
x-ms-cosmos-allow-tentative-writes	自選	布爾	當此標頭針對設定多個寫入位置的 Azure Cosmos 帳戶設定為 true 時，Azure Cosmos DB 將允許寫入所有位置。寫入此標頭的值設定為 false（或標頭不存在）的要求將會失敗，並出現 403 回應狀態代碼，並出現錯誤訊息「不允許區域中寫入」。

另請參閱