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 は一つの言語に絞り込まれていないロケールマップそのままです。 上の例の productName が { "ko-KR": "스테인리스 텀블러 500ml" } であるように、各フィールドの値はロケールごとの値を持つマップとして来ます。CDA Content・CDA Media の取得が locale パラメータで値を単一の値に絞り込んでくれるのとは異なり、Sync は一つの言語に絞らずマップ全体をそのまま返します。クライアントがこのマップを受け取ってローカルでキャッシュし、必要なときに目的の言語の値を選んで使います。そのため Sync には locale パラメータがありません。

上の例の photo が {}(空のマップ)になっているのは、紐づいた Media がどのロケールにもないためです。

項目の種類

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 パラメータがありません。値はロケールマップそのままで来ます。

空の items は最後の同期以降に変更がないという意味です。このときも新しい nextSyncUrl が来るので、その値を保存しておき次の同期にそのまま使います。

関連ドキュメント

• CDA 概要: CDA 全体と共通の配信動作。
• CDA Content: 単件取得で一つの言語の値だけを選んで受け取った公開 Content。
• CDA Locale: 同期で受け取ったロケールマップから値を選ぶときに使う Locale の一覧。
• 多言語(概念): ロケール値の選択・fallback。