Paginierung

Listen, die groß werden können, verwenden Keyset-Paginierung: Sie fordern mit limit eine Seite an, und die Antwort sagt Ihnen, wo die nächste Seite beginnt.

Welche Operationen blätternLink zum Abschnitt kopieren

Andere Listen, etwa Werte, Wertehistorien und Modellversionen, liefern alle Einträge in einer Antwort.

AnfrageLink zum Abschnitt kopieren

Senden Sie die Filter der Operation (zum Beispiel battery_model_id oder passport_status bei listBatteries) mit jeder Seite unverändert mit.

AntwortLink zum Abschnitt kopieren

{
  "items": [
    { "id": "0192f0a3-1b7c-7e2a-8f45-6a9d0c3e5b12", "serial_number": "SV2027-000001" },
    { "id": "0192f0a3-1b7c-7e2a-8f45-6a9d0c3e5b13", "serial_number": "SV2027-000002" }
  ],
  "next_cursor": "eyJzIjoiU1YyMDI3LTAwMDAwMiJ9"
}

Das Beispiel zeigt nur zwei Felder je Einheit; echte Einträge haben das vollständige Schema der Operation.

Regeln für CursorLink zum Abschnitt kopieren

• Ein Cursor ist undurchsichtig. Lesen, bauen oder ändern Sie ihn nicht; sein Inhalt kann sich jederzeit ändern.
• Ein Cursor gehört zu der Abfrage, die ihn erzeugt hat: dieselbe Operation, dieselben Pfadparameter, dieselben Filter. Verwenden Sie ihn gleich für die nächste Seite und speichern Sie Cursor nicht als dauerhafte Lesezeichen.
• next_cursor: null heißt, dass keine weiteren Einträge folgen.
• Ein unbrauchbarer Cursor ergibt 400 validation_error auf dem Feld cursor; ein limit außerhalb von 1 bis 200 ein 400 auf dem Feld limit.
• Seiten sind keine Momentaufnahme. Einträge, die während des Blätterns entstehen oder sich ändern, können erscheinen oder fehlen. Für eine konsistente Kopie blättern Sie durch und gleichen danach über die ID ab (siehe Einheiten synchronisieren).

Alle Seiten lesenLink zum Abschnitt kopieren

Die folgenden Schleifen lesen alle Einheiten mit veröffentlichtem Pass, 200 pro Seite.

type Battery = { id: string; serial_number: string };
type Page<T> = { items: T[]; next_cursor: string | null };

const base = `${process.env.BATTERYPASS_URL}/api/v1`;
const headers = { Authorization: `Bearer ${process.env.BATTERYPASS_API_KEY}` };

async function* listBatteries(filters: Record<string, string>): AsyncGenerator<Battery> {
  let cursor: string | null = null;
  do {
    const query = new URLSearchParams({ ...filters, limit: '200' });
    if (cursor) query.set('cursor', cursor);
    const res = await fetch(`${base}/batteries?${query}`, { headers });
    if (!res.ok) throw new Error(`listBatteries: ${res.status} ${await res.text()}`);
    const page: Page<Battery> = await res.json();
    yield* page.items;
    cursor = page.next_cursor;
  } while (cursor);
}

let count = 0;
for await (const unit of listBatteries({ passport_status: 'published' })) {
  console.log(unit.serial_number, unit.id);
  count++;
}
console.log(`${count} Einheiten`);