Product3 мин четене

Idempotency-Key: безопасни повторни опити за PDF задачи

Изпращайте Idempotency-Key за POST под /api/v1/. PDF123 кешира успешните отговори 24 часа в паметта на процеса и връща Idempotency-Replayed: true без второ пускане.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: безопасни повторни опити за PDF задачи

Мрежовите прекъсвания и повторните опити на клиента са нормални при качване на multipart PDF. Без ключ за идемпотентност втори POST изпълнява същото сливане, OCR или компресия отначало, дублирайки качването и времето за обработка. С Idempotency-Key PDF123 може да върне първия успешен отговор, вместо да го изпълни пак.

Какво прави междинният слой

Сървърният междинен слой в pdfx-server се прилага само за променящи извиквания: POST към пътища под /api/v1/ (включително /api/v1/pipeline). GET и другите методи минават непроменени. Ако заявката няма заглавка Idempotency-Key (или тя е празна след премахване на интервали), операцията се изпълнява нормално, без търсене в кеша.

Когато заглавката е налице:

  1. Хранилището ключва записа по principal + ключ. Principal се извежда от X-API-KEY (като key:…), иначе от Authorization (като auth:…), иначе от буквалното anon. Тези две стойности се хешират (SHA-256) в ключа на картата; тялото на заявката не е част от ключа.
  2. При попадение в кеша в рамките на 24 часа междинният слой връща запазените статус, тип на съдържанието, разположение на съдържанието и тяло и задава Idempotency-Replayed: true.
  3. При пропуск заявката продължава. Само успешните отговори се буферират и запазват (неуспешните не се кешират за повторение).
  4. Телата на отговорите се буферират до 100 MiB, за да може повторението да изпрати байтовете на файла отново. Тяло, което не може да се буферира, не пропуска кеша тихо: заявката връща HTTP 500, така че отговор над лимита се проваля, вместо да премине без кеширане.

Неуспешните задачи са безопасни за повторен опит със същия ключ: понеже неуспехите не се запазват, следващият опит може да успее и после да стане кешираният резултат. Не използвайте повторно ключ за различен файл или параметри; кешът не хешира тялото, само principal и ключа. Двама извикващи, които не споделят нито API ключ, нито Authorization, не могат да се сблъскат случайно; анонимните извикващи споделят principal anon, затова трябва да изберат различни ключове.

Как да го изпратите

Изберете стабилен непрозрачен низ за всяка логическа задача (UUID е подходящ):

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

Работи и за анонимни, и за извикващи с API ключ. Потоците, които свързват воден знак, после компресия, все пак трябва да изпратят по един ключ за всяка HTTP заявка, която искате да дедуплицирате, включително всяка стъпка, ако ги изпращате поотделно, или един ключ за едно извикване на /api/v1/pipeline.

Еднократните задачи в браузъра на страниците с инструменти (Compress, OCR, …) не изискват да измисляте ключ; заглавката има значение за клиентите, които повтарят. Публикуваният skill на /skills/pdf123.md показва Idempotency-Key в пример за pipeline по същата причина.

Клиентски модели, които работят

  • Генерирайте ключа преди първия POST; използвайте го повторно при повторни опити след прекъсване за същата логическа задача.
  • При успех проверете Idempotency-Replayed: true, ако трябва да знаете дали този отговор е дошъл от кеша, или операцията е изпълнена отново.
  • Сменете ключа, когато файлът, операцията или параметрите се променят, дори ако principal остава същият.
  • За /api/v1/pipeline един ключ покрива цялата POST заявка на pipeline, а не всяка вътрешна стъпка.

Какво не е повторението

Повторението не е трайна опашка от задачи. Хранилището е локално за процеса (HashMap зад mutex) с TTL от 24 часа. След изтичане или след рестарт на процеса, който изхвърля картата в паметта, същият ключ изпълнява операцията отново. Внедряванията с няколко инстанции не споделят тази карта, освен ако не поставите споделено хранилище отпред; днешният междинен слой е за отделен процес.

Третирайте Idempotency-Replayed: true като доказателство, че този отговор е дошъл от кеша, а не като постоянен регистър. Той не означава, че PDF е обработен отново, и не удължава TTL.

Повече подробности за повърхността: Developers и Създаден за AI агенти. Страниците с инструменти като Compress остават достъпни за еднократни задачи в браузъра без измисляне на ключове.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool
Read next
Редактиране на текст в PDF онлайн: поправете файла без изходния документ
Щракнете върху ред текст в PDF, променете го и изтеглете резултата. Нищо не се качва и не е нужно да влизате в профил. Могат да се редактират само редове текст, които вече съществуват във файла.
От пакет сканирания към текст: OCR, после Compress на PDF, който още пазите
Пакетът сканирания изисква две стъпки: OCR в PDF123 връща Markdown, а Compress свива оригиналния PDF чрез прекомпресия на потоци. Редът и резултатите се различават.
Какво е PDF123: безплатен PDF инструментариум, който можете да хоствате сами
PDF123 е безплатен PDF инструментариум в браузъра: всичките 56 инструмента, от обединяване и компресиране до OCR и шифроване, работят без акаунт. Същите операции са достъпни и през REST, MCP и командния ред pdfx, а можете да хоствате цялата система при себе си и да пазите файловете в собствената си мрежа.