Azure DocumentDB 的数据 API（预览版）

Azure DocumentDB 的数据 API 是一个 https 接口，开发人员无需数据库驱动程序即可访问数据并与之交互。它通过 HTTP 请求启用控制平面和聚合操作，简化了数据操作。此 API 非常适合 Web 应用程序，提供对数据库的安全且可缩放的访问。

在 Azure DocumentDB 上启用数据 API

可以使用 Azure 门户、Azure CLI 或 ARM 模板启用或禁用此功能。

在 Azure 门户中启用数据 API 的步骤

转到 Azure 门户
- portal.azure.cn
转到 Azure DocumentDB 群集
打开“功能”边栏选项卡
单击“数据 API”
单击“启用”
验证结果
- “功能”边栏现在应将“数据 API”显示为“已启用”。

通过 ARM 模板在群集上启用数据 API 的步骤

获取连接字符串：
- 从 Azure 门户获取群集的连接字符串。
检索身份验证令牌：
- 在 Windows PowerShell 中运行以下命令：
```
az login
az account get-access-token --resource-type arm
```
发送 PATCH 请求：
- 使用 Azure 门户中的连接字符串，并使用以下命令发送 PATCH 请求：
  - 身份验证令牌：使用从 PowerShell 检索到的令牌。
  - 正文：
```
{
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}
```
验证结果：
- 确保响应有效负载包括 "dataApi": {"mode": "Enabled"}。
- 如果遇到错误“此群集不支持数据 API”，请注意，仅新预配的群集支持数据 API。

更新群集配置

请求

方法：PATCH
端点：https://chinanorth3.management.chinacloudapi.cn/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.DocumentDB/mongoClusters/<ClusterName>?api-version=2024-10-01-preview

请求主体

{
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}

获取连接字符串

若要获取群集的连接字符串，请执行以下步骤：

导航到创建的群集。
转到 “设置” 并选择“ 连接字符串”。
复制所提供的数据 API 终结点。

如何使用数据 API

让我们探索受支持的操作以及如何使用数据 API。

Aggregate

使用此命令对集合执行聚合操作。

curl {cluster-name}.data.mongocluster.cosmos.azure.cn:443/data/v1/action/aggregate -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection", "pipeline" : [{"$limit" : 500}]}' --user "{username}:{password}"

{ "documents" : [ { "_id" : { "$oid" : "680957492551581200c73bf8" }, "name" : "Sample Document", "createdAt" : { "$date" : { "$numberLong" : "1745442633506" } }, "tags" : [ "test", "mongo", "sample" ] } ] }

列出数据库

列出指定群集中的所有数据库。

curl {cluster-name}.data.global.mongocluster.cosmos.azure.cn:443/data/v1/action/listDatabases -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{}' --user "{username}:{password}"

{ "databases" : [ { "name" : "testDB", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false }, { "name" : "test", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false } ], "totalSize" : { "$numberInt" : "0" }, "ok" : { "$numberDouble" : "1.0" } }

列出集合

列出特定数据库中的所有集合。

curl {cluster-name}.data.global.mongocluster.cosmos.azure.cn:443/data/v1/action/listCollections -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database": "newDB"}' --user "{username}:{password}"

{ "collections" : [ { "name" : "testCollection", "type" : "collection", "options" : {  }, "info" : { "readOnly" : false, "uuid" : { "$binary" : { "base64" : "mNh96KepTm+NtLtALGxDiw==", "subType" : "04" } } }, "idIndex" : { "v" : { "$numberInt" : "2" }, "name" : "_id_", "key" : { "_id" : { "$numberInt" : "1" } } } } ] }

获取架构

检索特定数据库的架构详细信息。

下面是 .md 文件的格式化版本：

curl {cluster-name}.data.mongocluster.cosmos.azure.cn:443/data/v1/action/getSchema -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection"}' --user "{username}:{password}"

{ "_id" : { "bsonType" : "objectId" }, "name" : { "bsonType" : "string" }, "createdAt" : { "bsonType" : "date" }, "tags" : { "bsonType" : "array" } }

局限性

数据 API 适用于新创建的群集。
数据 API 不支持使用可重用访问令牌进行访问。
仅支持数据平面聚合和有限的控制平面操作。

Last updated on 2025-12-11

通过