Polling và webhook PiAPI: xử lý hoàn tất tác vụ đáng tin cậy

Yêu cầu ảnh hoặc video được chấp nhận vẫn cần quy trình xử lý hoàn tất. Với tác vụ dùng API hợp nhất của PiAPI, hãy lưu ID, kiểm tra trạng thái cuối rồi xử lý đầu ra theo mô hình. Polling phù hợp khi mới tích hợp; webhook giúp máy chủ phản ứng khi công việc kết thúc.

1. Lưu ID và giới hạn polling

Sau khi tạo, lưu data.task_id cùng ID công việc của ứng dụng. Truy vấn lại đúng tác vụ bằng khóa API phía máy chủ. HTTP thành công không chứng minh quá trình tạo đã xong: hãy kiểm tra 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}"

Với completed, xác minh data.output theo mô hình; với failed, lưu data.error. Giới hạn số lần thử, tăng khoảng chờ và thêm độ lệch ngẫu nhiên. Thời hạn chờ của ứng dụng là lựa chọn cục bộ: hết hạn không chứng minh tác vụ từ xa thất bại hoặc bị hủy. Giữ ID để đối chiếu sau.

2. Thêm callback có xác thực

Ghép đoạn cấu hình dưới đây vào nội dung yêu cầu tạo tác vụ hợp lệ, giữ nguyên các trường cấu hình hiện có. Dùng endpoint HTTPS công khai và bí mật trong kho an toàn của máy chủ. Theo tài liệu PiAPI, bí mật được gửi qua header x-webhook-secret; xác minh trước khi nhận thông báo.

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

JSON webhook có timestamp và data. Kiểm tra tác vụ thuộc ứng dụng, lưu bền vững sự kiện hoặc đưa vào hàng đợi bền vững rồi nhanh chóng trả 2xx. Thực hiện tải xuống và việc tốn thời gian ngoài bộ xử lý HTTP. Dự kiến có gửi lặp: tài liệu mô tả thử lại khi không nhận phản hồi thành công.

3. Hợp nhất polling và callback

Dùng chung bộ xử lý hoàn tất. Ràng buộc duy nhất bền vững theo ID tác vụ và hành động kết thúc giúp tránh hai thông báo hoặc hai công việc tiếp theo. Chỉ dấu thời gian không đủ phân biệt sự kiện giữa các tác vụ. Bỏ qua cập nhật cũ sau trạng thái cuối và thiết kế worker có thể thử lại an toàn sau sự cố.

Nếu thiếu callback hoặc trạng thái chưa rõ, truy vấn lại ID đã lưu. Truy vấn hết thời gian không phải lý do tạo ngay một tác vụ trả phí khác. Phân biệt lỗi truyền tải với lỗi tác vụ đã xác nhận và đối chiếu trước khi quyết định gửi lại.

4. Kiểm tra tình huống lỗi

Trước triển khai, phát lại callback, gửi bí mật sai, trì hoãn giao nhận và mô phỏng khởi động lại worker. Mỗi tác vụ hoàn tất phải tạo đúng một kết quả bền vững; tác vụ thất bại phải giữ lỗi. Sau đó dùng hướng dẫn lưu đầu ra để bảo quản tệp.

Tham khảo: lược đồ API hợp nhất, ví dụ truy vấn tác vụ và tài liệu webhook. Ví dụ minh họa cấu trúc tích hợp, không phải đo hiệu năng tạo thực tế.