PPDF123
Productอ่านประมาณ 1 นาที

Idempotency-Key: การลองใหม่ที่ปลอดภัยสำหรับงาน PDF

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

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: การลองใหม่ที่ปลอดภัยสำหรับงาน PDF

การหมดเวลาเครือข่ายและการลองใหม่จากฝั่งไคลเอนต์เป็นเรื่องปกติของอัปโหลด PDF แบบ multipart ถ้าไม่มี idempotency key การ POST ครั้งที่สองอาจรันการรวม OCR หรือบีบอัดเดิมซ้ำอีกครั้ง ทำให้เสียทั้งการอัปโหลดและเวลาในการประมวลผลซ้ำ เมื่อส่ง Idempotency-Key PDF123 จะเล่นการตอบกลับที่สำเร็จครั้งแรกซ้ำแทนได้

มิดเดิลแวร์ทำอะไร

มิดเดิลแวร์บนเซิร์ฟเวอร์ใน pdfx-server ใช้กับการเรียกที่เปลี่ยนสถานะเท่านั้น คือ POST ไปยังเส้นทางใต้ /api/v1/ (รวม /api/v1/pipeline) ส่วน GET และเมธอดอื่นผ่านไปโดยไม่เปลี่ยนอะไร ถ้าคำขอไม่มีเฮดเดอร์ Idempotency-Key (หรือมีแต่ว่างหลัง trim) op จะรันตามปกติโดยไม่ค้นแคช

เมื่อมีเฮดเดอร์:

  1. สโตร์เก็บรายการด้วย principal + key โดย principal มาจาก X-API-KEY (ในรูป key:…) ถ้าไม่มีจึงใช้ Authorization (ในรูป auth:…) ถ้าไม่มีอีกจึงใช้คำว่า anon ค่าสองส่วนนี้ถูกแฮช (SHA-256) เป็นคีย์ในแมป ส่วนบอดีของคำขอไม่ถูกนำมาเป็นส่วนของคีย์
  2. เมื่อแคชฮิตภายใน 24 ชั่วโมง มิดเดิลแวร์จะคืนสถานะ content type content disposition และบอดีที่เก็บไว้ พร้อมตั้ง Idempotency-Replayed: true
  3. เมื่อแคชพลาด คำขอจะดำเนินต่อไป และมีเฉพาะการตอบกลับที่สำเร็จเท่านั้นที่ถูกบัฟเฟอร์และเก็บไว้ (การตอบกลับที่ไม่สำเร็จไม่ถูกแคชเพื่อเล่นซ้ำ)
  4. บอดีของการตอบกลับถูกบัฟเฟอร์ได้ถึง 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 ยังใช้สำหรับงานเบราว์เซอร์ครั้งเดียวโดยไม่ต้องสร้างคีย์

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 CLI หรือคุณจะโฮสต์สแตกเองและเก็บไฟล์ไว้ในเครือข่ายของคุณก็ได้