Idempotency-Key: bezpieczne ponawianie zadań PDF
Wysyłaj Idempotency-Key przy POST na /api/v1/. PDF123 zapisuje udane odpowiedzi 24 godziny w pamięci procesu i zwraca Idempotency-Replayed: true zamiast powtórki.

Przekroczenia limitu czasu w sieci i ponowienia po stronie klienta to codzienność przy przesyłaniu PDF-ów w formacie multipart. Bez klucza idempotencji drugie żądanie POST uruchamia to samo scalanie, OCR albo kompresję od nowa, powtarzając przesyłanie pliku i czas przetwarzania. Z nagłówkiem Idempotency-Key PDF123 potrafi zamiast tego odtworzyć pierwszą udaną odpowiedź.
Co robi warstwa pośrednicząca
Warstwa pośrednicząca serwera w pdfx-server dotyczy wyłącznie wywołań zmieniających stan: POST na ścieżki pod /api/v1/ (w tym /api/v1/pipeline). Żądania GET i pozostałe metody przechodzą bez zmian. Jeśli żądanie nie zawiera nagłówka Idempotency-Key (albo po przycięciu jest pusty), operacja wykonuje się normalnie, bez zaglądania do pamięci podręcznej.
Gdy nagłówek jest obecny:
- Magazyn tworzy klucz wpisu z pary podmiot + klucz. Podmiot pochodzi z
X-API-KEY(jakokey:…), w przeciwnym razie zAuthorization(jakoauth:…), a gdy nie ma żadnego, przyjmuje wartośćanon. Te dwie wartości są hashowane (SHA-256) i tworzą klucz mapy; treść żądania nie wchodzi w skład klucza. - Przy trafieniu w pamięci podręcznej w ciągu 24 godzin warstwa zwraca zapisany status, typ zawartości, dyspozycję zawartości i treść, ustawiając
Idempotency-Replayed: true. - Przy braku trafienia żądanie idzie dalej. Buforowane i zapisywane są wyłącznie odpowiedzi udane (odpowiedzi nieudane nie trafiają do pamięci podręcznej).
- Treści odpowiedzi są buforowane do 100 MiB, aby odtworzenie mogło ponownie wysłać bajty pliku. Treść, której nie da się zbuforować, nie pomija pamięci podręcznej po cichu: takie żądanie zwraca HTTP 500, więc odpowiedź ponad limit kończy się błędem, zamiast przejść bez zapisu w pamięci podręcznej.
Nieudane zadania można bezpiecznie ponawiać z tym samym kluczem: ponieważ niepowodzenia nie są zapisywane, kolejna próba może się udać i dopiero ona stanie się wynikiem z pamięci podręcznej. Nie używaj tego samego klucza do innego pliku albo innych parametrów; pamięć podręczna nie hashuje treści żądania, tylko podmiot i klucz. Dwaj wywołujący, którzy nie dzielą ani klucza API, ani nagłówka Authorization, nie zderzą się przypadkiem; anonimowi współdzielą podmiot anon, więc muszą wybierać różne klucze.
Jak go wysłać
Wybierz stabilny, nieprzejrzysty ciąg dla każdego logicznego zadania (UUID jest w porządku):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Ta metoda działa zarówno dla wywołań anonimowych, jak i z kluczem API. Potoki łączące znak wodny z kompresją nadal powinny wysyłać jeden klucz na każde żądanie HTTP, które chcesz deduplikować, w tym na każdy krok, jeśli wysyłasz je osobno, albo jeden klucz na pojedyncze wywołanie /api/v1/pipeline.
Jednorazowe zadania w przeglądarce na stronach narzędzi (Compress, OCR itd.) nie wymagają wymyślania klucza; nagłówek ma znaczenie dla klientów, które ponawiają. Opublikowany skill pod /skills/pdf123.md pokazuje Idempotency-Key w przykładzie potoku właśnie z tego powodu.
Wzorce klienta, które działają
- Generuj klucz przed pierwszym żądaniem POST i używaj go ponownie przy ponowieniach po przekroczeniu czasu dla tego samego logicznego zadania.
- Po sukcesie sprawdź
Idempotency-Replayed: true, jeśli chcesz wiedzieć, czy odpowiedź przyszła z pamięci podręcznej, czy operacja wykonała się jeszcze raz. - Zmień klucz, gdy zmienia się plik, operacja albo parametry, nawet jeśli podmiot pozostaje ten sam.
- W przypadku
/api/v1/pipelinejeden klucz obejmuje całe żądanie POST, a nie każdy wewnętrzny krok.
Czym nie jest odtwarzanie odpowiedzi
Odtwarzanie odpowiedzi to nie trwała kolejka zadań. Magazyn działa lokalnie w procesie (HashMap za mutexem) z TTL 24 godziny. Po wygaśnięciu albo po restarcie procesu, który gubi mapę w pamięci, ten sam klucz uruchamia operację ponownie. Wdrożenia wieloinstancyjne nie współdzielą tej mapy, chyba że postawisz przed nimi wspólny magazyn; obecna warstwa pośrednicząca działa w obrębie procesu.
Traktuj Idempotency-Replayed: true jako dowód, że odpowiedź przyszła z pamięci podręcznej, a nie jako trwały rejestr. Nie oznacza to, że PDF został przetworzony ponownie, i nie przedłuża TTL.
Więcej szczegółów: Dla programistów i Stworzone z myślą o agentach AI. Strony narzędzi, takie jak Compress, nadal służą jednorazowym zadaniom w przeglądarce bez wymyślania kluczy.