Docs 菜单
Docs 主页
/
MongoDB Atlas
/
Atlas App Services
/
Edge Server - Preview

在Atlas中管理边缘服务器 - 预览

在此页面上

  • 开始之前
  • 为Edge Server创建服务
  • 创建 Edge Server 实例
  • 列出 Edge Server 实例
  • 删除 Edge Server 实例
  • 更新Edge Server的数据模型
  • 对 Edge Server 实例进行故障排除
  • Edge Server 限制

与 Edge Server 兼容的服务是您创建、删除或监控 Edge Server 实例的 Atlas 目的地。

有两种类型的服务可启用您使用Edge Server ：

  • Edge Server服务 ：如果您希望客户端使用Edge Server MongoDB驱动程序和工具连接到 实例，请使用此选项。它会根据您插入的文档推断和更新模式，并提供MongoDB开发人员熟悉的开发者体验。 此服务与Atlas Device SDK不兼容；它会拒绝传入的Atlas Device SDK连接。

  • Device Sync Service（使用 Edge Server）：如果要使用 Atlas Device SDK 和 MongoDB 驱动程序和工具开发客户端应用程序，请使用此选项。此选项涉及更严格的模式实施，SDK 使用该模式在设备之间自动同步对象并处理冲突。

无论您选择哪种类型的服务，边缘服务器都使用Device Sync在Edge Server实例和Atlas之间同步数据。

重要

您稍后无法将 Atlas Device SDK 添加到 Edge Server 服务中

您始终可以将边缘服务器添加到Device Sync服务。 但您不能将Atlas Device SDK连接与Edge Server服务一起使用。

用户不可在服务之间迁移。 如果您从Edge Server Service 开始，但后来想使用Atlas Device SDK开发应用程序，则无法将 Edge Service 中的任何用户转移到新的Device Sync Service。

开始之前

要在Atlas 用户界面中管理边缘服务器，您需要满足以下条件：

  • 具有项目所有者权限的MongoDB Atlas帐户。 要学习；了解如何注册免费帐户，请参阅 Atlas入门。

要使用 Admin API 管理边缘服务器，您需要满足以下条件：

  • 具有项目所有者权限的 MongoDB Atlas 帐户。要了解如何注册免费帐户，请参阅开始使用 Atlas。

  • MongoDB Atlas Admin API 公钥/私钥对。API 密钥必须具有项目所有者权限才能使用 App Services Admin API。

  • 您的应用的内部ObjectId 十六进制string 以及包含您的应用的ID 项目的项目Atlas 。要学习；了解如何查找这些元数据，请参阅获取应用元数据。

为Edge Server创建服务

您可以在数据服务或应用服务中创建与 Edge Server 兼容的服务。

  • 如果只想使用Edge Server或Device Sync和Edge Server开始构建，而不需要其他App Services。 您可以从 Data Services 创建Edge Server服务。

  • 如果要将服务与身份验证、函数、触发条件、HTTPS 端点或值和密钥捆绑在一起，则可以选择 App Services。您可以从 App Services 创建 Device Sync Service，并向其中添加 Edge Server。

1

导航到 Data Services用户界面

当您在Atlas用户界面项目仪表盘盘中选择一个项目时，默认会显示 Data Services标签页。

如果您在 App Services 或 Charts 中，请选择 Data Services 标签页。

2

选择设备和边缘同步

在左侧边栏中，浏览到 Services 部分。选择 Device & Edge Sync。

3

创建服务

选择要创建的服务类型，然后按照提示创建 Edge Server 服务或 Device Sync 服务。

创建Edge Server服务后，您可以立即添加Edge Server实例。

如果您创建Device Sync服务，请单击左侧导航栏中的Edge Server 。 这将打开一个列表，您可以在其中添加和查看Edge Server实例。

单击 Add a server 按钮，然后按照提示命名并创建新的 Edge Server 实例。

1

创建Device Sync应用

请参阅创建App Services App文档。

选择应用程序类型时，请选择 Device Sync 。 配置Device Sync后，您可以将边缘服务器添加到Device Sync应用。

2

将Edge Server实例添加到Device Sync服务

查看Device Sync Service 时，单击左侧导航栏中的Edge Server 。 这将打开一个列表，您可以在其中添加和查看Edge Server实例。

单击 Add a server 按钮，然后按照提示命名并创建新的 Edge Server 实例。

重要

必填字段

要与Edge Server同步的文档必须包含 _id字段，其类型因服务类型而异：

  • Edge Server服务：类型 ObjectId

  • Device Sync Service：类型ObjectId 、 String 、 Long 、 Int 、 UUID

任何没有此字段的文档都无法同步到Edge Server 。

支持的身份验证提供程序

Edge Server 支持部分身份验证提供者。支持的身份验证提供者会有所不同，具体取决于您是使用 Atlas Device SDK 连接，还是使用 MongoDB URI 连接 MongoDB 驱动程序或工具。

您必须至少启用其中一个提供程序，才能让客户端连接到 Edge Server 实例。

支持的 Atlas Device SDK 身份验证提供者

支持的 MongoDB驱动程序身份验证提供者

创建 Edge Server 实例

创建与 Edge Server 兼容的服务后，您可以向其中添加 Edge Server。该服务可以处理多个 Edge Server，每个 Edge Server 都有自己的注册密钥。

1

添加服务器

单击 Add a server。系统会提示您命名 Edge Server。

用户界面提供了一个安装脚本，您可以将其复制并粘贴到要安装Edge Server代码的设备上的终端中。 您还会获得一个令牌，在配置Edge Server实例时将使用该令牌。

2

安装和配置Edge Server代码

将安装脚本复制并粘贴到要安装Edge Server代码的设备的终端中。 有关详细信息，请参阅安装和配置Edge Server实例。

配置并启动Edge Server实例后，其在Edge Server仪表盘的 Health 状态会从 Pending 更改为 Active。

1

对 MongoDB Atlas 用户进行身份验证

使用您的 MongoDB Atlas API 密钥对调用管理员用户身份验证端点：

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

如果身份验证成功，响应正文将包含一个具有access_token值的JSON对象：

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

access_token授予对App Services Admin API的访问权限。 您必须将其作为持有者令牌包含在所有 Admin API请求的Authorization标头中。

提示

另请参阅：

API身份验证文档

2

调用创建Edge Server实例端点

调用管理API创建Edge Server实例端点以将Edge Server实例添加到您的服务。

您的请求必须包括：

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>' \
  -d '{
    "name": "YOUR-EDGE-SERVER-INSTANCE-NAME"
  }'

成功的请求将返回 201 代码以及JSON对象，其中包含有关新创建的Edge Server实例的信息：

{
  "id": "6622b8f5118368b943d228a9",
  "user_id": "6622b8f5118368b943d2288a",
  "registration_key": "Qi4GgpvVduwwt4k1w77ZzaQ1n4SdTWC8rLBD9vyTib1w9G3CX2ta8WrJvt3giEK7"
}

  • id： Edge Server实例的唯一标识符，类型为ObjectId ，为string 。 您可以使用此标识符删除或更新Edge Server实例。

  • user_id： Edge Server本身就是一个用户。 这是Edge Server用户的唯一标识符，类型为ObjectId ，为string 。 您可以在配置权限时使用此标识符。

  • registration_key：保存此信息。 当您在托管上安装Edge Server代码时，请输入此注册令牌。 Edge Server将其交换为API密钥，用于与Atlas进行身份验证。 此注册令牌只能使用一次。

3

安装Edge Server代码

将安装脚本复制并粘贴到要安装Edge Server代码的设备的终端中。 有关详细信息，请参阅安装和配置Edge Server实例。

列出 Edge Server 实例

Edge Server您可以在Atlas 用户界面中或从 Admin 中获取API 实例的列表。

Edge Server仪表盘列出了每个Edge Server实例的简要摘要，包括上次连接的日期和时间及其状态快照。 您可以选择查看每个实例的详细信息或日志。

要查看Edge Server仪表盘，请在左侧导航栏中选择 Edge Server。

要查看特定Edge Server实例的详细信息，请单击该Edge Server实例的 View Details（查看详细信息）。 或者，单击App Logs浏览与该实例相关的日志。

1

对 MongoDB Atlas 用户进行身份验证

使用您的 MongoDB Atlas API 密钥对调用管理员用户身份验证端点：

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

如果身份验证成功，响应正文将包含一个具有access_token值的JSON对象：

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

access_token授予对App Services Admin API的访问权限。 您必须将其作为持有者令牌包含在所有 Admin API请求的Authorization标头中。

提示

另请参阅：

API身份验证文档

2

获取Edge Server实例列表

调用Admin API 列出边缘服务器端点以获取所有边缘服务器实例的列表。

您的请求必须包含Authorization 标头，其中包含作为持有令牌的 Admin API 访问 令牌。

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

成功的请求将返回一个 200 代码和一个 edge_servers 键，该键的值是一个对象数组，其中包含与 appId 关联的每个Edge Server实例的摘要详细信息。

{
  "edge_servers": [
    {
      "id": "6622b8f5118368b943d228a9",
      "created": "2024-04-19T08:51:00Z",
      "name": "Edge-Store-42",
      "user_id": "6622b8f5118368b943d2288a",
      "status": "active",
      "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
      "last_connection": "2024-04-19T09:51:00Z"
    }
  ]
}

有关更多详细信息，请找到要查看其详细信息的实例的id 。

3

调用Edge Server信息端点

调用Admin API获取Edge Server信息端点以获取有关Edge Server实例的详细信息。

您的请求必须包含Authorization 标头，其中包含作为持有令牌的 Admin API 访问 令牌。

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge/{edgeServerId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

成功的请求会返回200 代码以及包含JSON 实例详细信息的Edge Server 对象：

{
  "id": "6622b8f5118368b943d228a9",
  "created": "2024-04-19T08:51:00Z",
  "name": "Edge-Store-42",
  "user_id": "6622b8f5118368b943d2288a",
  "status": "active",
  "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
  "last_connection": "2024-04-19T09:51:00Z",
  "query": {
    "Item": "(store_id == \"641cb3d99e425c794ef69315\")"
  },
  "package_version": "v0.21.2",
  "latest_package_version": "v0.22.2",
  "metrics": [
    {
      "key": "edge_host_memory_percent",
      "name": "Memory Usage",
      "category": "host",
      "detail": "Percentage of memory used by the edge container",
      "value": 15,
      "unit": "%"
    },
    ...additional Edge Server metrics...
  ]
}

有关此响应正文的更多信息，请参阅 API 规范。

Edge Server实例详细信息

Edge Server 详细信息中的可用信息会有所不同，具体取决于 Edge Server 是已配置并连接到 Atlas，还是配置和连接仍处于待处理状态。

待处理的 Edge Server 实例

当Edge Server实例尚未首次连接到Atlas时，该实例的 Health 状态为 Pending。

当Edge Server实例处于 Pending 状态时，您可以从详细视图中执行以下操作：

  • 重命名该实例。

  • 查看有关实例状态的警报。

  • 获取实例 ID。您可以用它来设置此特定实例的权限。

  • 查看可在终端中用于安装Edge Server代码的安装命令。

  • 重新生成注册令牌。

  • 删除Edge Server实例。

成功配置并连接Edge Server实例后，详细视图将更改以提供其他信息。

活跃或出现故障的 Edge Server 实例

将Edge Server实例首次连接到Atlas后，该实例的 Health 状态将更改为 Active。

如果 Edge Server 实例遇到严重错误，则其 Health 状态将更改为 Failed。

您可以对活动实例或故障实例执行以下操作：

  • 重命名该实例。

  • 查看有关实例状态的警报。

  • 查看上次连接的日期和时间。

  • 获取实例 ID。您可以用它来设置此特定实例的权限。

  • 查看实例查询。 这决定了哪些数据在实例和Atlas之间同步，以及哪些数据客户端可以写入实例。 客户端只能写入属于其权限范围内的数据以及实例的查询。 有关详细信息，请参阅指定Edge Server的查询。

  • 查看有关Edge Server实例的指标。 有关详细信息，请参阅Edge Server指标。

  • 查看实例日志。 有关详细信息，请参阅Edge Server日志。

  • 查看版本信息。 此页面列出了当前版本和最新可用版本。 如果该实例的版本比最新可用版本落后一个以上主要版本，则会进入Failed状态，并且在升级之前无法与Atlas同步。 有关详细信息，请参阅升级Edge Server版本。

  • 查看可在终端中用于安装Edge Server代码的安装命令。

  • 重新生成注册令牌。

  • 删除Edge Server实例。

删除 Edge Server 实例

您可以从 中删除单个Edge Server Atlas实例。

1

浏览到Edge Server仪表盘

单击左侧导航侧边栏中的 Edge Server 选项，打开“ Edge Server仪表盘。

2

查看Edge Server实例详细信息

在列表中找到要删除的Edge Server实例，然后单击 View Details 按钮。

3

删除Edge Server实例

单击“ Edge Server详细信息”视图底部的 Delete 按钮。

系统将提示您确认删除。按照提示确认要删除 Edge Server。

1

对 MongoDB Atlas 用户进行身份验证

使用您的 MongoDB Atlas API 密钥对调用管理员用户身份验证端点：

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

如果身份验证成功，响应正文将包含一个具有access_token值的JSON对象：

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

access_token授予对App Services Admin API的访问权限。 您必须将其作为持有者令牌包含在所有 Admin API请求的Authorization标头中。

提示

另请参阅：

API身份验证文档

2

ID获取要删除的Edge Server 的

调用Admin API列出边缘服务器端点以获取所有Edge Server实例的列表。

您的请求必须包含Authorization 标头，其中包含作为持有令牌的 Admin API 访问 令牌。

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

成功的请求将返回一个 200 代码和一个 edge_servers 键，该键的值是一个对象数组，其中包含与 appId 关联的每个Edge Server实例的摘要详细信息。

{
  "edge_servers": [
    {
      "id": "6622b8f5118368b943d228a9",
      "created": "2024-04-19T08:51:00Z",
      "name": "Edge-Store-42",
      "user_id": "6622b8f5118368b943d2288a",
      "status": "active",
      "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
      "last_connection": "2024-04-19T09:51:00Z"
    }
  ]
}

在大量中找到要删除的Edge Server实例的 id。

3

调用删除端点

使用要删除的边缘 实例的 调用 管理 删除API Edge Server实例 端点。IDEdge Server

您的请求必须包含Authorization 标头，其中包含作为持有令牌的 Admin API 访问 令牌。

curl -X DELETE \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge/{edgeServerId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

成功的请求会返回200代码。

更新Edge Server的数据模型

更新数据模型的进程会有所不同，具体取决于您使用的是Edge Server Service 还是Device Sync Service with Edge Server 。

Edge Server服务

当您使用Edge Server服务时，当您对同步的文档进行更改时，该服务会自动更新模式中的字段。

如果您使用用户界面手动更新模式，并且这些模式更改会trigger模式版本更改，则会导致具有旧模式的Edge Server实例重新启动并自行擦除。

如果要添加之前未同步过的新集合，则必须定义新的模式。

添加集合

当您想要将集合添加到 Edge Server 服务时，您必须添加包含以下内容的模式：

  • collection名称。

  • 属于 ObjectID 类型的 _id 字段。

Edge Server 会根据所同步文档或集合中文档的结构来自动推断其他字段。

有关如何添加模式的信息，请参阅定义和实施模式。

在添加集合之后，您必须停止并启动 Edge Server 实例，以便获取新集合的详细信息。有关更多信息，请参阅启动和停止 Edge Server。

更改文档中的字段

当您使用 Edge Server 服务更改文档中的字段时，该服务会自动更改模式以添加新字段。

通过用户界面进行的某些更改被视为“重大”模式更改。 发生“重大”模式更改时，任何具有旧模式的Edge Server实例都会重新启动并自行擦除。 擦除进程会删除所有未同步的数据。

重要

擦除并重新启动实例会清除该实例上的所有本地未同步数据。

如果该数据是由Atlas Device SDK客户端写入的，则客户端本身可以处理数据恢复。 这使得客户端写入的本地未同步数据最终能够到达Atlas。

如果数据是由使用传输协议的MongoDB驱动程序或工具写入的，则未同步的数据将无法恢复。

在 Edge Server 从公共预览版移至全面可用版之前，当发生此错误时，您可以选择恢复本地数据。

有关哪些类型的更改被视为“重大”更改的详细信息，请参阅“重大”与“非重大”更改快速参考”。

Device Sync Service

在 服务中运行的 Edge Server使用Device Sync 规则来更新数据模型。Device Sync

发生“重大”模式更改时，任何具有旧模式的Edge Server实例都会重新启动并自行擦除。

重要

擦除并重新启动实例会清除该实例上的所有本地未同步数据。

如果该数据是由Atlas Device SDK客户端写入的，则客户端本身可以处理数据恢复。 这使得客户端写入的本地未同步数据最终能够到达Atlas。

如果数据是由使用传输协议的MongoDB驱动程序或工具写入的，则未同步的数据将无法恢复。

在 Edge Server 从公共预览版移至全面可用版之前，当发生此错误时，您可以选择恢复本地数据。

有关更多信息，请参阅更新数据模型。

对 Edge Server 实例进行故障排除

某些情况可能导致 Edge Server 实例进入 Failed 状态：

Edge Server的离线时间超过客户端最大离线时间

Edge Server 使用 Device Sync 在 Edge Server 实例和 Atlas 之间同步数据。Device Sync 具有客户端最长离线时间设置。

默认启用此设置。它会修剪历史记录，以减少支持 Atlas 集群所需的存储量。客户端最大离线时间越长，Atlas 保存支持同步的历史记录所需的存储空间就越大。

如果 Edge Server 实例离线的时间超过此设置，则这是一项不可恢复的错误。您必须擦除并重新启动实例。或者，当您使实例重新联机时，则会擦除并自动重新启动该实例。

重要

擦除并重新启动实例会清除该实例上的所有本地未同步数据。

如果该数据是由Atlas Device SDK客户端写入的，则客户端本身可以处理数据恢复。 这使得客户端写入的本地未同步数据最终能够到达Atlas。

如果数据是由使用传输协议的MongoDB驱动程序或工具写入的，则未同步的数据将无法恢复。

在 Edge Server 从公共预览版移至全面可用版之前，当发生此错误时，您可以选择恢复本地数据。

您可以在同步设置中变更客户端最长离线时间的长度。

重要

Edge Server脱机限制为 60 天

无论客户端最大离线时间设置如何，Edge Server 实例的离线时间都不能超过 60 天。如果未设置或设置大于 60 天，则 Edge Server 离线限制为 60 天。

Edge Server实例落后于多个主要版本

Edge Server不支持比当前最新版本落后一个以上主要版本的实例。 如果您的Edge Server实例在版本上进一步落后，则必须将其升级才能解决 Failed 状态。

有关升级Edge Server实例的信息，请参阅升级Edge Server版本。

Edge Server 令牌无效

如果重新生成了Edge Server实例令牌，并且您没有更新实例本身的API密钥，则边缘服务器可能会进入 Failed 状态。

如需详细了解如何在重新生成 Edge Server 令牌后更新 Edge Server 实例上的 API 密钥，请参阅循环使用 Edge Server API 密钥。

Edge Server 限制

虽然 Edge Server 处于公开预览阶段，但它还不支持 MongoDB 和 Atlas Device SDK 的全部特性和功能。

集合类型

Edge Server当前不支持时间序列集合。

当您创建Edge Server服务时，我们会自动为链接数据库中的每个集合创建模式。 尝试将Edge Server与包含时间序列集合的数据库一起使用会引发错误。

要解决此错误，您必须手动删除时间序列集合的模式。 有关如何删除模式的信息，请参阅删除模式。

聚合和 CRUD 操作

Edge Server目前仅支持MongoDB聚合和CRUD操作的子集。 有关支持的操作列表，请参阅Edge Server MongoDB API支持 - 预览。

Atlas Device SDK功能

Edge Server当前不支持数据导入。

后退

Edge Server - Preview