Docs 菜单

Docs 主页 → Atlas App Services

同步设置

在此页面上

  • 可用设置
  • 同步类型
  • 开发模式
  • 要同步的集群
  • 数据库名称（仅开发模式）
  • 可查询字段
  • 权限
  • 数据导入
  • 客户端最长离线时间
  • 客户端恢复
  • 同步配置文件参考
  • 同步配置对象

本页说明了启用或配置 Device Sync 时可用的设置。

可用设置

同步类型

Atlas Device Sync 具有两种同步模式：Flexible Sync 和较旧的基于分区的同步。基于分区的同步已弃用，而不允许在新的同步配置中使用。如果现有的应用使用基于分区的同步，您可以将其迁移到 Flexible Sync。有关更多信息，请参阅迁移 Device Sync 模式。

灵活同步允许您在客户端中定义查询，并仅同步与查询匹配的对象。通过客户端订阅，客户端应用程序可以：

  • 维护查询

  • 响应更改

  • 添加、更改或删除查询

开发模式

开发模式是一种配置设置，允许 Device Sync 根据客户端数据模型推断和更新模式。这会简化开发过程，但不应在生产环境中使用。

在开发模式下，您可以直接在客户端应用程序代码中设计模式，从而加快开发速度。

同步 Realm 时，Atlas App Services 会将每个同步的对象类型映射到数据库名称（仅适用于开发模式）指定的数据库中自己的集合。如果您在客户端更新对象模型，App Services 会更新集合模式以进行匹配。这样，您就可以在开发应用时更新客户端代码中的对象。

您可以在“开发模式”下使用数据访问规则。请注意，模式更改会忽略数据访问规则。也就是说，任何客户端都可以通过更改客户端模式来更新后台模式。

要详细了解使用开发模式时 Realm 对象模式如何映射到 App Services 模式，请参阅数据模型映射。

有关修改同步的对象模式的更多信息，请参阅：更新数据模型。

重要

为生产应用禁用开发模式

开发模式是一种开发工具，不适合生产使用。在将您的应用部署到生产环境之前，请确保关闭开发模式。

重大更改

在 2023 年 9 月 13 日之后创建并采用开发模式的 App Services 应用可以从客户端代码中对同步的对象模式进行中断性更改。

如果应用是在 2023 年 9 月 13 日之前创建的，您可以与支持人员联系以启用该功能。

先决条件

  • 2023 年 9 月 13 日之后创建的 App Services 应用

  • 用于实现 Flexible Sync 兼容性的 MongoDB 5.0 或更高版本

  • 最低 SDK 版本：

    • Realm C++ SDK v1.0.0

    • Realm Flutter SDK v1.6.0

    • Realm Java SDK v10.16.2

    • Realm Kotlin SDK v11.1.1

    • Realm .NET SDK v11.6.0

    • Realm Node.js SDK v12.2.0

    • Realm React Native SDK v12.2.0

    • Realm Swift SDK v10.42.2

注意

2023 年 9 月 13 日之前创建的应用

对于 2023 年 9 月 13 日之前创建的应用，您需要在 App Services 用户界面中更新对象模式。有关详细信息，请参阅更新数据模型。

要从客户端代码中进行中断性更改，请执行以下操作：

  1. 删除您的本地 Realm 和数据。这不会影响同步到后端的数据。未同步的本地更改将被删除，并且无法恢复。

  2. 更改本地对象模型。

  3. 打开一个具有更新的对象模型的 Realm。

  4. 运行客户端应用以将更改同步到后端。

要删除 Realm 文件，请使用 Realm SDK 特定的方法：

启用开发模式的不利影响

启用开发模式具有两个不利影响：

如果您的应用不需要匿名身份验证，您可能需要在启用开发模式后将其禁用。

在禁用开发模式之前，无法在用户界面中重新启用部署草稿。但是，您仍然可以通过 CLI 或 Admin API 手动创建部署草稿。

要同步的集群

您想要存储同步数据的 Atlas 集群数据源的名称。

Flexible Sync 需要使用 MongoDB 5.0。您无法在无服务器实例中使用同步。在用户界面中，在集群不满足 Flexible Sync 要求时，集群将显示为灰色并且无法进行选择。

数据库名称（仅开发模式）

启用开发模式后，您将指定一个数据库来存储同步对象。 App Services 在此开发模式数据库中为每种类型的同步对象创建新集合。

例子

指定 myapp 的开发模式数据库。您的 iOS 客户端有一个 Person 模型。您同步一个包含 Person 对象实例的 Realm。开发模式创建与该模型相关联的服务器端模式。该对象同步到 myapp.Person 集合。

App Services 继续为每个新的对象类型创建新的服务器端模式和集合。如果您稍后添加一个 Dog 对象，该对象将同步到 App Services 创建的新 myapp.Dog 集合。

可查询字段

在配置 Flexible Sync 时，您可以指定客户端应用程序可以在 Flexible Sync 订阅中查询的字段名称。可以在订阅查询中使用的字段称为可查询字段。

例子

在待办事项清单应用中，您可以将 assignee 或 owner 设置为可查询字段。然后，您可以在客户端查询 assignee 或 owner 与登录用户匹配的任务。

可查询字段范围

可查询字段适用于您在配置时指定的范围。可用范围有两个：

  • 全局可查询字段：范围涵盖应用模式中的所有集合。

  • 集合可查询字段：范围仅限于应用中的单个集合。

将可查询字段的范围限定为特定集合可减少存储同步元数据所需的后备 Atlas 存储容量。

您可以使用规则和权限为每个集合配置更精细的访问控制。您可以为全局可查询字段和集合可查询字段定义集合级规则和权限。

配置可查询字段

您可以通过启用开发模式自动指定可查询字段。使用开发模式时在客户端查询中出现的字段会自动添加为所查询集合的集合可查询字段。

您提供的字段名称是任意字符串。如果一个对象类型有一个字段，其名称与您提供的字段名称匹配（并且满足其他资格条件），则该字段可供 Device Sync 用来查询。

配置索引可查询字段

只有在未启用 Device Sync 时，您才能添加或删除索引可查询字段。如果 Device Sync 已在应用中运行，您必须终止 Sync，并在重新启用 Sync 时配置索引可查询字段。

对于在重新启用 Sync 后尝试重新连接的任何客户端，这会导致客户端重置。

符合条件的字段类型

灵活同步仅支持标量类型的顶级基元字段作为可查询字段。您也可以将这些基元的数组作为可查询字段。灵活同步不支持嵌入式对象或对象数组作为可查询字段。

索引可查询字段支持一部分数据类型。索引可查询字段可以是以下类型之一：int64、string、ObjectId、UUID。

提示

另请参阅：Realm 查询语言 — Flexible Sync 限制

有关可以对这些字段执行的查询的信息，请参阅： Flexible Sync RQL 限制

保留字段名称

App Services 保留了一些关键字用于 Realm 查询语言和其他目的。不能使用保留关键字作为字段名称。

App Services 保留以下任意大小写的关键字：

  • 和

  • asc

  • ascending

  • beginswith

  • between

  • contains

  • desc

  • descending

  • distinct

  • endswith

  • falsepredicate

  • inf

  • infinity

  • 就像

  • 限制

  • nan

  • nil

  • null

  • 或

  • 排序

  • subquery

  • truepredicate

例子

您无法将 descending、Descending、DESCENDING 或 DeScEnDiNG 作为字段名称。

App Services 还保留以下具有给定确切大小写的关键字：

  • 所有

  • 注意到

  • B64

  • false

  • 登录

  • 无

  • not

  • SOME

  • 真正

  • 所有

  • 注意到

  • false

  • in

  • 无

  • not

  • oid

  • some

  • true

  • uuid

例子

您无法使用 true 或 TRUE，因为这两种大小写的关键字是专门保留的关键词，但可以将 True 或 tRUE 作为字段名称。

性能和存储

每个可查询字段都会向 Atlas 集群添加额外的元数据存储，并且可能导致写入性能下降。您应该根据应用程序的需要尽量减少可查询字段，并将其查询范围限定为所需的最少集合数量。

很多应用在存储使用量和查询灵活性之间达到了良好的平衡，并且最多 10 个可查询字段适用于任何单个集合。例如，如果您具有 3 个全局可查询字段 和 7 个集合可查询字段，则您具有 10 个适用于集合的可查询字段。

如果您仅希望在一个集合中查询某个字段，但将其配置为全局可查询字段，这会不必要地消耗 Atlas 存储空间。例如，如果在每个集合中具有一个 user 字段，但您仅将其用于一个集合中的 Sync 查询，将其范围限定为集合可查询字段 将会降低存储要求。缩小范围意味着，Sync 不必为您不查询 user 字段的其他集合保留该字段的元数据。

如果需要减少存储使用量或提高性能，可以从应用中删除不需要的可查询字段。但是，请注意添加或删除可查询字段的后果。有关更多信息，请参阅添加或删除可查询字段的后果。

有关其他注意事项，请参阅使用 Flexible Sync 时优化性能和存储。

索引可查询字段

您可以添加索引可查询字段以提高某些类型的工作负载的性能。索引可查询字段是一个全局可查询字段，可以更高效地对其进行查询，从而提供更高的 Sync 性能。您可以将一个 全局可查询字段指定为索引可查询字段。

为可查询字段编制索引可以提高对单个字段的简单查询的性能，例如 {“store_id”: 1} 或 {“user_id”: “641374b03725038381d2e1fb”}。

索引可查询字段必须出现在所有 Sync 集合的模式中，并且必须使用相同的有效数据类型。例如，如果索引可查询字段为store_id ，则它必须出现在您同步的所有集合中，并且必须在所有集合中具有相同的有效类型。有关符合条件的字段类型的更多信息，请参阅符合条件的字段类型。

您无法在客户端更改索引可查询字段值

在配置索引可查询字段后，客户端设备无法更新现有对象的索引可查询字段值。例如，如果索引可查询字段为 store_id，则客户端无法直接更改该值。不支持从客户端进行更改，因为这可能与在同一时间段对该对象进行的其他更新发生冲突。

如果尝试更改设备上索引可查询字段的值，则会触发补偿写入错误。有关此错误及其引起的行为的更多信息，请参阅 Flexible Sync 错误文档中的 ErrorCompensatingWrite。

您仍然可以直接在 Atlas 数据库中更改该值。

警告

通过 Atlas 更改对象的索引可查询字段值可能会覆盖客户端对对象的并发更新。

对索引可查询字段的客户端查询

在应用使用索引可查询字段时，Flexible Sync 订阅中的客户端查询必须 包含使用 == 或 IN 与一个常量进行至少一次比较的索引可查询字段。例如 user_id == 641374b03725038381d2e1fb 或 store_id IN {1,2,3}。

可以选择包含 AND 比较，前提是使用 == 或 IN 将索引化可查询字段直接与常量进行至少一次比较。例如，store_id IN {1,2,3} AND region=="Northeast" 或 store_id == 1 AND (active_promotions < 5 OR num_employees < 10)。

对索引化可查询字段的无效灵活同步查询包括以下情况的查询：

  • 索引化可查询字段未将 AND 与查询的其余部分结合使用。例如，store_id IN {1,2,3} OR region=="Northeast" 是无效的，因为它使用了 OR 而不是 AND。同样，store_id == 1 AND active_promotions < 5 OR num_employees < 10 也是无效的，因为 AND 仅适用于其旁边的词，而不适用于整个查询。

  • 索引化可查询字段未在相等运算符中使用。例如，store_id > 2 AND region=="Northeast" 是无效的，因为它仅将 > 运算符与索引化可查询字段结合使用，而没有相等比较。

  • 查询中完全没有索引化可查询字段。例如，region=="Northeast" 和 truepredicate 都是无效的，因为它们不含索引化可查询字段。

添加或删除可查询字段的后果。

在启用 Sync 后，您可以更新 Sync 配置以添加或删除可查询字段名称，但要注意以下几点：

在添加可查询字段时，只有在设备赶上 Device Sync 历史记录中添加该字段的时间点后，设备才能在该字段上进行同步。

在删除可查询字段时，仍使用该字段的任何设备将删除其 Device Sync 会话，并且必须执行客户端重置。不使用删除的字段的客户端不会收到任何错误。为了避免在删除可查询字段时触发客户端重置，您应该先在客户端停止使用该字段。

如果在添加或删除可查询字段之前终止 Sync，则这些注意事项不适用。不过，对于已与应用同步的任何客户端，终止 Sync 确实会触发客户端重置。

权限

对于针对同步的集群的所有请求，Atlas Device Sync 实施基于角色的数据访问规则。规则是动态 JSON 表达式，用于确定用户是否能够同步、查看和修改数据。

有关详细信息，请参阅基于角色的权限。

数据导入

数据摄入是一种同步策略，适用于具有繁重客户端插入工作负载的应用程序。您可以为一个或多个集合启用数据摄入。它支持写入任何集合类型，包括 Atlas 时间序列集合。

例如，经常记录传感器数据的物联网应用具有大量写入工作负载，但没有读取工作负载。设备也可能长时间处于离线状态。数据摄入绕过了双向同步所需的一些处理，从而显著提高对 Atlas 集合的写入速度。

其他使用案例包括写入不可变数据，例如来自零售应用的发票，或记录应用程序事件，这两种情况都不需要解决冲突。

您可以将数据摄入应用于单个集合。这意味着您的应用可以使用数据摄入写入一些数据，但在其他集合上进行双向灵活同步。

数据导入集合仅用于写入数据。您无法对这些集合使用 Flexible Sync 查询。相反，请使用连接到 MongoDB 数据源。

启用数据摄入后，您可以通过客户端 SDK 在客户端应用程序中予以实现。目前，以下 Realm SDK 支持数据摄入：

Atlas Device Sync 全面管理这些数据的生命周期。它会保留在设备上，直到数据摄入同步完成，然后从设备中删除。

客户端最长离线时间

客户端最大离线时间决定客户端在两次同步会话之间可以离线多长时间。通过更改此值，您可以平衡离线访问与同步 Atlas 集群使用的存储。有关更多信息，请参阅客户端最长离线时间。

客户端恢复

通过使用客户端恢复，客户端可以在恢复设备上的数据时尝试自动执行客户端重置。有关更多信息，请参阅恢复未同步的更改。

同步配置文件参考

您可以在已导出应用的 sync 目录中找到应用程序的同步配置文件：

app/
└── sync/
    └── config.json

例如，以下同步配置适用于使用灵活同步的应用。

sync/config.json
{
  "type": "flexible",
  "development_mode_enabled": <Boolean>,
  "service_name": "<Data Source Name>",
  "database_name": "<Development Mode Database Name>",
  "state": <"enabled" | "disabled">,
  "client_max_offline_days": <Number>,
  "is_recovery_mode_disabled": <Boolean>,
  "queryable_fields_names": [
    <Array of String Field Names>
  ],
  "indexed_queryable_fields_names": [
   <Array of String Field Names>
  ],
  "collection_queryable_fields_names": <Map[String][]String>
  "permissions": "<Deprecated, Do Not Use>"
}

已弃用的 permissions 字段可能仍会出现在导出的应用配置中。这可能表明您的应用尚未自动迁移到统一规则系统。在应用完成迁移之前，请避免删除此字段。

同步配置对象

sync/config.json
{
  "type": "flexible",
  "development_mode_enabled": <Boolean>,
  "service_name": "<Data Source Name>",
  "database_name": "<Development Mode Database Name>",
  "state": <"enabled" | "disabled">,
  "client_max_offline_days": <Number>,
  "is_recovery_mode_disabled": <Boolean>,
  "queryable_fields_names": ["<Field Name>", ...],
  "indexed_queryable_fields_names": ["<Field Name>", ...],
  "collection_queryable_fields_names": {
    "<Collection Name>": ["<Field Name>", ...],
    ...
  }
}
字段
说明
type
string

同步模式。共有两种同步模式：Flexible Sync 和较旧的基于分区的同步。我们建议使用 Flexible Sync。有关基于分区的同步的更多信息，请参阅基于分区的同步。

Flexible Sync 配置的有效选项：

  • "flexible"

development_mode_enabled
boolean
如果为true ，则为应用程序启用开发模式。启用后，App Services 会自动将同步的对象存储在特定数据库（在database_name中指定）中，并镜像该数据库的集合模式中的对象类型。
service_name
string
要同步的 Atlas 集群数据源的名称。您无法在无服务器实例中使用同步。
database_name
string
App Services 在Development Mode 下存储数据的同步集群中数据库的名称。 App Services 会自动为每个同步类型生成模式，并将每个对象类型映射到数据库中的集合。
state
string

应用程序同步协议的当前状态。

有效选项：

  • "enabled"

  • "disabled"

client_max_offline_days
number
在主动修剪某些客户端需要从旧版本的 Realm 同步的元数据之前，后端压缩过程等待的天数。
is_recovery_mode_disabled
boolean
如果为 false，则应用程序已启用恢复模式。启用后，支持此功能的 Realm SDK 会尝试在执行客户端重置时恢复未同步的更改。恢复模式默认启用。
queryable_fields_names
string[]
用作全局可查询字段的字段名称列表。
indexed_queryable_fields_names
string[]

用作索引可查询字段的字段名称列表。虽然此属性是一个数组，但 Sync 目前仅支持一个单索引可查询字段。因此，该数组最多可以包含一个元素。

索引可查询字段必须存在于模式中，并且在同步的每个集合中具有相同的符合条件的字段类型。索引可查询字段名称也必须出现在queryable_fields_names中，因为这是一个全局可查询字段。

collection_queryable_fields_names
{ [collectionName: string]: string[] }
从集合名称到每个集合的集合级可查询字段列表的映射。
last_disabled
number
上次暂停或禁用同步的日期和时间，表示为自 Unix 纪元（1970 年 1 月 1 日，00:00:00 UTC）以来的秒数。
asymmetric_tables
string[]
定义为与数据导入不对称的集合名称的数组，客户端可以写入但不能读取数据。
← 配置并启用 Atlas Device Sync
暂停或终止同步 →

在此页面上