Idempotency-Key: Cubaan Semula yang Selamat untuk Tugasan PDF
Idempotency-Key pada POST di bawah /api/v1/: PDF123 cache respons berjaya 24 jam dalam memori proses dan menetapkan Idempotency-Replayed: true tanpa jalan dua kali.

Tamat masa rangkaian dan cubaan semula oleh klien adalah perkara biasa bagi muat naik PDF multipart. Tanpa kunci idempotensi, POST kedua akan menjalankan merge, OCR, atau compress yang sama sekali lagi, sehingga muat naik dan masa pemprosesan terbuang. Dengan Idempotency-Key, PDF123 boleh memainkan semula respons berjaya yang pertama.
Apa yang dilakukan oleh middleware
Middleware pelayan dalam pdfx-server hanya terpakai kepada panggilan yang mengubah keadaan: POST ke laluan di bawah /api/v1/ (termasuk /api/v1/pipeline). GET dan kaedah lain melaluinya tanpa perubahan. Jika permintaan tiada pengepala Idempotency-Key (atau pengepala itu kosong selepas dipangkas), operasi berjalan seperti biasa tanpa carian cache.
Apabila pengepala itu ada:
- Stor menetapkan kunci entri berdasarkan principal + key. Principal diperoleh daripada
X-API-KEY(sebagaikey:β¦), jika tidak daripadaAuthorization(sebagaiauth:β¦), jika tidak daripada literalanon. Kedua-dua nilai itu dicincang dengan SHA-256 untuk menjadi kunci peta tersebut; badan permintaan bukan sebahagian daripada kunci itu. - Jika ada padanan cache dalam tempoh 24 jam, middleware memulangkan status, jenis kandungan, penyusunan kandungan, dan badan yang tersimpan, serta menetapkan
Idempotency-Replayed: true. - Jika tiada padanan, permintaan diteruskan. Hanya respons berjaya yang disimpan dalam penimbal dan disimpan (respons yang tidak berjaya tidak di-cache untuk pemutaran semula).
- Badan respons disimpan dalam penimbal sehingga 100 MiB supaya pemutaran semula boleh menghantar semula bait fail. Badan yang tidak dapat disimpan dalam penimbal tidak melangkau cache secara senyap: permintaan itu memulangkan HTTP 500, jadi respons yang melebihi had akan gagal dan bukan melaluinya tanpa cache.
Tugasan yang gagal selamat dicuba semula dengan kunci yang sama: kerana kegagalan tidak disimpan, percubaan seterusnya boleh berjaya dan kemudian menjadi hasil yang di-cache. Jangan gunakan semula kunci yang sama untuk fail atau parameter yang berbeza; cache tidak mencincang badan permintaan, hanya principal dan key. Dua pemanggil yang tidak berkongsi kunci API mahupun Authorization tidak boleh berlanggar secara tidak sengaja; pemanggil tanpa nama berkongsi principal anon, jadi mereka mesti memilih kunci yang berbeza.
Cara menghantarnya
Pilih rentetan legap yang stabil bagi setiap tugasan logik (UUID pun boleh):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Pemanggil tanpa nama dan pemanggil berkunci API kedua-duanya berfungsi. Pipeline yang merangkaikan watermark kemudian compress masih perlu menghantar satu kunci bagi setiap permintaan HTTP yang anda mahu elakkan penduaannya, termasuk setiap langkah jika anda menghantar POST secara berasingan, atau satu kunci untuk satu panggilan /api/v1/pipeline.
Tugasan sekali melalui pelayar pada halaman alat (Mampatkan PDF, OCR, β¦) tidak memerlukan anda mencipta kunci sendiri; pengepala itu penting untuk klien yang membuat cubaan semula. Skill terbitan di /skills/pdf123.md menunjukkan Idempotency-Key pada contoh pipeline atas sebab yang sama.
Corak klien yang berkesan
- Hasilkan kunci sebelum POST pertama; gunakan semula kunci itu untuk cubaan semula akibat tamat masa bagi tugasan logik yang sama.
- Apabila berjaya, semak
Idempotency-Replayed: truejika anda perlu tahu sama ada respons ini datang daripada cache atau operasi itu dijalankan semula. - Tukar kunci apabila fail, operasi, atau parameter berubah, walaupun principal kekal sama.
- Untuk
/api/v1/pipeline, satu kunci merangkumi keseluruhan POST pipeline itu, bukan setiap langkah dalamnya.
Apa yang bukan pemutaran semula
Pemutaran semula bukan baris gilir tugasan yang tahan lama. Stornya bersifat setempat proses (HashMap di belakang mutex) dengan TTL 24 jam. Selepas ia luput, atau selepas permulaan semula proses yang menggugurkan peta dalam memori itu, kunci yang sama akan menjalankan operasi itu sekali lagi. Pemasangan berbilang instans tidak berkongsi peta itu melainkan anda meletakkan storan yang dikongsi di hadapannya; middleware hari ini beroperasi bagi setiap proses.
Anggap Idempotency-Replayed: true sebagai bukti bahawa respons ini datang daripada cache, bukan sebagai lejar yang kekal. Ia tidak bermakna PDF itu diproses semula, dan ia tidak melanjutkan TTL.
Butiran lanjut: Pembangun dan Dibina untuk ejen AI. Halaman alat seperti Mampatkan PDF kekal tersedia untuk tugasan pelayar sekali sekala tanpa perlu mencipta kunci.