الاستعلام الدوري وWebhooks في PiAPI: معالجة اكتمال المهام بثبات

قبول طلب صورة أو فيديو لا يُغني عن معالجة اكتماله. لمهام واجهة PiAPI الموحدة، احفظ معرّف المهمة وتحقق من حالتها النهائية ثم عالج المخرجات بحسب النموذج. يناسب الاستعلام الدوري التكامل الأول، بينما يتيح Webhook للخادم الاستجابة عند انتهاء العمل.

1. احفظ المعرّف وحدد الاستعلام الدوري

بعد الإنشاء، احفظ 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. أضف إشعارًا راجعًا موثّقًا

ادمج المقطع التالي في جسم صالح لإنشاء مهمة، مع الحفاظ على حقول الإعداد الموجودة. استخدم عنوان HTTPS عامًا وسرًا من مخزن أسرار الخادم. توضح وثائق PiAPI إرسال السر في الترويسة x-webhook-secret؛ تحقق منه قبل قبول الإشعار.

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

يحتوي JSON الخاص بالإشعار على timestamp وdata. تأكد أن المهمة تخص التطبيق، ثم احفظ الحدث بشكل دائم أو ضعه في طابور دائم وأعد استجابة 2xx سريعًا. نفّذ التنزيلات والعمل الطويل خارج معالج HTTP. توقع التكرار، فالوثائق تصف إعادة الإرسال عند غياب استجابة ناجحة.

3. اجمع الاستعلام والإشعارات في معالج واحد

استخدم معالج اكتمال مشتركًا. قيد تفرد دائم على معرّف المهمة والإجراء النهائي يمنع الإشعارات المزدوجة أو تشغيل العمل التالي مرتين. الطابع الزمني وحده لا يميز أحداث المهام المختلفة. تجاهل التحديثات القديمة بعد الحالة النهائية واجعل العامل قابلًا لإعادة المحاولة بأمان بعد التعطل.

إذا لم يصل الإشعار أو كانت الحالة غامضة، استعلم مجددًا بالمعرّف المحفوظ. انتهاء مهلة الاستعلام لا يبرر إنشاء مهمة مدفوعة أخرى بلا تحقق. ميّز خطأ النقل عن فشل المهمة المؤكد وطابق الحالة قبل إعادة الإرسال.

4. اختبر حالات الفشل

قبل النشر، أعد إرسال إشعار واستخدم سرًا خاطئًا وأخّر التسليم وحاكِ إعادة تشغيل العامل. تحقق أن كل مهمة مكتملة تنتج نتيجة دائمة واحدة وأن المهام الفاشلة تحتفظ بأخطائها. ثم اتبع دليل حفظ المخرجات.

المراجع: مخطط API الموحد، مثال جلب المهمة، ووثائق Webhook. توضح الأمثلة بنية التكامل وليست قياسًا لأداء توليد فعلي.