Đồng bộ creative

TL;DR — Kéo các creative quảng cáo đã duyệt theo kiểu tăng dần: truyền checkpoint gần nhất của bạn vào updated_since, đi theo next_cursor tới hết, ghi đè bản ghi theo creative_id, và chỉ dời checkpoint khi cả lượt chạy đã thành công. Kiểm lại một creative đã lưu bằng GET /creatives/{id}; ngừng dùng nó sau ngày UTC của rights.ends_at.

Trước khi bắt đầu#

• Một key có creatives:export cho job, đặt trong WANDURA_API_KEY. Job marketing không bao giờ cần playback.
• Bản ghi và lớp vỏ response: Creative.

Quy trình#

1. Lần chạy đầu: GET /creatives?limit=100 không có updated_since; khi data.next_cursor còn khác null, gọi lại với cursor=<next_cursor>.
2. Upsert mọi bản ghi theo creative_id. Một bản ghi có thể đến hai lần (updated_at được làm tròn xuống tới giây, và updated_since là so sánh nghiêm ngặt): cứ ghi đè.
3. Checkpoint: sau khi lượt chạy hoàn tất, lưu updated_at lớn nhất bạn đã nhận.
4. Các lần chạy sau: làm như trên, với updated_since=<checkpoint> ở mọi trang của lượt chạy.
5. Khi lỗi (kể cả 422 4222, cursor không còn hợp lệ): giữ checkpoint cũ; lần chạy sau bắt đầu lại từ đó. Không bỏ sót gì.
6. Creative bị gỡ không được thông báo. Trước khi dùng một creative đã lưu, hoặc mỗi ngày một lần, gọi GET /creatives/{id}: 404 4040 nghĩa là ngừng dùng nó.
7. Bản quyền: dùng được tới hết ngày UTC mà rights.ends_at trỏ tới (ends_at + 86400).

Vài lần chạy mỗi giờ vẫn nằm thoải mái trong rate limit của creative.

Code#

export async function syncCreatives(store: CreativeStore, o: CallOptions = {}): Promise<boolean> {
  const since = await store.checkpoint();
  let cursor: string | null = null;
  let max = since ?? 0;
  try {
    do {
      const qs = new URLSearchParams({ limit: '100' });
      if (since !== null) qs.set('updated_since', String(since)); // the same value on every page of a run
      if (cursor) qs.set('cursor', cursor);
      const { data }: { data: Envelope } = await call<Envelope>('GET', `/api/delivery/v1/creatives?${qs}`, { policy: BACKGROUND, ...o });
      for (const c of data.data.items) { await store.upsert(c); max = Math.max(max, c.updated_at); }
      cursor = data.data.next_cursor;
    } while (cursor);
  } catch (e) {
    // 422 / code 4222 (cursor no longer valid) or anything else: the next run restarts from the old checkpoint.
    log('creatives_sync_failed', { status: (e as { status?: number }).status, code: (e as { errorCode?: string }).errorCode });
    return false;
  }
  await store.saveCheckpoint(max); // only after the whole run: nothing is ever skipped
  return true;
}

Xong khi#

• Lần chạy thứ hai khi phía Wandura không có thay đổi thì không trả về gì mới.
• Lượt chạy bị ngắt giữa chừng không dời checkpoint.
• Creative đã quá ngày bản quyền không còn được dùng.

Liên quan#

• Liệt kê creative, Lấy một creative