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

使用 REST API 查询 Azure Cosmos DB 资源

项目
08/05/2023

Azure Cosmos DB 是一种全球分布式多模型数据库，支持多个 API。本文介绍如何使用 REST 通过 SQL API 查询资源。

如何使用 REST 查询资源？

若要对资源执行 SQL 查询，请执行以下操作：

使用 JSON 对资源路径执行方法， POST 其中 query 属性设置为 SQL 查询字符串，并将“parameters”属性设置为可选参数值的数组。
将 x-ms-documentdb-isquery 标头设置为 True。
将 Content-Type 标头设置为 application/query+json。

有关演示如何使用 .NET 对资源执行 SQL 查询的示例，请参阅 REST from .NET Sample。

示例

下面是对文档资源执行的 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) 表示。 Fri, 08 Apr 2015 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` 才能返回查询指标

请求正文

请求正文应是包含 SQL 查询和参数的有效 JSON 文档。如果输入格式不正确或 SQL 语法无效，操作将失败并返回“400 错误的请求”错误。

如果网关无法提供查询，你还将收到 400 错误请求。

属性	说明
query	“必需”。查询的 SQL 查询字符串。有关详细信息，请参阅 Azure Cosmos DB SQL 语法参考。
parameters	“必需”。以名称/值对形式指定的参数的 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 格式返回响应正文。
Date	响应操作的日期时间。此日期时间格式符合以 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，以及包含投影和选择操作资源属性的资源数组构成。根据示例，如果对 _rid 为 XP0mAJ3H-AA= 的集合的 docs 路径执行了查询，则响应如下所示：

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

属性	说明
_摆脱	查询中使用的集合的资源 ID。
_计数	返回的项数。
资源数组	包含查询结果的数组。

构建查询请求正文

查询请求必须是一个有效的 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"}  
     ]  
}

网关无法提供服务的查询

网关无法为需要跨延续状态的任何查询提供服务。这包括：

TOP
ORDER BY
OFFSET LIMIT
聚合
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 值使用上次处理的文档资源 ID (_rid) 来跟踪执行的进度。因此，如果在提取页面之间删除并重新插入文档，则可能会从任何查询批处理中排除文档。但是，x-ms-continuation 标头的行为和格式可能会在将来的服务更新中更改。

通过