HTTP 端点配置文件

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

注意

本页介绍一种旧版配置文件格式。仅当使用已弃用的 realm-cli时才应使用此信息。

使用 App Services CLI 拉取或从用户界面导出的任何配置文件都使用最新配置版本。有关当前配置文件格式的详细信息，请参阅应用程序配置。

app/
└── http_endpoints/
    ├── config.json
    ├── data_api_config.json
    └── [Deprecated] <Service Name>/
        ├── config.json
        ├── rules/
        │   └── <Rule Name>.json
        └── incoming_webhooks/
            └── <Webhook Name>/
                ├── config.json
                └── source.js

自定义 HTTPS 端点配置

在http_endpoints/config.json中将应用程序的所有HTTPS endpoints的配置定义为数组。

[
  {
    "route": "<Endpoint route name>",
    "http_method": "<HTTP method>",
    "function_name": "<Endpoint function name",
    "validation_method": "<Authorization scheme>",
    "secret_name": "<Validation Secret Name>",
    "respond_result": <boolean>,
    "fetch_custom_user_data": <boolean>,
    "create_user_on_auth": <boolean>,
    "disabled": <boolean>
  }
]

字段	说明
`route` string	端点路由。
`http_method` string	HTTP方法的类型端点处理。指定``以处理具有单个端点的所有方法。以下之一： `"GET"` `"POST"` `"PUT"` `"PATCH"` `"DELETE"` `"DELETE"` `""`
`function_name` string	与端点关联的函数的名称。该函数应使用端点函数签名。
`validation_method` string	用于验证传入请求的端点授权方案。以下之一： `"SECRET_AS_QUERY_PARAM"` `"VERIFY_PAYLOAD"` `"NO_VALIDATION"`
`secret_name` string	包含字符串的密钥名称。如果`validation_method`设置为`SECRET_AS_QUERY_PARAM`或`VERIFY_PAYLOAD` ，则此密钥用于授权请求。
`respond_result` boolean	如果为`true` ，端点将向客户端返回可自定义的 HTTP 响应。您可以通过调用响应对象上的方法来配置响应。如果未配置响应，端点将返回`200 - Ok`响应，其中包含从端点函数返回的值作为请求正文。如果`false` ，则请求将返回`204 - No Content`响应，正文中不含数据。
`fetch_custom_user_data` boolean	如果为`true` ，则可通过`context.user.custom_data`获取经过身份验证的用户的自定义用户数据文档。如果为`false` ，则不查询用户的自定义数据，并且`context.user.custom_data`为空对象。
`create_user_on_auth` boolean	如果`true` ，如果提供的用户档案成功进行身份验证，您的应用程序会自动创建一个新用户，但未与现有用户关联。此设置对于通过自定义 JSON web token 身份验证提供者与外部身份验证系统集成的应用程序非常有用。如果一个请求包含来自外部系统的与注册用户不对应的有效 JSON web token，则会创建一个以 JSON web token 作为身份的新用户。
`disabled` boolean	启用 ( `false` ) 或禁用 ( `true` ) 端点。

数据 API 配置

在http_endpoints/data_api_config.json中为应用程序生成的数据API 端点定义配置。

{
  "disabled": <boolean>,
  "versions": ["v1"],
  "return_type": "EJSON" | "JSON",
  "create_user_on_auth": <boolean>,
  "run_as_system": <boolean>,
  "run_as_user_id": "<User Account ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

字段	说明
`disabled` boolean	如果为`false`，则未启用数据API。生成的端点不会处理或响应请求。
`versions` string[]	您的应用支持的数据API版本列表。该列表可能包括所有可能版本的子集，但必须按升序列出版本。您无法启用最新版本以外的版本，但此处列出的任何以前启用的版本都将继续有效。可用版本： `"v1"`
`return_type` string	用于 HTTPS 响应正文中端点返回的数据的数据格式。以下之一： `"EJSON"` `"JSON"`
`create_user_on_auth` boolean	如果`true` ，如果提供的用户档案成功进行身份验证，您的应用程序会自动创建一个新用户，但未与现有用户关联。此设置对于通过自定义 JSON web token 身份验证提供者与外部身份验证系统集成的应用程序非常有用。如果一个请求包含来自外部系统的与注册用户不对应的有效 JSON web token，则会创建一个以 JSON web token 作为身份的新用户。
`run_as_user_id` string	应用程序用户的帐号 ID。如果已定义，端点将始终以指定的用户身份运行。不能与 `run_as_user_id_script_source` 一起使用。
`run_as_user_id_script_source` string	返回应用程序用户帐户 ID 的函数的字符串化源代码。如果已定义，端点将在每个请求时执行该函数，并以具有该函数返回的 ID 的用户身份运行。不能与 `run_as_user_id` 一起使用。

[已弃用] HTTP Service

已弃用的旧版 HTTP 服务将分组为/http_endpoints中的命名服务。

http_endpoints/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "http",
  "config": {}
}

字段	说明
`name` String	HTTP 端点服务的名称。它在应用程序的所有 HTTP 端点服务中必须是唯一的，并与其包含目录的名称匹配。
`type` String	对于 HTTP 端点，此值始终为`"http"` 。
`config` String	该服务的其他配置选项。 HTTP 端点当前没有其他配置选项。

[已弃用] 服务操作规则

您可以在服务的rules/目录中定义服务操作规则。每条规则都映射到与该规则同名的自己的.json配置文件。

http_endpoints/<Service Name>/rules/<Rule Name>.json

{
  "name": "<Rule Name>",
  "actions": ["<Service Action Name>"],
  "when": { <JSON Rule Expression> }
}

字段	说明
`name` String	服务规则的名称。该名称的长度最多为 64 个字符，并且只能包含 ASCII 字母、数字、下划线和连字符。
`actions` Array<String>	应用规则的HTTP 操作列表。
`when` Document	当规则应用于给定请求时，规则表达式的计算结果为`true` 。

[已弃用] 传入 Webhook

配置

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/config.json

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "respond_result": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

字段

说明

name

String

Webhook 的名称。它在 HTTP 端点服务中的所有 Webhook 中必须是唯一的，并与其包含目录的名称匹配。

can_evaluate

JSON Expression (default: true)

如果允许执行 Webhook，则JSON 表达式的计算结果为true 。 Atlas App Services 会对每个传入请求的该表达式求值。

disable_arg_logs

Boolean

如果true ，App Services 将省略函数执行日志条目中为 Webhook 提供的参数。

run_as_authed_user

Boolean

如果为true ，则 Webhook 函数在每个传入请求指定的现有应用程序用户的上下文中运行。传入请求必须在请求正文或请求标头中包含用户的身份验证提供者档案。

提示

有关如何指定档案的示例，请参阅配置服务 Webhook [已弃用]。

run_as_user_id

String

函数执行时始终使用的App Services 用户的唯一 ID。不能与run_as_user_id_script_source或run_as_authed_user一起使用。

run_as_user_id_script_source

String

一个字符串化函数，在调用 Webhook 时运行，并返回该函数执行时使用的App Services 用户的唯一 ID。不能与run_as_user_id或run_as_authed_user一起使用。

respond_result

Boolean

如果true ，则 App Services 将 Webhook 函数返回值作为 HTTP 响应正文包含在内，发送到发起 Webhook 请求的客户端。

fetch_custom_user_data

Boolean

如果true ，App Services 会查询请求用户的自定义用户数据，如果存在，则将数据公开为context.user.custom_data属性上的对象。

仅当run_as_authed_user设置为true时，此选项才可用。

create_user_on_auth

Boolean

如果true ，App Services 会根据提供的用户档案自动创建一个新用户，前提是这些用户档案与现有用户不匹配（例如其他用户都没有指定的电子邮件地址）。在请求创建新用户时，必须启用与凭证对应的身份验证提供程序。

仅当run_as_authed_user设置为true时，此选项才可用。

options

Document

包含 Webhook 配置选项的文档。

{
  "httpMethod": "<HTTP Method>",
  "validationMethod": "<Webhook Validation Method>",
  "secret": "<Webhook Secret>"
}

字段	说明
`httpMethod` String	Webhook 接受的 HTTP 方法类型。传入的 Webhook 请求必须使用此方法。
`validationMethod` String	Webhook 使用的请求验证方法的名称。有效选项： `"VERIFY_PAYLOAD"` `"SECRET_AS_QUERY_PARAM"` `"NO_VALIDATION"`
`secret` String	用于验证传入的 Webhook 请求的密钥值。

源代码

您可以在 Webhook 目录下的source.js文件中定义 Webhook 函数的源代码。每个文件都必须导出在请求调用 Webhook 时运行的主函数。

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/source.js

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

来年

什么是 Atlas App Services？