自定义 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 请求进行身份验证。

[
  {
    ...,
    "run_as_user_id": "628e47baf4c2ac2796fc8a91"
  }
]

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

[
  {
    ...,
    "run_as_system": true
  }
]

授权

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

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

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

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

[
  {
     ...,
     "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 标头，则响应将使用端点配置中指定的默认数据格式。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/ejson" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

{
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

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

验证请求

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

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

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

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{ "name": "Bob" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "name": "Alice" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZXN0LWN1c3RvbS1lbmRwb2ludHMtZWhtenQiLCJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoyMTQ1OTE2ODAwfQ.pIMvnXWrcDvmPzmE33ZPrwkBAFSwy-GxW8sP-qLtYiw" \
  -d '{ "name": "Carlos" }'

授权请求

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

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/passwordRequired?secret=Super5ecr3tPa55w0rd" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "data": "VGhpcyBpcyBzb21lIGRhdGEgdGhhdCB3YXMgZW5jb2RlZCBhcyBhIEJhc2U2NCBBU0NJSSBzdHJpbmc=" }'

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 -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/sendMessage" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -H "Endpoint-Signature: sha256=d4f0537db4e230d7a6028a6f7c3bb1b57c9d16f39176d78697e559ac333e0b36" \
  -d '{ "message": "Hello!" }'