WordPress-Cache per API leeren

WordPress-Cache per API leeren

Nach einem Deployment, einem Import oder einer Konfigurationsänderung soll eine WordPress-Website sofort frische Inhalte ausliefern. Mit der Hosting-API leerst du den Cache aus einem Skript oder deiner CI-Pipeline, ohne dich im Panel anzumelden.

Voraussetzungen

• Ein API-Token mit dem Recht cache:purge für genau diese Website. Wie du es erstellst, steht in API-Token erstellen und widerrufen.
• Eine WordPress-Installation in deinem turbopress-Hosting. Für statische AI-Launch-Sites gibt es keinen Cache-Purge.
• Die site_id der Website. Sie ist eine opake ID aus GET /sites, keine Domain.

Was geleert wird

Du wählst mit scope genau einen Bereich:

Ist ein Cache gar nicht aktiv, gibt es nichts zu leeren. Der Job endet dann trotzdem erfolgreich und meldet im Ergebnis, dass nichts geleert wurde. Konnte die API nicht sicher feststellen, ob ein Cache aktiv ist, oder blieb der Testeintrag im Objekt-Cache stehen, meldet sie das ehrlich und behauptet kein „geleert“. Prüfe dann cache_cleared und verified im Ergebnis.

Mit dem CLI

export TURBOPRESS_API_TOKEN='…'   # Secret aus deinem Secret Store
npx @turbopress-de/cli cache purge --site "$SITE_ID" --scope page --wait

--wait wartet, bis der Job succeeded meldet, und endet sonst mit einem Fehlercode. Ohne --wait bekommst du nur die Annahme zurück.

Mit curl

curl -sS -X POST "https://panel.turbopress.de/api/v1/sites/${SITE_ID}/cache/purge" \
  -H "Authorization: Bearer ${TURBOPRESS_API_TOKEN}" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"scope":"page"}'

Die Antwort 202 bedeutet „angenommen“, nicht „fertig“. Lies den Job anschließend mit GET /operations/{id} frühestens nach dem Retry-After der Antwort (mindestens fünf Sekunden), bis der Status succeeded, failed oder unknown lautet. Gib dem Aufruf einen eigenen Idempotency-Key aus 16 bis 128 Zeichen und hebe ihn zusammen mit der Job-ID auf. Eine Wiederholung mit demselben Key liefert denselben Job statt eines zweiten Aufrufs.

Im Deployment nutzen

Leere den Cache als letzten Schritt, nachdem dein Code übertragen und geprüft ist. Starte ihn nicht parallel zu einem Backup oder Deployment derselben Website. Läuft dort noch ein Job, antwortet die API mit 409; warte dann das Ende ab und versuche es erneut.

Grenzen

• Pro Konto gelten fünf neue Schreibaufrufe pro Minute und höchstens vier offene Jobs. Bei Überschreitung antwortet die API mit 429 (queue_full bei vollen Jobs). Warte die Zeit aus Retry-After ab.
• Nach dem Leeren sind die ersten Seitenaufrufe kurz langsamer, bis der Cache neu aufgebaut ist.
• Bei unknown ist das Ergebnis ungewiss. Prüfe die Website und die Fehlersuche, statt blind zu wiederholen.

Weitere Anleitungen

OpenAPI-Referenz · Fehler und Timeouts · API-Token