你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

常见的 Azure Cosmos DB REST 请求头

以下请求标头对于你可能使用 SQL API 执行的所有任务是通用的:

标头 必需 类型 说明
授权 必须 字符串 请求的授权令牌。 有关生成有效授权令牌的详细信息,请参阅 Cosmos DB 资源上的访问控制
Content-Type PUT、PATCH 和 POST) 上所需的 ( 字符串 对于查询操作的 POST,它必须是 application/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 可选 字符串 一个字符串,指定执行请求的客户端用户代理。 建议使用的格式为 {用户代理名}/{版本}。 例如,官方 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 可选 字符串 针对文档和附件的读取选项的一致性级别替代。 有效值为:Strong、Bounded、Session 或 Eventual (,按最强到最弱) 顺序排列。 替代必须与帐户配置的一致性级别相同或更弱。
x-ms-continuation 可选 字符串 如果有更多结果需要读取,则为查询和读取源操作返回的字符串标记。 客户端可以通过重新提交将 x-ms-continuation 请求标头设置为此值的请求来检索下一页结果。
x-ms-date 必须 Date 按 RFC 1123 日期格式表示的请求日期,以协调世界时表示,例如,2015 年 4 月 8 日星期五 03:52:31 GMT。
x-ms-max-item-count 可选 Number 一个整数,指示每页返回的最大项数。 可以指定 -1 的 x-ms-max-item-count,让服务确定最佳项计数。 这是 x-ms-max-item-count 的建议配置值
x-ms-documentdb-partitionkey 可选 Array 请求的文档或附件操作的分区键值。 当集合定义包含分区键定义时,对文档和附件执行的操作是必需的。 此值用于将查询范围限定为与分区键条件匹配的文档。 根据设计,它是一个单分区查询。 在 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 可选 Number 用于 更改源 请求。 用于读取数据的分区键范围 ID。
x-ms-cosmos-allow-tentative-writes 可选 布尔 对于配置了多个写入位置的 Azure Cosmos 帐户,当此标头设置为 true 时,Azure Cosmos DB 将允许写入所有位置。 将此标头的值设置为 false 的写入请求 (或者如果标头不存在) 将失败并显示 403 响应状态代码,并显示错误消息“不允许在区域中写入”。

另请参阅