Inkrementaalne sünkroonimine parameetriga updated_since

Sursa andmete koopia hoidmiseks oma süsteemis ei pea te iga kord kõike uuesti lugema. Nende objektide loendid, millel on väli updated_at, võtavad vastu parameetri updated_since ja tagastavad ainult objektid, mis muutusid sel hetkel või pärast seda.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "updated_since=2026-10-23T00:00:00Z" \
  --data-urlencode "limit=200"

Parameetriga updated_since sorditakse loend kasvavalt välja updated_at järgi, seejärel välja id järgi, ja kursor jätkab samas järjekorras. Nii loete muudatusi nende toimumise järjekorras ja lehepiir ei jaga neid kunagi nii, et mõni neist kaotsi läheks.

Parameetrit updated_since toetavad need loendid:

Kogudel, kasutajatel ja teadaannetel ei ole välja updated_at, seega nende loendid selle järgi ei filtreeri: need on lühikesed, nii et lugege need igal käivitusel tervikuna. Ajahetkel peab olema ajavööndi nihe, näiteks Z või +02:00; muu väärtus lükatakse tagasi nagu lõpp-punktis GET /v1/cards.

Parameetriga updated_since ei ole kaustapuu enam puu: iga kogu väli folders sisaldab muutunud kaustu lameda loendina tühja väljaga children ja parent_id näitab, kus iga kaust asub. GET /v1/folders jätab siis välja kogud, milles muutunud kaustu ei ole.

Sünkroonimistsükkel

1. Esimesel käivitusel lugege kogu loend ilma parameetrita updated_since ja jätke meelde hetk, mil käivitus algas.
2. Igal järgmisel käivitusel edastage meelde jäetud hetk parameetrina updated_since, millest on lahutatud väike varu, näiteks üks minut, ja jätke meelde uus algusaeg.
3. Kirjutage iga objekt oma andmehoidlasse selle id järgi, asendades eelmise koopia. Objektid, mis varu tõttu ilmuvad kaks korda, kirjutatakse lihtsalt uuesti.
4. Küsige iga järgmist lehte kursoriga ja sama parameetriga updated_since. Kursor toimib ainult esimese lehe filtritega: ilma nendeta tagastab päring 400 koodiga api.cursor_invalid.

Kui kasutate käivituse algusaega, mitte lõpuaega, jõuab käivituse ajal tehtud muudatus kindlasti järgmisesse käivitusse.

GET /v1/cards tagastab JSON-massiivi, seega tuleb selle järgmine leht päises X-Next-Cursor (vt Massiivi tagastavad loendid):

const BASE = "https://api.sursa.com";
const headers = { Authorization: `Bearer ${process.env.SURSA_API_KEY}` };

async function syncCards(since, saveCard) {
  const startedAt = new Date();
  const params = new URLSearchParams({ limit: "200" });
  if (since) params.set("updated_since", new Date(since.getTime() - 60_000).toISOString());
  let query = params.toString();
  while (query) {
    const response = await fetch(`${BASE}/v1/cards?${query}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    for (const card of await response.json()) await saveCard(card); // write into your store by card.id
    const cursor = response.headers.get("X-Next-Cursor");
    if (cursor) params.set("cursor", cursor); // keep updated_since: the cursor needs the same filters
    query = cursor ? params.toString() : "";
  }
  return startedAt; // pass it as `since` next time
}

Kustutamised

Loend tagastab ainult olemasolevad objektid, seega ei saa see teile öelda, et midagi kustutati. Võtke kustutamised sündmuste lindist:

curl -G https://api.sursa.com/v1/webhook-events \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "type=card.deleted" \
  --data-urlencode "created_since=2026-10-23T00:00:00Z"

Lindi lugemiseks on vaja võtit, millel on roll admin ja ulatus webhooks:manage. Sündmusi säilitatakse 30 päeva. Kui teie sünkroonimine ei ole kauem käivitunud, lugege kogu loend uuesti ja eemaldage oma andmehoidlast kõik objektid, mida selles enam ei ole.

Eksport andmelattu ühendab loendid, parameetri updated_since ja sündmuste lindi üheks tööks.