‏واجهة API الفيديو‏

النشر

تتيح لك API الفيديو نشر مقاطع الفيديو على الصفحات والمجموعات. علمًا بأن النشر لدى المستخدمين غير مدعوم.

كما يمكنك نشر مقاطع ريلز على الصفحات. لمزيد من المعلومات، راجع API نشر مقاطع ريلز.

تتضمن عملية نشر مقاطع الفيديو اختيار بروتوكول التحميل وإرسال طلب POST إلى عنصر الربط /videos التابع للصفحة أو المجموعة المستهدفة. تدعم API بروتوكولات التحميل القابل للاستئناف وغير القابل للاستئناف. نوصي باستخدام بروتوكول التحميل القابل للاستئناف نظرًا لأنه أكثر تنوعًا ويمكنه معالجة حالات انقطاع الاتصال بكفاءة.

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

المتطلبات

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

النشر على الصفحات

يجب أن يتوفر لدى مستخدم التطبيق دور المسؤول في الصفحة التي تستهدفها. وستحتاج إلى رمز وصول الصفحة الخاص بمستخدم التطبيق، ويجب منح تطبيقك الأذونات pages_show_list وpages_read_engagement وpages_manage_posts.

النشر على المجموعات

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

التحميل القابل للاستئناف

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

يمكنك نشر فيديو على صفحة أو مجموعة. وتتضمن عملية النشر الخطوات التالية:

  1. بدء جلسة تحميل على الصفحة أو المجموعة،
  2. تحميل الأجزاء الفردية بالترتيب الذي ينبغي تجميعها به
  3. وإنهاء جلسة التحميل.

بمجرد إنهاء جلسة التحميل، سنعمل على إعادة تجميع الفيديو وترميزه ونشره.

التقييدات

يتم تقييد مقاطع الفيديو عند 10 جيجابايت ومدة تصل إلى 4 ساعات.

الخطوة الأولى: بدء جلسة تحميل

لبدء جلسة تحميل الفيديو، أرسل طلب POST إلى نقطة النهاية مقاطع فيديو الصفحة:

POST /v19.0/{page-id}/videos
  ?upload_phase=start
  &access_token={access-token}
  &file_size={file-size}

احرص على تضمين المعلمات التالية:

اسم المعلمةالقيمة

upload_phase

start

access_token

رمز وصول الصفحة في حالة النشر على صفحة أو رمز وصول المستخدم في حالة النشر على مجموعة.

file_size

إجمالي حجم ملف الفيديو بالبايت.

عينة من الطلب

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=start" \
  -F "access_token=EAADI..." \
  -F "file_size=22420886"

عينة من الاستجابة

{
  "video_id":"2918040888250909",          //Capture this value (optional)
  "start_offset":"0",                     //Capture this value
  "end_offset":"1048576",
  "upload_session_id":"2918040901584241"  //Capture this value
}

احتفظ بالقيمتين start_offset وupload_session_id اللتين يتم إرجاعهما بواسطة API. حيث ستستخدمهما في الخطوة التالية لتحميل الجزء الأول من الفيديو. قد تحتاج أيضًا إلى الاحتفاظ بقيمة video_id. علمًا بأنك لا تحتاجها عند النشر، ولكنها ستمثل المعرف النهائي للفيديو المنشور.

الخطوة الثانية: تحميل الأجزاء بشكل فردي

احرص على تحميل أجزاء الفيديو بالترتيب الذي ينبغي تجميعها به من خلال إرسال طلبات POST متتالية إلى نقطة نهاية مقاطع فيديو الصفحة:

POST /v19.0/{page-id}/videos
  ?upload_phase=transfer
  &access_token={access-token}
  &upload_session_id={upload-session-id}
  &start_offset={start-offset}
  &video_file_chunk={video-file-chunk}

احرص على تضمين البيانات التالية في صورة multipart/form-data في النص الأساسي للطلب:

اسم بيانات النموذجالقيمة

upload_phase

transfer

access_token

رمز وصول الصفحة في حالة النشر على صفحة أو رمز وصول المستخدم في حالة النشر على مجموعة.

upload_session_id

معرف جلسة التحميل لديك.

start_offset

قيمة start_offset التي تم إرجاعها في الاستجابة السابقة.

video_file_chunk

اسم جزء الفيديو المطلوب تحميله.

في كل مرة تقوم خلالها بتحميل الجزء بنجاح، سيتم إرجاع قيمة start_offset جديدة. يمكنك تكرار هذا الطلب باستخدام قيمة start_offset التي تم إرجاعها حديثًا واسم الجزء التالي من الفيديو المطلوب تحميله (تم تعيينه إلى video_file_chunk)، وتابع تكرار الأمر بالتدريج نفسه مع جميع أجزاء الفيديو المتبقية.

عينة من طلب الجزء الأول

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=0" \
  -F "video_file_chunk=@/Users/...xaa"

عينة من الاستجابة

{
  "start_offset":"10485760",  //Value for second chunk
  "end_offset":"15728640"
}

عينة من طلب الجزء الثاني

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=transfer" \
  -F "upload_session_id=2918040901584241" \
  -F "access_token=EAADI..." \
  -F "start_offset=10485760" \
  -F "video_file_chunk=@/Users/...xab"

عينة من الاستجابة

{
  "start_offset":"20971520",  //Value for third chunk
  "end_offset":"22420886"
}

بمجرد تحميل الجزء الأخير، يجب أن تستجيب API بإرسال القيمتين start_offset وend_offset المتطابقتين مما يشير إلى أنه يمكنك إنهاء جلسة التحميل.

عينة من الاستجابة الأخيرة

{
  "start_offset":"22420886",  //When values match you can
  "end_offset":"22420886"     //end the upload session
}

الخطوة الثالثة: إنهاء جلسة التحميل

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

POST /v19.0/{page-id}/videos
  ?upload_phase=finish
  &access_token={access-token}
  &upload_session_id={upload-session-id}

احرص على تضمين المعلمات التالية:

اسم المعلمةالقيمة

upload_phase

finish

access_token

رمز وصول الصفحة في حالة النشر على صفحة أو رمز وصول المستخدم في حالة النشر على مجموعة.

upload_session_id

معرف جلسة التحميل لديك.

يمكنك أيضًا تضمين أي معلمات إضافية تدعمها نقطة نهاية مقاطع فيديو الصفحة، مثل title وdescription وthumb.

عينة من الطلب

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos"  \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"

عينة من استجابة JSON

{
  "success":true
}

عندما تتلقى هذه الاستجابة، فإنها تشير إلى أننا بدأنا تجميع الفيديو الكامل وترميزه. وستتمكّن من مشاهدة الفيديو المنشور في غضون دقائق.

التحميل غير القابل للاستئناف

نوصيك بتحميل الملفات باستخدام بروتوكول التحميل القابل للاستئناف نظرًا لأنه يعالج حالات انقطاع الاتصال بكفاءة أكبر ويدعم ملفات بحجم أكبر. ومع ذلك، إذا كنت تفضل تحميل الملفات باستخدام بروتوكول التحميل غير القابل للاستئناف، فيمكنك إجراء ذلك من خلال إرسال طلب POST إلى عنصر الربط مقاطع فيديو الصفحة وتضمين المعلمة source (بالنسبة لملفات الفيديو المحلية) أو المعلمة file_url (بالنسبة للملفات التي تتم استضافتها على خادم عام) في النص الأساسي للطلب لديك في صورة multipart/form-data. يمكنك أيضًا تضمين أي معلمات إضافية تدعمها نقطة نهاية مقاطع فيديو الصفحة، مثل title وdescription وthumb.

التقييدات

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

عينة من طلب الملف المحلي

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"

عينة من طلب الملف المُستضاف

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "file_url=https://socialsizz.../incredible.mov"

عند نجاح الأمر، ستستجيب API من خلال معرف الفيديو المنشور.

عينة من الاستجابة

{
  "id":"287788272232962"  //ID of the published Video
}

الصور المصغرة للفيديو

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

متطلبات الصورة المصغرة

التنسيق: BMP وGIF وJPEG وPNG وTIFF
حجم الملف: 10 ميجابايت أو أقل.

لا توجد متطلبات لأبعاد الصورة، ولكن يجب أن تشترك في نسبة العرض إلى الارتفاع نفسها المُستخدمة في الفيديو لديك.

عينة من طلب التحميل القابل للاستئناف الذي يتضمن صورة مصغرة

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "upload_phase=finish" \
  -F "access_token=EAADI..." \
  -F "upload_session_id=2918040901584241"
  -F "thumb=@/Users/...thumbnail_image.png"

عينة من استجابة JSON

{
  "success":true
}

عينة من طلب التحميل غير القابل للاستئناف الذي يتضمن صورة مصغرة

curl -X POST \
  "https://graph-video.facebook.com/v19.0/1755847768034402/videos" \
  -F "access_token=EAADd..." \
  -F "source=@/Users/...incredible.mov"
  -F "thumb=@/Users/...thumbnail_image.png"

عينة من الاستجابة

{
  "id":"287788272232962"
}