Sync

Sync ist der CDA-Endpunkt, der die veröffentlichten Daten eines Space inkrementell (als Delta) synchronisiert. Statt die gesamten veröffentlichten Content-, Media- und Content Type-Daten jedes Mal erneut abzurufen, lädt der Client einmalig den vollständigen Bestand herunter, legt ihn lokal im Cache ab und empfängt danach nur noch die seit der letzten Synchronisierung geänderten und gelöschten Elemente, um diesen Cache zu aktualisieren. Verwendet wird das in Anwendungen, die den veröffentlichten Bestand vollständig vorhalten müssen (Offline-Cache, Suchindex, Builds statischer Websites usw.), um das Übertragungsvolumen zu reduzieren.

Die Synchronisierung läuft in zwei Schritten ab. Zuerst rufen Sie über die initiale Synchronisierung den gesamten Bestand ab und speichern die in der Antwort enthaltene nextSyncUrl. Danach rufen Sie mit dem in dieser URL enthaltenen sync-token die Delta-Synchronisierung auf, um nur die Änderungen und Löschungen zu empfangen. Da die Antwort erneut eine neue nextSyncUrl liefert, speichern Sie diesen Wert und wiederholen den Vorgang.

Ablauf der Synchronisierung

1. Initiale Synchronisierung: Rufen Sie mit ?initial=true&type=All auf, um den gesamten veröffentlichten Bestand zu empfangen. Am Ende der Antwort steht nextSyncUrl.
2. nextSyncUrl speichern: Speichern Sie den empfangenen Wert von nextSyncUrl unverändert. In dieser URL ist das sync-token enthalten, das beim nächsten Aufruf verwendet wird.
3. Delta-Synchronisierung: Rufen Sie erneut mit dem sync-token aus der gespeicherten nextSyncUrl auf. Nur die seit der letzten Synchronisierung geänderten und gelöschten Elemente werden in der Antwort geliefert, und am Ende kommt eine neue nextSyncUrl hinzu.
4. Wiederholen: Speichern Sie die empfangene neue nextSyncUrl und wiederholen Sie Schritt 3, sooft eine Synchronisierung nötig ist.

Das sync-token ist kein Wert, den Sie selbst erzeugen, sondern ein undurchsichtiger Cursor. Versuchen Sie nicht, sein Format zu interpretieren oder von Hand zusammenzusetzen, sondern übergeben Sie den aus der nextSyncUrl der vorangegangenen Antwort empfangenen Wert unverändert an den nächsten Aufruf.

Aufbau der Antwort

Im Folgenden sehen Sie die Antwort einer initialen Synchronisierung (type=All) eines Demo-Space. In items werden veröffentlichte Entitäten und Löschmarkierungen gemischt geliefert, und am Ende folgt die nextSyncUrl für die nächste Delta-Synchronisierung.

{
  "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"
}

Wichtige Schlüssel:

• sys.type: Die Art der Hülle, die die Synchronisierungsantwort umschließt; immer "PageResponse".
• limit: Die Anzahl der in einem Durchgang enthaltenen Elemente.
• items: Ein Array, in dem veröffentlichte Entitäten und Löschmarkierungen gemischt enthalten sind. Das erste Element im obigen Beispiel ist ein lebendiges Content (samt Inhalt), das zweite Element ist eine Löschmarkierung (DeletedContent), die ohne Inhalt nur sys enthält. Die Elementarten werden unten unter Elementarten behandelt.
• links: Das Objekt mit den Seitenlinks. Da Sync mit nextSyncUrl die nächste Seite bzw. das nächste Delta verkettet, kann dieses Objekt leer sein.
• nextSyncUrl: Der Pfad, der bei der nächsten Delta-Synchronisierung aufgerufen wird. Das sync-token dieser URL verwenden Sie unverändert beim nächsten Aufruf.

Die fields in items sind die Locale-Map unverändert, nicht auf eine einzelne Sprache reduziert. So wie productName im obigen Beispiel { "ko-KR": "스테인리스 텀블러 500ml" } ist, kommt jeder Feldwert als Map, die die Werte je Locale enthält. Anders als die Abfragen über CDA Content und CDA Media, die mit dem Parameter locale einen Einzelwert auswählen, liefert Sync keine auf eine Sprache reduzierte Auswahl, sondern die vollständige Map unverändert aus. Der Client empfängt diese Map, legt sie lokal im Cache ab und wählt bei Bedarf den gewünschten Sprachwert aus. Deshalb hat Sync keinen Parameter locale.

Dass photo im obigen Beispiel {} (eine leere Map) ist, liegt daran, dass kein verknüpftes Media in irgendeiner Locale vorhanden ist.

Elementarten

In items kommen Elemente mit unterschiedlichem sys.type gemischt vor. Im Wesentlichen sind es zwei Stränge: lebendige Entitäten und Löschmarkierungen.

Eine Löschmarkierung ist ein Signal dafür, dass die betreffende Ressource nicht mehr im veröffentlichten Bestand vorhanden ist. Der Client liest die sys.id der Markierung und entfernt das entsprechende Element aus dem lokalen Cache.

Bei der initialen Synchronisierung wählen Sie über den Parameter type aus, was Sie empfangen.

Wenn type gleich Content oder DeletedContent ist, können Sie über den Parameter content-type auf die Elemente eines bestimmten Content Type einschränken.

API

Die Basis-URL der beiden folgenden Endpunkte ist https://cda.weegloo.com/v1, und im Header Authorization ist ein Bearer-Token erforderlich, das gegenüber CDA authentifiziert. Beide verwenden denselben Pfad GET /spaces/{spaceId}/sync und unterscheiden initiale und Delta-Synchronisierung über Query-Parameter. Anders als die Abfragen von Content und Media hat Sync keinen Parameter locale. Die Werte kommen als Locale-Map unverändert.

Ein leeres items bedeutet, dass es seit der letzten Synchronisierung keine Änderungen gibt. Auch dann kommt eine neue nextSyncUrl; speichern Sie diesen Wert und verwenden Sie ihn unverändert bei der nächsten Synchronisierung.

Verwandte Dokumente

• CDA-Übersicht: CDA insgesamt und das gemeinsame Auslieferungsverhalten.
• CDA Content: Veröffentlichtes Content, bei dem über eine Einzelabfrage nur der Wert einer Sprache ausgewählt empfangen wird.
• CDA Locale: Liste der Locale, die zur Auswahl eines Werts aus der per Synchronisierung empfangenen Locale-Map verwendet wird.
• Mehrsprachigkeit (Konzept): Auswahl von Locale-Werten und Fallback.