Idempotency-Key: การลองใหม่ที่ปลอดภัยสำหรับงาน PDF
ส่ง Idempotency-Key บนงาน POST ใต้ /api/v1/ ระบบแคชคำตอบที่สำเร็จไว้ 24 ชั่วโมงในหน่วยความจำของโปรเซส และตั้ง Idempotency-Replayed: true แทนการรันซ้ำสองครั้ง

การหมดเวลาเครือข่ายและการลองใหม่จากฝั่งไคลเอนต์เป็นเรื่องปกติของอัปโหลด PDF แบบ multipart ถ้าไม่มี idempotency key การ POST ครั้งที่สองอาจรันการรวม OCR หรือบีบอัดเดิมซ้ำอีกครั้ง ทำให้เสียทั้งการอัปโหลดและเวลาในการประมวลผลซ้ำ เมื่อส่ง Idempotency-Key PDF123 จะเล่นการตอบกลับที่สำเร็จครั้งแรกซ้ำแทนได้
มิดเดิลแวร์ทำอะไร
มิดเดิลแวร์บนเซิร์ฟเวอร์ใน pdfx-server ใช้กับการเรียกที่เปลี่ยนสถานะเท่านั้น คือ POST ไปยังเส้นทางใต้ /api/v1/ (รวม /api/v1/pipeline) ส่วน GET และเมธอดอื่นผ่านไปโดยไม่เปลี่ยนอะไร ถ้าคำขอไม่มีเฮดเดอร์ Idempotency-Key (หรือมีแต่ว่างหลัง trim) op จะรันตามปกติโดยไม่ค้นแคช
เมื่อมีเฮดเดอร์:
- สโตร์เก็บรายการด้วย principal + key โดย principal มาจาก
X-API-KEY(ในรูปkey:…) ถ้าไม่มีจึงใช้Authorization(ในรูปauth:…) ถ้าไม่มีอีกจึงใช้คำว่าanonค่าสองส่วนนี้ถูกแฮช (SHA-256) เป็นคีย์ในแมป ส่วนบอดีของคำขอไม่ถูกนำมาเป็นส่วนของคีย์ - เมื่อแคชฮิตภายใน 24 ชั่วโมง มิดเดิลแวร์จะคืนสถานะ content type content disposition และบอดีที่เก็บไว้ พร้อมตั้ง
Idempotency-Replayed: true - เมื่อแคชพลาด คำขอจะดำเนินต่อไป และมีเฉพาะการตอบกลับที่สำเร็จเท่านั้นที่ถูกบัฟเฟอร์และเก็บไว้ (การตอบกลับที่ไม่สำเร็จไม่ถูกแคชเพื่อเล่นซ้ำ)
- บอดีของการตอบกลับถูกบัฟเฟอร์ได้ถึง 100 MiB เพื่อให้การเล่นซ้ำส่งไบต์ของไฟล์กลับไปได้ บอดีที่บัฟเฟอร์ไม่ได้จะไม่ข้ามแคชไปเงียบ ๆ แต่คำขอนั้นจะคืน HTTP 500 ดังนั้นการตอบกลับที่เกินขีดจำกัดจะล้มเหลว แทนที่จะผ่านไปโดยไม่ถูกแคช
งานที่ล้มเหลวลองใหม่ด้วยคีย์เดิมได้อย่างปลอดภัย เพราะความล้มเหลวไม่ถูกเก็บ ความพยายามครั้งถัดไปจึงอาจสำเร็จและกลายเป็นผลลัพธ์ที่ถูกแคช อย่าใช้คีย์ซ้ำกับไฟล์หรือพารามิเตอร์อื่น เพราะแคชไม่ได้แฮชบอดี แต่แฮชแค่ principal กับคีย์ ผู้เรียกสองรายที่ไม่แชร์ API key หรือ 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 request ที่ต้องการ dedupe ไม่ว่าจะเป็นแต่ละขั้นหากคุณ POST แยกกัน หรือคีย์เดียวสำหรับการเรียก /api/v1/pipeline ครั้งเดียว
งานครั้งเดียวบนเบราว์เซอร์ในหน้าเครื่องมือ (Compress, OCR, …) ไม่บังคับให้คุณสร้างคีย์ขึ้นมาเอง เฮดเดอร์นี้สำคัญกับไคลเอนต์ที่ลองใหม่ สกิลที่เผยแพร่ที่ /skills/pdf123.md ก็แสดง Idempotency-Key บนตัวอย่าง pipeline ด้วยเหตุผลเดียวกัน
แพตเทิร์นไคลเอนต์ที่ใช้ได้
- สร้างคีย์ก่อน POST ครั้งแรก แล้วใช้คีย์เดิมเมื่อลองใหม่เพราะหมดเวลา สำหรับงานเชิงตรรกะงานนั้น
- เมื่อสำเร็จ ให้ตรวจ
Idempotency-Replayed: trueหากต้องรู้ว่าการตอบกลับนี้รันงานใหม่หรือมาจากแคช - เปลี่ยนคีย์เมื่อไฟล์ op หรือพารามิเตอร์เปลี่ยน แม้ principal จะยังเหมือนเดิม
- สำหรับ
/api/v1/pipelineคีย์เดียวครอบคลุมทั้ง POST ของ pipeline ไม่ใช่แต่ละขั้นข้างใน
การเล่นซ้ำไม่ใช่อะไร
การเล่นซ้ำไม่ใช่คิวงานแบบถาวร สโตร์เป็นแบบ process-local (HashMap หลัง mutex) พร้อม TTL 24 ชั่วโมง หลังหมดอายุ หรือหลังรีสตาร์ทโปรเซสที่ทำให้แมปในหน่วยความจำหายไป คีย์เดิมจะรัน op อีกครั้ง การดีพลอยหลายอินสแตนซ์ไม่แชร์แมปนั้น เว้นแต่คุณจะวางสโตร์ร่วมไว้ข้างหน้า มิดเดิลแวร์วันนี้เป็นแบบต่อโปรเซส
ให้ถือ Idempotency-Replayed: true เป็นหลักฐานว่าการตอบกลับนี้มาจากแคช ไม่ใช่สมุดบัญชีถาวร มันไม่ได้หมายความว่า PDF ถูกประมวลผลใหม่ และไม่ได้ยืด TTL
รายละเอียดพื้นผิวเพิ่มเติม: Developers และ สร้างมาเพื่อเอเจนต์ AI ส่วนหน้าเครื่องมืออย่าง Compress ยังใช้สำหรับงานเบราว์เซอร์ครั้งเดียวโดยไม่ต้องสร้างคีย์