Sync

Sync 是以增量（增量数据）方式同步 Space 发布资料的 CDA 端点。无需每次重新获取全部已发布的 Content、Media、Content Type，客户端只需获取一次全量并在本地缓存，此后仅获取自上次同步以来发生变更和被删除的内容来更新该缓存。它适用于需要持有全部发布资料的应用（离线缓存、搜索索引、静态站点构建等），用于减少传输量。

同步分两个阶段进行。先通过初始同步获取全量，并保存响应中返回的 nextSyncUrl。此后使用该 URL 中包含的 sync-token 调用增量同步，仅获取变更和删除部分，响应会再次返回新的 nextSyncUrl，因此保存该值并循环重复。

同步流程

1. 初始同步： 以 ?initial=true&type=All 调用，获取全部发布资料。响应末尾包含 nextSyncUrl。
2. 保存 nextSyncUrl： 原样保存获取到的 nextSyncUrl 值。该 URL 中包含下次调用所用的 sync-token。
3. 增量同步： 使用保存的 nextSyncUrl 中的 sync-token 再次调用。仅有自上次同步以来发生变更和被删除的内容会包含在响应中，末尾会一并返回新的 nextSyncUrl。
4. 重复： 保存获取到的新 nextSyncUrl，每当需要同步时重复第 3 步。

sync-token 不是自行构造的值，而是不透明游标。请勿解析其格式或手动拼接，直接将上一次响应的 nextSyncUrl 中获取的值原样传给下次调用。

响应结构

以下是某个演示 Space 的初始同步（type=All）响应。items 中混合包含已发布实体和删除标记，末尾返回用于下次增量同步的 nextSyncUrl。

{
  "sys": { "type": "PageResponse" },
  "limit": 15,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
        "type": "Content",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T15:16:12.151Z",
        "updatedAt": "2026-06-16T14:31:20.073Z",
        "revision": 3
      },
      "fields": {
        "price": { "ko-KR": 18000 },
        "description": { "ko-KR": "이중 진공 단열로 보온·보냉이 오래갑니다. 500ml 대용량." },
        "photo": {},
        "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
      }
    },
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7O7vFALWs1GJ",
        "type": "DeletedContent",
        "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
        "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA", "type": "Refer", "targetType": "ContentType" } },
        "createdAt": "2026-06-15T07:34:41.522Z",
        "updatedAt": "2026-06-15T07:41:57.198Z",
        "revision": 1
      }
    }
  ],
  "links": {},
  "nextSyncUrl": "/v1/spaces/HnQ32YiH/sync?sync-token=165rWhDiuLNoYOwjVQQAYXMA7makztXnhAV3qamYU75jFldqtvaEhMnr29PqsKTAbcoy6xs0iKpafM0KsKfZ2OHtA6pmbpx2pgx5jJ6bFzrkrBvoSvXF8tYZPkbw4X7B2EpCr95lgkQv4UJVCu1SSZIeH2ewzF"
}

主要键：

• sys.type：包裹同步响应的信封类型，始终为 "PageResponse"。
• limit：单次返回的条目数。
• items：混合存放已发布实体和删除标记的数组。上例的第一个条目是存活的 Content（含正文），第二个条目是删除标记（DeletedContent），不含正文，仅含 sys。条目类型在下文 条目类型 中说明。
• links：分页链接对象。Sync 通过 nextSyncUrl 衔接下一页和下一个增量，因此该对象可能为空。
• nextSyncUrl：下次增量同步要调用的路径。下次调用原样使用该 URL 中的 sync-token。

items 中的 fields 是未按单一语言筛选的原样 Locale 映射。 正如上例的 productName 为 { "ko-KR": "스테인리스 텀블러 500ml" }，每个字段值都以包含各 Locale 取值的映射形式返回。与 CDA Content、CDA Media 查询通过 locale 参数将值筛选为单一值不同，Sync 不按单一语言筛选，而是原样返回整个映射。客户端接收该映射后在本地缓存，需要时再选取所需语言的值使用。因此 Sync 没有 locale 参数。

上例中 photo 为 {}（空映射），是因为关联的 Media 在任何 Locale 下都不存在。

条目类型

items 中混合返回 sys.type 各不相同的条目。大致分为存活实体和删除标记两类。

删除标记表示该资源已不再存在于发布资料中。客户端根据标记的 sys.id 从本地缓存中删除对应条目。

初始同步中通过 type 参数选择获取什么内容。

当 type 为 Content 或 DeletedContent 时，可通过 content-type 参数限定为仅属于特定 Content Type 的条目。

API

以下两个端点的基准 URL 为 https://cda.weegloo.com/v1，并需要在 Authorization 头中提供用于认证 CDA 的 Bearer 令牌。两者均为相同路径 GET /spaces/{spaceId}/sync，通过查询参数区分初始同步和增量同步。与 Content、Media 查询不同，Sync 没有 locale 参数。值以原样的 Locale 映射返回。

空的 items 表示自上次同步以来没有变更。此时也会返回新的 nextSyncUrl，请保存该值用于下次同步时原样使用。

相关文档

• CDA 概览：CDA 整体与通用交付行为。
• CDA Content：通过单条查询仅选取一种语言值获取的已发布 Content。
• CDA Locale：从同步获取的 Locale 映射中选取值时使用的 Locale 列表。
• 多语言（概念）：Locale 值选取与 fallback。