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

常见的 Azure Cosmos DB REST 请求标头

SQL API 可能执行的所有任务都有以下请求标头:

页眉 必填 类型 描述
授权 必填 字符串 请求的授权令牌。 有关生成有效授权令牌的详细信息,请参阅 Cosmos DB 资源 的访问控制
内容类型 必需(在 PUT、PATCH 和 POST 上) 字符串 对于查询操作的 POST,它必须 application/query+json

对于 PATCH 操作,它必须 应用程序/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 自选 字符串 针对文档和附件的读取选项的一致性级别替代。 有效值为:Strong、Bounded、Session 或 Eventual(以最强到最弱的顺序)。 重写必须与帐户配置的一致性级别相同或弱。
x-ms-continuation 自选 字符串 如果要读取更多结果,则为查询和读取源操作返回的字符串令牌。 客户端可以通过重新提交请求并将 x-ms-continuation 请求标头设置为此值来检索下一页结果。
x-ms-date 必填 日期 每个 RFC 1123 日期格式的请求日期(例如,2015 年 4 月 8 日 03:52:31 GMT)表示的请求日期。
x-ms-max-item-count 自选 一个整数,指示每页要返回的最大项数。 可以指定 x-ms-max-item-count of -1,使服务确定最佳项计数。 这是 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 自选 用于 更改源 请求。 用于读取数据的分区键范围 ID。
x-ms-cosmos-allow-tentative-writes 自选 布尔 如果为配置了多个写入位置的 Azure Cosmos 帐户将此标头设置为 true,则 Azure Cosmos DB 将允许写入所有位置。 将此标头的值设置为 false(或者标头不存在)的写入请求将失败,出现 403 响应状态代码,并显示错误消息“不允许在区域中写入”。

另请参阅