ProductDakika 3 za kusoma

Idempotency-Key: Majaribio Salama kwa Kazi za PDF

Tuma Idempotency-Key kwa POST za /api/v1/. PDF123 huhifadhi majibu yaliyofanikiwa saa 24 kwenye kumbukumbu ya mchakato; Idempotency-Replayed: true huzuia kurudia.

By the PDF123 team Β· Updated 2026-09-30
Idempotency-Key: Majaribio Salama kwa Kazi za PDF

Muda wa mtandao unaoisha na majaribio ya pili ya wateja ni kawaida kwa upakiaji wa PDF wa sehemu nyingi. Bila funguo ya idempotency, POST ya pili huendesha merge, OCR au kubana hiyo hiyo kutoka mwanzo, ikirudia upakiaji na muda wa usindikaji. Kwa Idempotency-Key, PDF123 inaweza kurudia jibu la kwanza lililofanikiwa badala yake.

Kifuniko cha kati hufanya nini

Kifuniko cha kati cha seva kwenye pdfx-server hutumika kwa simu zinazobadilisha pekee: POST kwa njia chini ya /api/v1/ (ikiwemo /api/v1/pipeline). GET na mbinu nyingine hupita bila mabadiliko. Kama ombi halina kichwa cha Idempotency-Key (au ni tupu baada ya kukatwa), operesheni huendeshwa kawaida bila kuangalia hifadhi.

Kichwa kinapokuwepo:

  1. Hifadhi huweka kiingilio kwa mhusika + funguo. Mhusika hutokana na X-API-KEY (kama key:…), vinginevyo Authorization (kama auth:…), vinginevyo neno halisi anon. Thamani hizo mbili hupigwa hashi (SHA-256) kwenye funguo ya ramani; mwili wa ombi hauwi sehemu ya funguo.
  2. Kwa kupatikana kwenye hifadhi ndani ya saa 24, kifuniko hurudisha hali iliyohifadhiwa, aina ya maudhui, mpangilio wa maudhui na mwili, na huweka Idempotency-Replayed: true.
  3. Kwa kutokupatikana, ombi huendelea. Majibu yaliyofanikiwa pekee huhifadhiwa kwa kurudiwa (majibu yasiyofanikiwa hayahifadhiwi kwa kurudiwa).
  4. Miili ya majibu huhifadhiwa hadi 100 MiB ili kurudiwa kuweze kutuma tena baiti za faili. Mwili usioweza kuhifadhiwa hauruki hifadhi kimya kimya: ombi hilo hurudisha HTTP 500, hivyo jibu linalozidi kikomo hushindwa badala ya kupita bila kuhifadhiwa.

Kazi zilizoshindwa ni salama kujaribiwa tena kwa funguo hiyo hiyo: kwa kuwa kushindwa hakuhifadhiwi, jaribio linalofuata linaweza kufanikiwa na kisha kuwa tokeo lililohifadhiwa. Usitumie funguo tena kwa faili au vigezo tofauti; hifadhi haipigi hashi mwili, bali mhusika na funguo pekee. Waitaji wawili wasioshiriki funguo ya API wala Authorization hawawezi kugongana kwa bahati; waitaji bila jina hushiriki mhusika anon, hivyo wanapaswa kuchagua funguo tofauti.

Jinsi ya kuituma

Chagua mfuatano thabiti usiofafanuliwa kwa kila kazi ya kimantiki (UUID inafaa):

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

Waitaji bila jina na wenye funguo za API wote hufanya kazi. Mitiririko inayofunga muhuri wa maji kisha kubana inapaswa bado kutuma funguo moja kwa kila ombi la HTTP unalotaka kulizuia kurudiwa, ikiwemo kila hatua kama unaituma kando, au funguo moja kwa mwito mmoja wa /api/v1/pipeline.

Kazi moja za kivinjari kwenye kurasa za zana (Bana, OCR, …) hazikuhitaji kuvumbua funguo; kichwa ni muhimu kwa wateja wanaojaribu tena. Ujuzi uliochapishwa kwenye /skills/pdf123.md huonyesha Idempotency-Key kwenye mfano wa pipeline kwa sababu hiyo hiyo.

Mifumo ya wateja inayofanya kazi

  • Tengeneza funguo kabla ya POST ya kwanza; itumie tena kwenye majaribio ya pili ya muda unaoisha kwa kazi hiyo hiyo ya kimantiki.
  • Baada ya kufanikiwa, angalia Idempotency-Replayed: true kama unahitaji kujua kama jibu hili lilitoka kwenye hifadhi au liliendesha operesheni tena.
  • Badilisha funguo wakati faili, operesheni au vigezo vinabadilika, hata kama mhusika anabaki yeye yeye.
  • Kwa /api/v1/pipeline, funguo moja hushughulikia POST yote ya pipeline, si kila hatua ya ndani.

Kurudiwa si nini

Kurudiwa si foleni ya kazi ya kudumu. Hifadhi ni ya ndani ya mchakato (HashMap nyuma ya mutex) yenye TTL ya saa 24. Baada ya kuisha, au baada ya kuanzisha upya mchakato unaotupa ramani iliyo kwenye kumbukumbu, funguo hiyo hiyo huendesha operesheni tena. Uenezaji wa mifano mingi haushiriki ramani hiyo isipokuwa uweke hifadhi inayoshirikiwa mbele; kifuniko cha leo ni cha kila mchakato.

Chukua Idempotency-Replayed: true kama uthibitisho kuwa jibu hili lilitoka kwenye hifadhi, si kama leja ya kudumu. Haimaanishi PDF ilisindikwa upya, na haiongezi TTL.

Maelezo zaidi ya uso: Watengenezaji na Imejengwa kwa ajenti wa AI. Kurasa za zana kama Bana zinabaki kupatikana kwa kazi moja za kivinjari bila kuvumbua funguo.

Open tool
Process in the browser β€” no watermark, files removed after the job.
Open tool