如何使用Postman通过Cosmos REST API查询单个或多个Cosmos文档？

一、查询一个/多个Cosmos文档（Postman两种实现方式） #

方式1：用Postman Cosmos DB扩展可视化查询 #

• 打开Postman，在左侧菜单栏「Integrations」中搜索并安装Cosmos DB扩展
• 新增Cosmos DB连接：填入你的Cosmos DB账户终结点、账户密钥，选择目标数据库和容器
• 在扩展的查询编辑器中编写SQL语句，例如：

  -- 查询所有文档
  SELECT * FROM c
  -- 按条件查询多个文档
  SELECT c.id, c.title FROM c WHERE c.category = 'books'
  -- 查询单个文档
  SELECT * FROM c WHERE c.id = 'sample-doc-001'
  

• 点击「Execute」即可获取查询结果

方式2：直接发送POST请求执行SQL查询 #

• 新建POST请求，URL格式：

  https://<你的Cosmos账户名>.documents.azure.com/dbs/<数据库ID>/colls/<容器ID>/docs
  

• 设置请求头：
  • x-ms-documentdb-isquery: True
  • x-ms-version: 2021-05-15（建议使用较新的API版本）
  • Content-Type: application/query+json
• 授权设置：在「Authorization」标签选择Azure Cosmos DB类型，填入账户名和账户密钥，Postman会自动生成授权头
• 请求体（支持参数化查询的JSON格式）：

  {
    "query": "SELECT * FROM c WHERE c.id = @targetId",
    "parameters": [
      {
        "name": "@targetId",
        "value": "sample-doc-001"
      }
    ]
  }
  

• 发送请求，返回匹配的文档结果

二、调用Cosmos REST API检索单个文档（GET请求） #

已知目标文档ID时，直接用GET请求快速获取：

• 新建GET请求，URL格式：

  https://<你的Cosmos账户名>.documents.azure.com/dbs/<数据库ID>/colls/<容器ID>/docs/<目标文档ID>
  

• 设置请求头：
  • x-ms-version: 2021-05-15
  • 授权设置同上述步骤：选择Azure Cosmos DB类型，填入账户名和密钥
• 发送GET请求，响应体即为该文档的完整JSON内容

关键注意事项 #

• 确保使用的账户密钥拥有读取权限（至少为Read角色）
• URL中的<数据库ID>、<容器ID>、<文档ID>必须与Cosmos DB中实际ID完全一致（区分大小写）
• API版本请与你的Cosmos DB账户兼容，可在Azure门户的Cosmos DB账户页面查看支持版本

内容的提问来源于stack exchange，提问作者Nicholas Hill