PiiBlur

Polling ist für einen Prototyp in Ordnung. Ein Produktions-Redaktionsworkflow benötigt normalerweise Webhooks.

Der Grund ist einfach: Die Schwärzung von Bildern und Videos erfolgt asynchron. Ihre App lädt eine Datei hoch, PiiBlur stellt den Job in die Warteschlange und das Ergebnis ist später verfügbar. Wenn Mitarbeiter herumsitzen und jeden Auftrag abfragen, verschwenden sie Kapazitäten und erschweren die Fehlerbehandlung. Mithilfe einer Webhook-Pipeline können Upload-Worker Aufträge schnell übermitteln und anschließend erledigt ein separater Handler die fertigen Dateien.

In diesem Artikel wird die Form dieser Pipeline beschrieben. Es ist nicht an einen bestimmten Warteschlangenanbieter gebunden. Das gleiche Muster funktioniert mit SQS-, Redis-, RabbitMQ-, Sidekiq-, Laravel-Warteschlangen oder einer datenbankgestützten Jobtabelle.

Die Pipelineform

Eine zuverlässige Schwärzungspipeline besteht aus fünf Teilen:

Quellspeicher- dort, wo sich das Originalbild oder -video derzeit befindet.
Submission Worker- sendet die Datei an /api/v1/media/redact.
Auftragstabelle- zeichnet Ihre interne Objekt-ID, die PiiBlur-Medien-ID, den Status, die ausgewählten Kategorien und die Anzahl der Wiederholungen auf.
Webhook-Endpunkt- empfängt die Ereignisse media.processed und media.failed.
Download-Worker- ruft die redigierte Ausgabe ab und speichert sie in Ihrem endgültigen Bucket.

Halten Sie die Einreichung und den Download getrennt. Das Hochladen von 10.000 Bildern sollte nicht darauf warten, dass die ersten 10 fertig sind.

Jobs mit Idempotenzschlüsseln senden

Verwenden Sie für jedes Quellasset einen Idempotenzschlüssel. Wenn nach dem Empfang des Uploads durch PiiBlur eine Netzwerk-Zeitüberschreitung auftritt, können Sie die Anfrage problemlos wiederholen.

curl -X POST https://piiblur.com/api/v1/media/redact \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Idempotency-Key: claim-photo-78391-v1" \
 -F "[email protected]" \
 -F "categories[]=heads" \
 -F "categories[]=license_plates" \
 -F "redaction_method=blur"

Speichern Sie den Idempotenzschlüssel neben Ihrem internen Asset-Datensatz. Generieren Sie nicht bei jedem Wiederholungsversuch einen zufälligen Schlüssel. das macht den Punkt zunichte.

Ein nützliches Schlüsselformat umfasst die Quell-Asset-ID und eine Versionsnummer:

listing-photo-44822-v1
dashcam-segment-20260608-0915-v2
claim-photo-78391-v1

Erhöhen Sie die Version nur, wenn sich die Datei- oder Kategorieauswahl ändert.

Zeichnen Sie genügend Status auf, um Fehler zu beheben

Ihre Jobtabelle sollte kein nachträglicher Einfall sein. Lagern Sie mindestens:

Interne Asset-ID
PiiBlur-Medien-ID
Ursprünglicher Dateiname
Medientyp
Ausgewählte PII-Kategorien
Schwärzungsmethode
Einreichungsstatus
Bearbeitungsstatus
Anzahl der Wiederholungen
Letzter Fehlercode und Anforderungs-ID
Zeitstempel für gesendete, verarbeitete, fehlgeschlagene und heruntergeladene Daten

Besonders nützlich ist das request_id aus API-Fehlern. Protokollieren Sie es mit Ihrer eigenen Job-ID, damit der Support die Anfrage nachverfolgen kann, wenn etwas fehlschlägt.

Webhook-Signaturen überprüfen

Behandeln Sie Webhook-Anfragen als nicht vertrauenswürdig, bis die Signatur ausgecheckt ist. PiiBlur sendet einen X-PiiBlur-Signature-Header. Ihr Handler sollte den erwarteten HMAC über den rohen Anforderungstext berechnen und ihn mit einer zeitkonstanten Vergleichsfunktion vergleichen.

Lehnen Sie Anfragen ab, bei denen die Signaturüberprüfung fehlschlägt. Aktualisieren Sie den Jobstatus nicht über eine nicht signierte Nutzlast.

Machen Sie Webhook-Handler langweilig

Ein häufiger Fehler besteht darin, innerhalb der HTTP-Webhook-Anfrage zu viel zu tun. Halten Sie den Handler kurz:

Überprüfen Sie die Signatur.
Analysieren Sie das Ereignis.
Fügen Sie die Ereignis-ID in eine Deduplizierungstabelle ein.
Aktualisieren Sie den Jobstatus.
Stellen Sie eine Download- oder Überprüfungsaufgabe in die Warteschlange.
Geben Sie 200 OK zurück.

Der eigentliche Download kann in einem Queue-Worker ausgeführt werden. Dadurch erhalten Sie Wiederholungsversuche, Zeitüberschreitungen und Beobachtbarkeit, ohne dass PiiBlur auf Ihren Speicheranbieter warten muss.

Ereignisse deduplizieren

Webhook-Bereitstellungssysteme versuchen möglicherweise erneut. Ihr Endpunkt sollte idempotent sein.

Verwenden Sie die Ereignis-ID als Deduplizierungsschlüssel. Wenn Ihre Datenbank bereits über diese Ereignis-ID verfügt, geben Sie 200 OK zurück und unternehmen Sie nichts. Dies verhindert doppelte Downloads und doppelte Statusübergänge.

Machen Sie Statusaktualisierungen außerdem monoton. Ein abgeschlossener Auftrag sollte nicht wieder in die Warteschlange verschoben werden, da ein altes Ereignis zu spät eintraf.

Download erst nach Fertigstellung

Die Medienstatusantwort enthält nur dann ein download_url, wenn die Verarbeitung abgeschlossen ist. Ihr Download-Worker sollte:

Lesen Sie die Medien-ID aus Ihrer Auftragstabelle.
Rufen Sie die Download-URL ab oder verwenden Sie die URL aus der verarbeiteten Webhook-Nutzlast.
Laden Sie mit demselben Bearer-API-Schlüssel herunter.
Speichern Sie die geschwärzte Datei in Ihrem eigenen Bucket.
Markieren Sie den Job als heruntergeladen.

Bewahren Sie Originale und redigierte Ausgaben in getrennten Pfaden auf. Zum Beispiel:

s3://media-originals/claims/78391/photo.jpg
s3://media-redacted/claims/78391/photo.jpg

Diese Trennung macht eine versehentliche Veröffentlichung von Originalen weniger wahrscheinlich.

Wiederholungsrichtlinie

Nicht jeder Fehler sollte auf die gleiche Weise wiederholt werden.

Netzwerk-Timeout- erneut versuchen mit exponentiellem Backoff.
HTTP 429- Retry-After beachten, dann erneut versuchen.
HTTP 500- einige Male wiederholen.
HTTP 409- prüfen Sie, ob der Idempotenzschlüssel noch verarbeitet wird oder mit einer anderen Nutzlast wiederverwendet wurde.
HTTP 422 - nicht erneut versuchen, bis die Datei oder Anfrage behoben ist.

Verschieben Sie den Auftrag nach dem letzten Wiederholungsversuch in eine Warteschlange für unzustellbare Nachrichten. Ein Mensch sollte in der Lage sein, die Datei, den Fehlercode, die ausgewählten Kategorien und die Anforderungs-ID zu sehen, ohne die Protokolle durchsuchen zu müssen.

Überprüfen Sie die Regeln

Die automatische Schwärzung ist kein Grund, die Überprüfung von Medien mit hohem Risiko zu überspringen. Fügen Sie Bewertungstore hinzu für:

Filmmaterial zur Veröffentlichung
Rechtsbeweis
Gesundheits- oder Bildungsakten
Medien mit Kindern
Jede Ausgabe, bei der die Quelldatei eine niedrige Auflösung, verschwommen, dunkel oder stark komprimiert war

Interne Arbeitsabläufe mit geringem Risiko können stattdessen häufig auf Stichproben zurückgreifen. Überprüfen Sie 1 - 5 % der abgeschlossenen Ausgaben, verfolgen Sie Fehler und passen Sie die Kategorieauswahl an, wenn die Stichprobe ein Muster erkennen lässt.

'So erstellen Sie eine Webhook-basierte Redaktionspipeline'