自定义 HTTPS 端点

基本 URL

应用中的端点共享一个基本 URL。该 URL 使用 App ID 来专门指向您的应用。

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

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

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

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

端点路由

每个 HTTPS 端点都有一个用作端点名称的路由。端点的路由是任意的，并且特定于您的应用。但是，它出现在端点 URL 路径中，因此应代表路由执行的操作。

路由名称必须以正斜杠 (/) 开头，可包含其他正斜杠来表示嵌套路径。

/my/nested/route

您可以通过将端点的路由附加到应用的基本 URL 并发送 HTTP 请求来调用该端点。

https://data.mongodb-api.com/app/<App ID>/endpoint/my/nested/route

HTTP 方法

应用程序中的每个端点都会处理一个或多个 HTTP 方法 对于给定的路线。例如，您可能有一个路由，它可接受用于创建新资源的POST GET请求。

您可以定义多个自定义端点，这些端点为同一路由提供服务，但处理不同的请求方法。或者，您可以为处理所有方法的路由定义单个端点。

自定义端点支持以下标准 HTTP 方法：

• 获取

• 发布

• PUT

• 修补

• 删除

身份验证

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

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

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

授权

端点可以要求已通过身份验证的用户在请求中提供其他授权信息。您可以通过配置端点函数来为每个自定义端点定义授权方案。

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

要了解如何为特定函数配置授权，请参阅定义函数。

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

访问请求数据

自定义端点 Request 对象表示调用端点的 HTTP 请求。您可以访问传入请求的标头、查询参数和正文数据。

{
  "headers": { "<Header>": ["<Header Value>"] },
  "query": { "<Query Parameter>": "<Parameter Value>" },
  "body": <BSON.Binary>
}

{
  "regions": "na&eu",
  "currency": "USD"
}

{
  "Content-Type": ["application/json"],
  "Accept": ["application/json"],
  "X-CustomHeader": ["some-value", "some-other-value"]
}

// Convert the request body to a JSON string
const serialized = request.body.text();
// Parse the string into a usable object
const body = JSON.parse(serialized);

返回 HTTPS 响应

自定义端点 Response Realm 对象允许你配置发送回调用方的 HTTPS 响应。你可以制定状态代码、自定义标头以及在响应正文中包含数据。

response.setStatusCode(201);

response.setBody(
  "{'message': 'Hello, World!'}"
);

response.setHeader(
  "Content-Type",
  "application/json"
);

response.addHeader(
  "Cache-Control",
  "max-age=600"
);
response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)

例子

考虑一个端点函数，它解析传入的 POST 请求的正文，将解析后的正文存储在 MongoDB 集合中，然后响应调用方：

exports = async function MyCustomEndpoint(request, response) {
  try {
    // 1. Parse data from the incoming request
    if (request.body === undefined) {
      throw new Error(`Request body was not defined.`);
    }
    const body = JSON.parse(request.body.text());
    // 2. Handle the request
    const { insertedId } = await context.services
      .get("mongodb-atlas")
      .db("myDb")
      .collection("myCollection")
      .insertOne({ date: new Date(), requestBody: body });
    // 3. Configure the response
    response.setStatusCode(201);
    // tip: You can also use EJSON.stringify instead of JSON.stringify.
    response.setBody(
      JSON.stringify({
        insertedId,
        message: "Successfully saved the request body",
      })
    );
  } catch (error) {
    response.setStatusCode(400);
    response.setBody(error.message);
  }
};

此函数接收以下 POST 请求：

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/custom" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "type": "event",
    "date": "2024-01-01T00:00:00.000Z",
    "name": "New Year Begins",
    "comment": "Happy New Year!"
  }'

{
  "message": "Successfully saved the request body",
  "insertedId": "639a521bbdec9b85ba94014b"
}

该函数验证传入请求的正文已定义后，会将解析后的正文作为新文档存储在名为 myCollection 的集合中。生成的输出显示配置的响应，其中包括自定义消息和 insertedId。

选择响应数据格式

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

验证请求

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

一般来说，与凭证标头相比，使用访问令牌进行持有者身份验证具有更高的吞吐量且更安全。尽可能使用访问令牌而不是凭证标头。该令牌允许您运行多个请求，而无需重新验证用户身份。它还允许您从实施 CORS 的 Web 浏览器发送请求。

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

curl -X GET \
   -H 'Authorization: Bearer <AccessToken>' \
   -H 'Content-Type: application/json' \
   https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello

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

授权请求

根据端点配置，您的请求可能需要包含其他授权信息。