同步设置
本页说明了启用或配置 Device Sync 时可用的设置。
可用设置
要同步的集群
要存储同步数据的关联Atlas 集群数据源的名称。
启用Device Sync，您无法修改此字段。 您必须先终止同步，然后才能选择其他集群。
注意
Device Sync的数据源要求
要启用Device Sync，您的App Services App必须至少有一个满足以下要求的链接数据源：
运行 MongoDB 5.0或更高版本的非分片MongoDB Atlas 群集。
集群不能是无服务器实例或联合数据库实例。 请参阅数据源限制。
同步类型
重要
同步类型仅适用于基于分区的同步应用程序
只有项目中至少有一个基于分区的同步应用的组织能力选择应用的同步类型。
基于分区的同步已弃用，并且不允许用于新的同步配置。 相反，所有新的同步配置都会自动默认为推荐的 Flexible Sync模式。
启用Device Sync后，您可以选择以下同步模式之一：
Flexible Sync允许您在客户端中定义查询并仅同步与查询匹配的对象。 通过客户端订阅，客户端应用程序可以：
维护查询
响应更改
添加、更改或删除查询
Flexible Sync是唯一可用于新同步配置的模式。
基于分区的同步是一种较旧的同步模式，现已弃用，并且不允许用于新的同步配置。
如果您的现有应用已经在使用较旧的基于分区的同步，我们强烈建议您迁移到Flexible Sync。 迁移是一个自动进程，除了升级 SDK 版本之外，不需要对客户端应用代码进行任何更改。 有关更多信息，请参阅迁移Device Sync模式。
启用Device Sync后，您无法更改同步类型。 您必须先终止或暂停同步，然后才能进行更改。
开发模式
开发模式是一种配置设置，允许 Device Sync 根据客户端数据模型推断和更新模式。这会简化开发过程，但不应在生产环境中使用。
在开发模式下，您可以直接在客户端应用程序代码中设计模式，从而加快开发速度。
在您同步域时，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 v 10.16.2
Realm Kotlin SDK v 11.1.1
Realm .NET SDK v 11.6.0
Realm Node.js SDK v 12.2.0
Realm React Native SDK v12.2.0
Realm Swift SDK v10.42.2
要从客户端代码中进行中断性更改，请执行以下操作：
删除您的本地 Realm 和数据。这不会影响同步到后端的数据。未同步的本地更改将被删除，并且无法恢复。
更改本地对象模型。
打开一个具有更新的对象模型的 Realm。
运行客户端应用以将更改同步到后端。
要删除 Realm 文件，请使用 Realm SDK 特定的方法：
启用开发模式的不利影响
启用开发模式具有两个不利影响：
如果您的应用不需要匿名身份验证，您可能需要在启用开发模式后将其禁用。
在禁用开发模式之前，无法在用户界面中重新启用部署草稿。但是，您仍然可以通过 CLI 或 Admin API 手动创建部署草稿。
数据库名称（仅开发模式）
启用“开发模式”后，您将指定数据库来存储同步对象。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。
保留字段名称
App Services 保留了一些关键字用于 Realm 查询语言和其他目的。不能使用保留关键字作为字段名称。
App Services 保留以下任意大小写的关键字：
|
|
|
例子
您无法将 descending、Descending、DESCENDING 或 DeScEnDiNG 作为字段名称。
App Services 还保留以下具有给定确切大小写的关键字：
|
|
|
例子
您无法使用 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 支持数据摄入：
C++ SDK：将数据流式传输到 Atlas — C++ SDK
Flutter SDK：将数据流式传输到 Atlas — Flutter SDK
Kotlin SDK：将数据流式传输到 Atlas — Kotlin SDK
.NET SDK：单向数据导入 — .NET SDK
Node.js SDK：定义非对称对象
React Native SDK：定义非对称对象
Swift SDK：将数据流式传输到 Atlas — Swift SDK
Atlas Device Sync 全面管理这些数据的生命周期。它会保留在设备上，直到数据摄入同步完成，然后从设备中删除。
客户端最长离线时间
客户端最大离线时间决定客户端在两次同步会话之间可以离线多长时间。通过更改此值，您可以平衡离线访问与同步 Atlas 集群使用的存储。有关更多信息，请参阅客户端最长离线时间。
客户端恢复
通过使用客户端恢复，客户端可以在恢复设备上的数据时尝试自动执行客户端重置。有关更多信息，请参阅恢复未同步的更改。
同步配置文件参考
您可以在已导出应用的 sync 目录中找到应用程序的同步配置文件：
app/ └── 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 字段可能仍会出现在导出的应用配置中。这可能表明您的应用尚未自动迁移到统一规则系统。在应用完成迁移之前，请避免删除此字段。
同步配置对象
{ "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>", ...], ... } }
字段 | 说明 |
|---|---|
typestring | 同步模式。共有两种同步模式：Flexible Sync 和较旧的基于分区的同步。我们建议使用 Flexible Sync。有关基于分区的同步的更多信息，请参阅基于分区的同步。 Flexible Sync 配置的有效选项：
|
development_mode_enabledboolean | |
service_namestring | |
database_namestring | App Services 在开发模式下存储数据的同步集群中数据库的名称。App Services 自动为每个同步类型生成模式，并将每个对象类型映射到数据库内的集合。 |
statestring | 应用程序同步协议的当前状态。 有效选项：
|
client_max_offline_daysnumber | 在主动修剪某些客户端需要从旧版本的 Realm 同步的元数据之前，后端压缩过程等待的天数。 |
is_recovery_mode_disabledboolean | 如果为 false，则应用程序已启用恢复模式。启用后，支持此功能的 Realm SDK 会尝试在执行客户端重置时恢复未同步的更改。恢复模式默认启用。 |
queryable_fields_namesstring[] | 用作全局可查询字段的字段名列表。 |
indexed_queryable_fields_namesstring[] | |
collection_queryable_fields_names{ [collectionName: string]: string[] } | 从集合名称到每个集合的集合级别可查询字段列表的映射。 |
last_disablednumber | 上次暂停或禁用同步的日期和时间，表示为自 Unix 纪元（1970 年 1 月 1 日，00:00:00 UTC）以来的秒数。 |
asymmetric_tablesstring[] | 定义为与数据导入不对称的集合的名称数组，其中客户端可以写入数据但不能读取数据。 |