Facebook Stories API من Meta

يعرض هذا المستند كيفية استخدام Facebook Stories API لنشر القصص على صفحات فيسبوك.

لنشر قصة، سيقوم التطبيق بتنفيذ الخطوات التالية:

1. تحميل الوسائط الخاصة بمستخدم التطبيق على خوادم Meta
2. نشر الوسائط الخاصة بمستخدم التطبيق على الصفحة كقصة

قبل البدء

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

• سيتعين على مستخدمي التطبيق أن يكونوا قادرين على تنفيذ المهمة CREATE_CONTENT في الصفحة الموضحة في رمز وصول الصفحة ومنح التطبيق الأذونات التالية:

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

إذا كنت تستخدم حساب مستخدم نظام نشاط تجاري في طلبات API، فإن الإذن business_management سيكون مطلوبًا.

متطلبات الوسائط

يجب تقديم صورة أو فيديو يناسب المواصفات التالية.

مواصفات الصورة

مواصفات الفيديو

التقييدات

• لا يمكن استخدام صورة أو فيديو تم تحميله لقصة في منشور تم نشره مسبقًا
• لا يمكن أن تتجاوز قصة الفيديو 60 ثانية
• لتضمين القصص المؤرشفة في طلبات GET لعرض قائمة بالقصص، يجب تشغيل أرشيف القصص على فيسبوك

أفضل الممارسات

يتم تنسيق أمثلة الرموز ضمن هذا المستند لإمكانية القراءة. استبدل القيم الغامقة والمائلة، مثل page_id بالقيم المتوفرة لديك.

قصص الفيديو

لنشر قصة فيديو على صفحة فيسبوك، ستقوم بتهيئة جلسة تحميل الفيديو من خلال خوادم Meta وتحميل الفيديو على خوادم Meta ثم نشر قصة الفيديو.

الخطوة الأولى: تهيئة الجلسة

لتهيئة جلسة التحميل، أرسل طلب POST إلى نقطة النهاية /page_id/video_stories حيث يكون page_id هو معرف صفحة فيسبوك، مع تعيين المعلمة upload_phase على start.

مثال على الطلب

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

عند نجاح العملية، يتلقى التطبيق استجابة JSON تتضمن معرف الفيديو وعنوان URL في فيسبوك حيث سيتم تحميل الفيديو.

مثال على الاستجابة

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v25.0/video_id",
}  

الخطوة الثانية: تحميل فيديو

الآن بعد تهيئة جلسة التحميل وتلقي عنوان URL التحميل، يمكنك تحميل الفيديو. يمكنك تحميل:

• ملف فيديو مستضاف على خادم http/https متاح للعامة مثل CDN
• ملف فيديو محلي من الجهاز

تحميل ملف مستضاف

لتحميل ملف مستضاف، أرسل طلب POST إلى نقطة النهاية upload_url التي تلقيتها في خطوة التهيئة مع تضمين المعلمات التالية:

• file_url تم تعيينه على عنوان URL ملف الفيديو

تأكد من أن المضيف هو rupload.facebook.com.

سترفض API الآن الملفات المستضافة على المواقع التي تقيد الوصول عبر ملف robots.txt. يجب على المطورين التأكد من أن موقع الاستضافة يسمح لوكيل المستخدم "facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)" بالحصول على الملف المستضاف.

سيتم رفض الملفات المستضافة على شبكة CDN من Meta (على سبيل المثال، عناوين URL الخاصة بـ fbcdn). بدلاً من ذلك، يمكن للمطوّرين استخدام ميزة النشر في منشورات متعددة لنشر مقطع فيديو على صفحات متعددة من دون الحاجة إلى تحميل الفيديو إلى كل صفحة. راجع الإرشادات التفصيلية حول النشر في منشورات متعددة.

مثال على الطلب

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

تحميل ملف محلي

لتحميل ملف محلي، أرسل طلب POST إلى نقطة النهاية upload_url التي تلقيتها في خطوة التهيئة مع تضمين المعلمات التالية:

• تعيين offset على 0
• تعيين file_size على الحجم الإجمالي بالبايت للفيديو الذي يتم تحميله

مثال على الطلب

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

عند نجاح التحميل، يتلقى التطبيق استجابة JSON مع تعيين success على true.

مثال على استجابة التحميل

{
    "success": true
}  

تحميل تمت مقاطعته

إذا تمت مقاطعة تحميل الفيديو، فيمكنك إعادة تشغيل التحميل أو استئنافه.

• لإعادة تشغيل التحميل، أعد إرسال طلب POST وقم بتعيين offset على 0.
• لاستئناف التحميل، أعد إرسال طلب POST مع تعيين offset على القيمة bytes_transfered من عملية التحقق من الحالة.

الحصول على حالة التحميل

للتحقق من حالة الفيديو أثناء التحميل أو النشر، أرسل طلب GET إلى نقطة النهاية /video_id بمع تضمين المعلمة التالية:

• تعيين fields على status

مثال على الطلب

curl -X GET "https://graph.facebook.com/v25.0/video_id" \
	-d "fields=status"

عند نجاح العملية، يتلقى التطبيق استجابة JSON تحتوي على:

• كائن status يحتوي على:

  • video_status بالقيمة ready أو processing أو expired أو error
  • كائن uploading_phase بأزواج القيم والمفاتيح التالية:

    • تعيين status على in_progress أو not_started أو complete أو error
    • تعيين bytes_transfered على البايت التي تم تحميلها. يمكن استخدامها كقيمة لـ offset إذا تمت مقاطعة التحميل.
  • كائن processing_phase بأزواج القيم والمفاتيح التالية:

    • تعيين status على in_progress أو not_started أو complete أو error
  • كائن processing_phase بأزواج القيم والمفاتيح التالية:

    • تعيين status على in_progress أو not_started أو complete أو error
    • تعيين publish_status على published أو not_published
    • تعيين publish_time على طابع زمني بتنسيق UNIX للوقت الفعلي أو المنشور

مثال على الاستجابة

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

الخطوة 3. نشر قصة فيديو

لنشر قصة فيديو إلى الصفحة، سترسل POST إلى نقطة النهاية /page_id/video_stories مع تضمين المعلمات التالية:

• تعيين video_id على معرف الفيديو الذي تم تحميله
• تعيين upload_phase على finish

مثال على الطلب

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

عند نجاح العملية، يتلقى التطبيق استجابة JSON تحتوي على أزواج القيم والمفاتيح التالية:

• تعيين success على true
• تعيين post_id على معرف منشور القصة

مثال على الاستجابة

{
  "success": true,
  "post_id": 1234
}

قصص الصور

الخطوة 1. تحميل صورة

تفضل بزيارة مرجع منشورات الصفحة للتعرف على كيفية تحميل صورة في خوادم Meta باستخدام نقطة النهاية /page_id/photos. تأكد من تضمين المعلمة published وتعيينها على false.

الخطوة الثانية. نشر قصة صورة

لنشر قصة صورة على الصفحة، سترسل طلب POST إلى نقطة النهاية /page_id/photo_stories مع تضمين المعلمات التالية:

• تعيين photo_id على معرف الصورة التي تم تحميلها

مثال على الطلب

curl -X POST "https://graph.facebook.com/v25.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

عند نجاح العملية، يتلقى التطبيق استجابة JSON تحتوي على أزواج القيم والمفاتيح التالية:

• تعيين success على true
• تعيين post_id على معرف منشور القصة

مثال على الاستجابة

{
  "success": true,
  "post_id": 1234
}

الحصول على القصص

للحصول على قائمة بكل القصص في الصفحة وبيانات حول القصة، أرسل طلب GET إلى نقطة النهاية /page_id/stories حيث يكون page_id هو معرف الصفحة التي تريد عرضها.

مثال على الطلب

    
curl -i -X GET "https://graph.facebook.com/v25.0/page_id/stories"

عند نجاح العملية، يتلقى التطبيق استجابة JSON تتضمن مصفوفة كائنات حيث يحتوي كل كائن على معلومات حول قصة منشورة في الصفحة. يحتوي كل كائن على أزواج القيم والمفاتيح التالية:

• تعيين post_id على معرف منشور القصة المنشورة
• تعيين status على PUBLISHED وARCHIVED
• تعيين creation_time على طابع زمني بتنسيق UNIX عند نشر القصة
• تعيين media_type على video أو photo
• تعيين media_id على معرف الفيديو أو القصة في منشور القصة
• تعيين url على عنوان URL فيسبوك لمنشور القصة، مثل https://facebook.com/stories/8283482737484972

مثال على الاستجابة

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

يمكنك فلترة القصص حسب الحالة، إما منشورة أو مؤرشفة، والتاريخ باستخدام المعلمتين since وuntil.

راجع أيضًا

تعرف على المزيد حول نقاط النهاية والمفاهيم الموضحة في هذا الدليل.

الدلائل ذات الصلة

• مستخدم نظام النشاط التجاري
• تسجيل دخول فيسبوك
• تسجيل دخول فيسبوك للأعمال
• Graph API - النتائج المقسمة إلى صفحات بالقيم "منذ" و"حتى"

مراجع نقاط النهاية

• مرجع الصفحة
• مرجع قصص فيديو الصفحة
• مرجع قصص صور الصفحة
• مرجع الفيديو
• مرجع رؤى القصص