数据API端点 [已弃用]

在此页面上

何时使用 Data API

基本 URL
设置数据 API
身份验证
授权
响应类型
访问权限
API 版本
调用 Data API 端点
选择 API 版本
指定请求数据格式
选择响应数据格式
验证请求
授权请求

Atlas Device Sync 、 Atlas Edge Server 、 Data API和HTTPS endpoints均已弃用。有关详细信息，请参阅弃用页面。

Data API 可让您使用标准 HTTPS 请求安全地读写数据。API 包括自动生成的端点，每个端点代表一个 MongoDB 操作。您可以使用该端点在 MongoDB 数据源中创建、读取、更新、删除和聚合文档。

示例，此 POST 请求通过调用insertOne 端点将文档存储在关联集群中：

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne" \
  -X POST \
  -H "Content-Type: application/ejson" \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "hello",
    "document": {
      "text": "Hello, world!"
    }
  }'

{ "insertedId": "5f1a785e1536b6e6992fd588" }

有关所有可用端点的详细 API 参考信息，请参阅 Data API OpenAPI 参考。

注意

私有端点不支持数据API端点。

何时使用 Data API

您可以使用 Data API 与任何支持 HTTPS 请求的应用或服务集成。例如，您可以：

从移动应用程序查询 Atlas
在 CI/CD 工作流程中访问测试数据和日志事件
将 Atlas 集成到联合 API 网关
通过 MongoDB 驱动程序或 Realm SDK 从当前不支持的环境中进行连接

与通过已连接 MongoDB 驱动程序调用的相应 MongoDB 操作相比，通过 API 端点调用的操作可能需要更长的时间。对于高负载使用案例和延迟敏感的应用程序，我们建议使用 MongoDB 驱动程序直接连接到数据库。要了解更多信息，请访问 MongoDB 驱动程序文档。

基本 URL

应用中的 Data API 端点共享一个基本 URL。该 URL 使用 App ID 来专门指向您的应用，并指定要调用哪个版本的 Data API。每个端点都有一个唯一 URL，该 URL 是通过将端点的路由附加到应用的基本 URL 形成的。

全局部署的应用程序采用以下格式：

端点基本 URL（本地应用）：

https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

本地部署应用中的终结点使用特定于应用的部署地区的基本 URL（例如us-east-1.aws）：

端点基本 URL（本地应用程序）

https://<Region>.<Cloud>.data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

设置数据 API

您可以通过 App Services UI 或使用 App Services CLI 部署配置文件，来配置应用的 Data API：

单击左侧导航菜单中的 HTTPS Endpoints ，然后选择Data API标签页。
为应用启用 Data API。这会生成端点，该端点可以访问链接到应用的任何 MongoDB 数据源。
选择身份验证方法并启用身份验证提供者。
选择响应类型。
保存 Data API 配置。
通过为关联的数据源中的集合定义规则来配置访问权限，以允许请求安全地读取和写入数据。
保存并部署应用程序。

拉取应用的最新版本。
```
appservices pull --remote="<Your App ID>"
```
定义数据API配置文件。
https_endpoints/data_api_config.json
```
{
  "disabled": false,
  "versions": ["v1"],
  "can_evaluate": {},
  "return_type": <"JSON" | "EJSON">
}
```
部署您的应用。
```
appservices push
```

身份验证

Data API 端点在特定用户的上下文中运行，这允许您的应用强制执行规则并验证每个请求的文档模式。

默认情况下，端点使用“应用程序身份验证”，要求每次请求都包含一个应用程序用户的凭据，如 API 密钥或 JWT。您还可以配置其他自定义身份验证方案，以满足应用程序的需求。

有关如何对请求进行身份验证的示例，请参阅对 Data API 请求进行身份验证。

应用程序身份验证要求用户使用您为应用启用的身份验证提供者。请求可以包含由身份验证提供者授予的访问令牌，也可以包含用户登录时使用的凭据（例如他们的 API 密钥或电子邮件和密码）。

用户ID身份验证将所有请求作为单个预选的应用程序用户运行。如果无论谁调用端点，所有请求都应具有相同的权限，这非常有用。

要选择用户，请在应用程序的 Data API 配置中指定其用户帐户 ID。

http_endpoints/data_api_config.json

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

脚本身份验证会调用函数来确定请求以哪个应用程序用户身份运行。您可以使用它来实现自定义身份验证和授权方案。

该函数必须以ID string或的形式返回现有应用程序用户的帐户{ "runAsSystem": true } MongoDBCRUD，才能以对和聚合 API 具有完全访问权限且不受任何规则、角色或权限影响的系统用户身份运行请求。

要定义函数，请在应用的数据 API 配置中指定源代码。

http_endpoints/data_api_config.json

[
  {
    ...,
    "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}"
  }
]

授权

可以要求经过身份验证的用户在每个请求中提供其他授权信息。您可以在 Data API 配置中为所有生成的 Data API 端点定义授权方案。

端点本身支持一组内置授权方案，这些方案使用密钥字符串来证明请求已获授权。您还可以定义自定义授权方案，可以将其与内置方案一起使用或代替内置方案。

内置授权模式

端点支持以下内置授权方案：

所有通过身份验证的用户都有权调用端点。经过身份验证的请求不需要包含授权信息。

经过身份验证的用户必须证明他们有权通过包含特定string作为 secret查询参数的值来调用端点。

您在string 密钥中定义该，并在端点配置中按名称引用该密钥。

http_endpoints/data_api_config.json

[
  {
    ...,
    "verification_method": "SECRET_AS_QUERY_PARAM",
    "secret_name": "secret_verification_string"
  }
]

要学习；了解如何在请求中包含密钥，请参阅授权请求。

经过身份验证的用户必须通过包含 Endpoint-Signature 标头来证明他们有权调用端点，该标头包含从请求正文生成的十六进制编码的 HMAC SHA-256 哈希和密钥string 。

您在string 密钥中定义该，并在端点配置中按名称引用该密钥。

要学习；了解如何对请求进行签名，请参阅授权请求。

自定义授权模式

您可以定义自定义授权表达式，以确定是否允许运行传入的已验证请求。该表达式针对每个请求进行计算，并且其计算结果必须为 true 才能允许请求。如果表达式的计算结果为 false，则请求不会获得授权并出现错误，以失败告终。未通过授权的请求不计入应用的计费使用量。

授权表达式可使用 %%user 等变量，根据调用用户的数据进行授权，或使用 %%request 等变量，根据每次传入请求的具体情况做出决定。

要定义自定义授权方案，请在应用的 Data API 配置中指定如下表达式：

http_endpoints/data_api_config.json

{
  ...,
  "can_evaluate": {
    "%%request.requestHeaders.x-secret-key": "my-secret"
  }
}

响应类型

端点可按 JSON 或 EJSON 这两种数据格式之一返回数据。

默认情况下，端点将返回 JSON，这是一种被现代语言和平台广泛支持的标准数据格式。但是，JSON 无法表示可以存储在 MongoDB 中的每种数据类型，并缺少某些数据类型的类型信息。

您还可以配置端点以返回 EJSON，它使用结构化 JSON 对象来全面表示 MongoDB 支持的类型。这会保留响应中的类型信息，但要求应用程序知道如何解析和使用 EJSON。

提示

官方 MongoDB 驱动程序包含使用 EJSON 的方法。您也可以在 npm 上下载像 bson 这样的独立解析器。

https_endpoints/data_api_config.json

{
   "return_type": "JSON"
}

https_endpoints/data_api_config.json

{
   "return_type": "EJSON"
}

访问权限

Data API 使用应用程序的数据访问规则来确定用户是否可以读写数据。要支持 Data API 请求访问特定集合，您必须首先为此集合定义规则。

还可以设置 IP 访问列表，以提高安全性。

API 版本

Data API 使用内置版本控制方案来随着时间的推移升级端点，同时保持向后兼容性。传入请求可以指定在请求 URL 中使用哪个版本的端点，并且 Data API 可以提供您已启用的任何版本。

您必须先启用新版本，用户才能使用该版本调用端点。您可以始终启用最新的 Data API 版本。但是，新版本发布后，无法启用旧版本。

目前支持以下版本：

beta
v1

调用 Data API 端点

可以从任何标准 HTTP 客户端调用 Data API 端点。每个请求都可以在请求正文中包含配置标头和参数。

发出请求时需要使用 HTTP/1.1 或更高版本。

选择 API 版本

Data API 请求指定要在请求的 URL 中使用的 API 版本。请求可以指定为应用启用的任何版本。

https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

指定请求数据格式

数据 API 请求必须包含 Content-Type 标头，以指定请求正文中使用的数据格式。

使用 Content-Type: application/json 在数据 API 请求正文中表示标准 JSON 类型。
使用 Content-Type: application/ejson 表示数据 API 请求正文中的标准 JSON 类型和其他 EJSON 类型。

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/ejson' \
  -H 'Accept: application/ejson' \
  --data-raw '{
      "dataSource": "mongodb-atlas",
      "database": "learn-data-api",
      "collection": "hello",
      "document": {
        "_id": { "$oid": "629971c0d71aad65bd59c595" },
        "greeting": "Hello, EJSON!",
        "date": { "$date": { "$numberLong": "1654589430998" } }
      }
  }'

{ "insertedId": { "$oid": "629971c0d71aad65bd59c595" } }

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/updateOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "filter": { "greeting": "Hello, world!" },
     "update": {
         "$set": { "greeting": "Hello, universe!" }
     }
  }'

{ "matchedCount": 1, "modifiedCount": 1 }

选择响应数据格式

请求可以包含 Accept 标头，以请求响应正文的特定数据格式（JSON 或 EJSON）。如果请求不包含有效的 Accept 标头，响应将使用数据 API 配置中指定的数据格式。

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/ejson' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": { "$oid": "629971c0d71aad65bd59c545"},
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": "629971c0d71aad65bd59c545",
  "greeting": "Hello, Leafie!",
  "date": "2022-06-07T08:10:30.998Z"
}

验证请求

如果端点配置为使用应用程序身份验证，则必须在每个请求中包含有效的用户访问令牌或登录档案。

通常，使用访问令牌的持有者身份验证具有更高的吞吐量，并且比凭证标头更安全。尽量使用访问令牌，而不是凭证标头。该令牌允许运行多个请求，而无需重新对用户进行身份验证。此外，它还允许从强制执行 CORS 的 Web 浏览器发送请求。

要使用访问令牌，请先通过 App Services 身份验证提供者来对用户进行身份验证。然后，获取从 App Services 返回的访问令牌，并使用持有者令牌方案将其包含在请求的“授权”标头中。有关如何获取和使用访问令牌的详情，请参阅持有者令牌身份验证。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

或者也可以在请求标头中包含用户的有效登录档案。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteWFwcC1hYmNkZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJleHAiOjIxNDU5MTY4MDB9.E4fSNtYc0t5XCTv3S8W89P9PKLftC4POLRZdN2zOICI" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

重要

请勿在面向用户的客户端中使用 API 密钥

如果您从浏览器或其他面向用户的客户端应用程序进行身份验证，请避免使用 API 密钥登录。请改用其他接受用户提供的档案的身份验证提供者。切勿在本地存储 API 密钥或其他敏感档案。

授权请求

根据 Data API 授权配置，您的请求可能需要包含额外的授权信息。

所有通过身份验证的用户都有权调用端点。经过身份验证的请求不需要包含授权信息。

经过身份验证的用户必须证明他们有权通过将端点的密钥string作为 secret查询参数的值来调用端点。

例子

以下 curl请求将密钥查询参数验证与密钥string "12345" 结合使用：

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne?secret=12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

经过身份验证的用户必须证明他们有权调用端点，方法是包含Endpoint-Signature 256标头，该标头包含根据请求正文和端点的密钥生成的十六进制编码的 HMAC SHA-string 哈希值。

Endpoint-Signature: sha256=<hex encoded hash>

您可以使用以下函数生成有效负载签名：

/**
 * Generate an HMAC request signature.
 * @param {string} secret - The secret validation string, e.g. "12345"
 * @param {object} body - The endpoint request body e.g. { "message": "MESSAGE" }
 * @returns {string} The HMAC SHA-256 request signature in hex format.
 */
exports = function signEndpointRequest(secret, body) {
  const payload = EJSON.stringify(body);
  return utils.crypto.hmac(payload, secret, "sha256", "hex");
};

例子

以下curl包括使用密钥值12345签名的有效负载签名标头：

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H "Content-Type: application/json" \
  -H "Endpoint-Signature: sha256=769cd86855787f476afc8b0d2cf9837ab0318181fca42f45f34b6dffd086dfc7" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

后退

Data API和HTTPS endpoints弃用

来年

自定义 HTTPS 端点 [已弃用]