Product3 min czytania

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.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: bezpieczne ponawianie zadań PDF

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:

  1. Magazyn tworzy klucz wpisu z pary podmiot + klucz. Podmiot pochodzi z X-API-KEY (jako key:…), w przeciwnym razie z Authorization (jako auth:…), 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.
  2. 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.
  3. Przy braku trafienia żądanie idzie dalej. Buforowane i zapisywane są wyłącznie odpowiedzi udane (odpowiedzi nieudane nie trafiają do pamięci podręcznej).
  4. 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/pipeline jeden 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.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool