Idempotency-Key: reintents segurs per a tasques PDF
Envieu Idempotency-Key a les tasques POST sota /api/v1/. PDF123 desa èxits 24 h en memòria local del procés i posa Idempotency-Replayed: true en lloc de repetir.

Els temps d'espera de xarxa i els reintents del client són normals en les càrregues de PDF multipart. Sense una clau d'idempotència, un segon POST torna a executar la mateixa unió, OCR o compressió des de zero, i duplica la càrrega i el temps de processament. Amb Idempotency-Key, PDF123 pot reproduir la primera resposta correcta.
Què fa el middleware
El middleware del servidor a pdfx-server només s'aplica a les crides que muten l'estat: POST a camins sota /api/v1/ (inclòs /api/v1/pipeline). Les peticions GET i els altres mètodes passen sense canvis. Si la petició no porta la capçalera Idempotency-Key (o queda buida després de retallar espais), l'operació s'executa amb normalitat sense cap consulta a la memòria cau.
Quan la capçalera hi és:
- El magatzem indexa l'entrada per principal + clau. El principal es deriva de
X-API-KEY(comkey:…), si no d'Authorization(comauth:…) i si no del literalanon. Aquests dos valors s'hanifiquen (SHA-256) dins la clau del mapa; el cos de la petició no forma part de la clau. - Si hi ha un encert a la memòria cau dins de les 24 hores, el middleware retorna l'estat, el tipus de contingut, la disposició de contingut i el cos desats, i posa
Idempotency-Replayed: true. - Si no hi ha encert, la petició continua. Només s'emmagatzemen i es bufferitzen les respostes correctes (les que no ho són no es guarden per reproduir-les).
- Els cossos de resposta es bufferitzen fins a 100 MiB perquè una reproducció pugui reenviar els bytes del fitxer. Un cos que no es pot bufferitzar no se salta la memòria cau en silenci: aquella petició retorna HTTP 500, de manera que una resposta per sobre del límit falla en lloc de passar sense cau.
Les tasques fallides es poden reintentar amb seguretat amb la mateixa clau: com que les fallades no s'emmagatzemen, el següent intent pot tenir èxit i convertir-se en el resultat desat. No reutilitzeu una clau per a un fitxer o uns paràmetres diferents; la memòria cau no hasheja el cos, només el principal i la clau. Dos sol·licitants que no comparteixin ni la clau d'API ni l'Authorization no poden col·lisionar per accident; els sol·licitants anònims comparteixen el principal anon, de manera que han de triar claus diferents.
Com enviar-la
Trieu una cadena opaca estable per a cada tasca lògica (un UUID va bé):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Funciona tant per a sol·licitants anònims com per als que tenen clau d'API. Les canalitzacions que encadenen marca d'aigua i després compressió haurien d'enviar igualment una clau per cada petició HTTP que vulgueu deduplicar, incloent-hi cada pas si els feu amb POST per separat, o una sola clau per a una única crida a /api/v1/pipeline.
Les tasques puntuals al navegador a les pàgines d'eines (Comprimeix, OCR, etc.) no us obliguen a inventar cap clau; la capçalera importa per als clients que reintenten. L'habilitat publicada a /skills/pdf123.md mostra una Idempotency-Key en un exemple de pipeline per la mateixa raó.
Patrons de client que funcionen
- Genereu la clau abans del primer POST i reutilitzeu-la en els reintents per temps d'espera d'aquella mateixa tasca lògica.
- Si teniu èxit, comproveu
Idempotency-Replayed: truesi necessiteu saber si aquesta resposta ve de la memòria cau o si l'operació s'ha tornat a executar. - Canvieu la clau quan canviïn el fitxer, l'operació o els paràmetres, encara que el principal sigui el mateix.
- Per a
/api/v1/pipeline, una sola clau cobreix tot el POST del pipeline, no cada pas intern.
Què no és una reproducció
Una reproducció no és una cua de tasques duradora. El magatzem és local al procés (un HashMap darrere un mutex) amb un TTL de 24 hores. Passat el termini, o després d'un reinici del procés que buidi el mapa en memòria, la mateixa clau torna a executar l'operació. Els desplegaments de diverses instàncies no comparteixen aquell mapa tret que poseu un magatzem compartit al davant; el middleware d'avui és per procés.
Tracteu Idempotency-Replayed: true com la prova que aquesta resposta ve de la memòria cau, no com un llibre de registre permanent. No vol dir que el PDF s'hagi tornat a processar i no allarga el TTL.
Més detall de la superfície: Desenvolupadors i Fet per a agents d'IA. Les pàgines d'eines com Comprimeix continuen disponibles per a tasques puntuals del navegador sense inventar claus.