Polling และ Webhook ของ PiAPI: จัดการงานเสร็จอย่างเชื่อถือได้

เมื่อคำขอภาพหรือวิดีโอได้รับการยอมรับ ยังต้องมีขั้นตอนจัดการเมื่อทำงานเสร็จ สำหรับงานที่ใช้ Unified API ของ PiAPI ให้บันทึกรหัสงาน ตรวจสถานะสุดท้าย แล้วจัดการผลลัพธ์ตามโมเดล การ polling เหมาะกับการเชื่อมต่อครั้งแรก ส่วน webhook ช่วยให้แบ็กเอนด์ตอบสนองเมื่องานจบ

1. บันทึกรหัสงานและจำกัดการ polling

หลังสร้างงาน ให้บันทึก data.task_id คู่กับรหัสงานของแอป ดึงงานเดิมด้วยคีย์ API ฝั่งเซิร์ฟเวอร์ การตอบกลับ HTTP สำเร็จไม่ได้ยืนยันว่าการสร้างเสร็จแล้ว ต้องตรวจ data.status

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

เมื่อเป็น completed ให้ตรวจ data.output ตามโมเดล เมื่อเป็น failed ให้บันทึก data.error จำกัดจำนวนครั้งที่ลองใหม่ เพิ่มช่วงรอและสุ่มความหน่วงเล็กน้อย กำหนดเวลารอของแอปเป็นการตัดสินใจภายใน การหมดเวลาไม่ได้แปลว่างานปลายทางล้มเหลวหรือถูกยกเลิก เก็บรหัสไว้ตรวจสอบภายหลัง

2. เพิ่ม callback ที่ตรวจสอบตัวตน

ผสานส่วนตั้งค่าด้านล่างกับเนื้อหาคำขอสร้างงานที่ถูกต้อง โดยคงฟิลด์เดิมไว้ ใช้ปลายทาง HTTPS สาธารณะและค่าลับจากที่เก็บที่ปลอดภัยของแบ็กเอนด์ เอกสาร PiAPI ระบุว่าส่งค่าลับในเฮดเดอร์ x-webhook-secret จึงต้องตรวจสอบก่อนรับการแจ้งเตือน

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

JSON ของ webhook มี timestamp และ data ตรวจว่างานเป็นของแอป จากนั้นบันทึกเหตุการณ์อย่างถาวรหรือใส่คิวถาวร แล้วตอบ 2xx โดยเร็ว ทำการดาวน์โหลดและงานที่ใช้เวลานานนอกตัวจัดการ HTTP เตรียมรับการส่งซ้ำ เพราะเอกสารอธิบายการลองใหม่เมื่อไม่ได้รับคำตอบสำเร็จ

3. รวม polling และ callback เข้าสู่การประมวลผลเดียว

ใช้ตัวจัดการเสร็จสิ้นร่วมกัน ข้อกำหนดไม่ซ้ำแบบถาวรตามรหัสงานและการกระทำสุดท้ายช่วยป้องกันการแจ้งเตือนหรือการเริ่มงานถัดไปสองครั้ง เวลาเพียงอย่างเดียวไม่พอแยกเหตุการณ์ระหว่างงาน ละเว้นข้อมูลเก่าหลังถึงสถานะสุดท้าย และออกแบบ worker ให้ลองใหม่อย่างปลอดภัยหลังหยุดทำงาน

หาก callback ไม่มา หรือสถานะไม่ชัด ให้ดึงรหัสงานที่บันทึกไว้อีกครั้ง การหมดเวลาระหว่างดึงข้อมูลไม่ใช่เหตุผลให้สร้างงานเสียเงินใหม่ทันที แยกข้อผิดพลาดการรับส่งออกจากงานล้มเหลวที่ยืนยันแล้ว และตรวจสอบก่อนส่งใหม่

4. ทดสอบกรณีผิดพลาด

ก่อนเปิดใช้ ให้ส่ง callback ซ้ำ ใช้ค่าลับผิด หน่วงการส่ง และจำลองการเริ่ม worker ใหม่ ตรวจว่าแต่ละงานที่เสร็จมีผลลัพธ์ถาวรหนึ่งรายการ และงานที่ล้มเหลวเก็บข้อผิดพลาดไว้ จากนั้นใช้คู่มือเก็บผลลัพธ์เพื่อรักษาไฟล์

อ้างอิง: โครงสร้าง Unified API, ตัวอย่างดึงงาน และเอกสาร Webhook ตัวอย่างอธิบายโครงสร้างการเชื่อมต่อ ไม่ใช่ผลทดสอบประสิทธิภาพการสร้างจริง