Перейти до основного вмісту

Повна ресинхронізація

Стрічка змін приносить лише зміни. Щоб завантажити все, що вже є у WMS, — під час підключення нової системи або щоб відновитися, коли ваші дані розійшлися, — прочитайте повний знімок через сесію ресинхронізації, а далі продовжуйте читати стрічку змін від моменту, коли знімок було зроблено.

Ресинхронізація потребує можливості Читання change feed. Ресинхронізувати можна не кожен тип даних; див. рядок Читання кожного типу в Типах даних інтеграції.

Кроки​

  1. Розпочніть сесію для потрібних типів даних:

    POST /api/v1/integrations/resync-sessions
    {"externalSystemCode": "ERP_MAIN", "entityTypes": ["PARTY", "PRODUCT"], "warehouseScope": []}

    warehouseScope обмежує дані, прив'язані до складів, переліченими складами (ідентифікатори WMS); порожній список означає склади, з якими може працювати ваша зовнішня система. Відповідь:

    {"sessionId": 1, "status": "CREATED", "snapshotWatermarkEventId": 5, "expiresAt": "2026-10-28T09:54:29.190Z"}

  2. Читайте сторінки, доки hasMore не стане false:

    GET /api/v1/integrations/resync-sessions/1/page?limit=100&cursor=<nextCursor попередньої сторінки>

    limit обов'язковий, від 1 до 500. Для першої сторінки cursor не передавайте. Кожен елемент містить повний поточний стан одного запису з ідентифікаторами у вигляді пар {int, ext} (див. Формування payload):

    {
      "sessionId": 1,
      "status": "IN_PROGRESS",
      "items": [
        {
          "entityType": "PARTY",
          "scopeType": "GLOBAL",
          "internalEntityId": "01a16373-d1c6-77c5-8fe9-71c359d09e0e",
          "payload": {
            "id": {"int": "01a16373-d1c6-77c5-8fe9-71c359d09e0e", "ext": null},
            "name": "Contoso Foods",
            "supplier": true,
            "deleted": false
          }
        }
      ],
      "nextCursor": "eyJ2ZXJzaW9uIjoxLCJlbnRpdHlUeXBlIjoiUEFSVFkiLCJ…",
      "hasMore": true
    }

  3. Завершіть сесію після останньої сторінки:

    POST /api/v1/integrations/resync-sessions/1/complete
    {"expectedStatus": "SNAPSHOT_COMPLETED"}

  4. Продовжуйте читати стрічку змін після snapshotWatermarkEventId сесії. Завершення сесії не переносить вашу контрольну точку, тож підтвердіть цю подію самі, якщо контрольна точка відстає від неї (POST /api/v1/integrations/checkpoints/acknowledge, див. Стрічку змін); тоді цикл читання почнеться одразу після знімка. Усе, що змінилося після знімка, прийде через стрічку; між ними нічого не загубиться.

    Контрольна точка у вашої системи одна для всіх типів даних. Переносьте її на знімок лише тоді, коли ресинхронізація охопила всі типи, які ваша система читає зі стрічки; інакше зміни інших типів до знімка буде пропущено.

Сесію треба завершити протягом 24 годин від початку. GET /api/v1/integrations/resync-sessions/{sessionId} показує її поточний стан; статуси перелічено в Статусах сесії ресинхронізації.

Код​

Функція проводить усю сесію й повертає ідентифікатор події, від якого продовжувати стрічку змін; передайте його функції startChangeFeedAt зі Стрічки змін. Вона використовує клієнт з Основ API.

// Reads a full snapshot of the given data types page by page and hands every
// record to `handleItem`. Returns the event id to continue the change feed from.
async function runResync(entityTypes, handleItem, {warehouseScope = [], pageSize = 100} = {}) {
  const base = '/api/v1/integrations/resync-sessions';
  const {body: session} = await wmsRequest('POST', base, {
    body: {externalSystemCode: config.externalSystem, entityTypes, warehouseScope},
  });

  let cursor;
  for (;;) {
    const query = {limit: pageSize};
    if (cursor) query.cursor = cursor;
    const {body: page} = await wmsRequest('GET', `${base}/${session.sessionId}/page`, {query});
    for (const item of page.items) await handleItem(item); // {entityType, internalEntityId, payload}
    if (!page.hasMore) break;
    cursor = page.nextCursor;
  }

  const {body: done} = await wmsRequest('POST', `${base}/${session.sessionId}/complete`, {
    body: {expectedStatus: 'SNAPSHOT_COMPLETED'},
  });
  // Read the change feed with fromEventId = this value: nothing before it is missed.
  return done.snapshotWatermarkEventId;
}