POST /v1/sync/task.
200 mit dem Task im Status QUEUED:
Lebenszyklus
Status
Ein Task mit vorübergehendem Fehler kehrt zu
QUEUED zurück und läuft erneut. Erst wenn seine Wiederholungen aufgebraucht sind, landet er in FAILED; ein Schritt PROCESSING → QUEUED ist also normal.
Polling lässt response weg, bis der Task einen Endzustand erreicht. Ein fehlgeschlagener Task hat stattdessen einen error-String auf oberster Ebene:
Credits beim Einreichen und Pollen
Preise, Reservierungen und Limits finden Sie unter Credits und Limits.
Verarbeitungszeit
task.latencyMs ist die Zeit, die die Engine gebraucht hat: von der ersten Übernahme durch einen Worker bis zum Endergebnis, in Millisekunden, ohne die Wartezeit in der Warteschlange. Wird ein Task nach einem vorübergehenden Fehler erneut eingereiht, zählt weiterhin ab der ersten Übernahme. Der Wert ist null in der Submit-Antwort und solange der Task QUEUED oder PROCESSING ist, und eine Zahl beim abschließenden Polling und im Webhook. Der Header X-Latency-Ms misst etwas anderes: die Zeit, die dieser Server für genau diese HTTP-Anfrage aufgewendet hat.
Priorität
priority akzeptiert 1 bis 10, Standard ist 1. Werte außerhalb des Bereichs werden in den Bereich gezogen statt abgelehnt. Der Wert wird in den Task-Metadaten zurückgegeben.
Aufbewahrung
Einen Task im Endzustand können Sie 24 Stunden nach Abschluss pollen. Danach liefertGET /v1/async/task/{id} 404 RESOURCE_NOT_FOUND, dieselbe Antwort wie für eine unbekannte id oder den Task eines anderen Kontos. Tasks in QUEUED und PROCESSING bleiben unabhängig von ihrem Alter sichtbar.
Das 24-Stunden-Fenster gilt auch für Ergebnis-Bodies in GET /v1/batches/{id}/items und beim Lesen von Rastern. Der idempotencyKey eines Tasks bleibt länger reserviert, mindestens 30 Tage nach der Anfrage (siehe Idempotenz). Automatische Webhook-Wiederholungen laufen nach eigenem Zeitplan, unabhängig von diesem Fenster.
Auf das Ergebnis in einer Anfrage warten
POST /v1/sync/task nimmt denselben Body entgegen und hält die Anfrage offen, bis der Task endet, höchstens 290 Sekunden. Die Antwort ist dann 200 mit demselben Body wie beim Polling des Tasks, auch bei einem fehlgeschlagenen Task.
Antwort-Engines brauchen länger als SERP- und Search-Tasks. Halten Sie die Anfrage so lange offen, wie es die Art der Engine im Engine-Katalog verlangt, und setzen Sie das Timeout Ihres HTTP-Clients ein paar Sekunden höher:
- Ein Task, der am Ende der Wartezeit noch nicht beendet ist, wird mit
202, dem Task undLocation: /v1/async/task/{id}beantwortet. Er läuft weiter und wird wie üblich berechnet. Pollen Sie diese Adresse oder nehmen Sie den Webhook. Ein202kann auch sofort kommen, wenn der Dienst gerade viele Anfragen offen hält. - Mit
Prefer: wait=<Sekunden>wird die Anfrage kürzer als 290 Sekunden offen gehalten. Bleiben Sie unter dem Timeout Ihres HTTP-Clients, damit Sie die Task-id erhalten, bevor Ihr Client aufgibt. - Senden Sie einen
idempotencyKey. Wer denselben Schlüssel erneut sendet, erhält den Task, der ihn hält. So können Sie eine Anfrage, die bei Ihnen abgelaufen ist, wiederholen, ohne den Task zweimal auszuführen. - Mit
Accept: text/htmlundpayload.include.html: truewird ein abgeschlossener Task mit seiner gespeicherten Seite alstext/htmlbeantwortet, undX-Task-Identhält die Task-id. Ein fehlgeschlagener Task oder einer, dessen Seite nicht gespeichert werden konnte, wird mit406und dem JSON-Body beantwortet.
Webhook oder Polling
Bevorzugen Sie Webhooks. Nutzen Sie Polling, um nachzuholen, was nicht angekommen ist.
Ein robuster Client macht beides: Er nutzt den Webhook als schnellen Weg und pollt jeden Task, von dem er nichts gehört hat, deutlich innerhalb des 24-Stunden-Fensters.
Nächste Schritte
Webhooks
Payload, Signaturen und Wiederholungen.
Batches und Raster
Bis zu 10.000 Tasks auf einmal einreichen.