نظرة عامة على واجهة برمجة التطبيقات لبث YouTube المباشر

تتيح لكم واجهة YouTube Live Streaming API إنشاء وتعديل وإدارة الأحداث المباشرة على YouTube. باستخدام واجهة برمجة التطبيقات، يمكنكم جدولة الأحداث (عمليات البث) وربطها بفيديوهات البث، التي تمثّل محتوى البث الفعلي.

تتألف واجهة برمجة تطبيقات البث المباشر في الواقع من مكوّنات من YouTube Data API وYouTube Content ID API. تتيح Data API لمستخدمي YouTube إدارة حساباتهم على YouTube، بينما تتيح YouTube Content ID API التفاعل مع نظام إدارة الحقوق في YouTube. ومع ذلك، لا تُستخدم جميع الموارد التي تشكّل Live Streaming API إلا لإنشاء الأحداث المباشرة وإدارتها.

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

المفاهيم الأساسية

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

حالات استخدام واجهة برمجة التطبيقات

تقترح القائمة أدناه عدة طرق لاستخدام واجهة برمجة التطبيقات في تطبيقكم:

  • جدولة عمليات البث وتحديد إعدادات البث: يمكن لتطبيقكم أن يتيح للمستخدمين تحديد إعدادات البث مسبقًا ثم اختيار الإعدادات لتطبيقها على بث معيّن. جدولة عمليات البث وتحديد إعدادات البث: يمكن لتطبيقكم أن يتيح للمستخدمين تحديد إعدادات البث مسبقًا ثم اختيار الإعدادات لتطبيقها على بث معيّن.

  • ربط فيديوهات البث بعمليات البث

  • السماح لمقدّمي البث بتحديد معلومات حول البث والفيديو الخاص به (باستخدام YouTube Data API) في الوقت نفسه

  • تسهيل عمليات الانتقال بين حالات البث (مثل testing أو live) والسماح للمستخدمين بإدراج نقاط إشارة

قبل البدء

  1. تحتاجون إلى حساب Google للوصول إلى Google Cloud console وطلب مفتاح واجهة برمجة التطبيقات وتسجيل تطبيقكم.

  2. سجّلوا تطبيقكم في Google لتتمكّنوا من إرسال طلبات بيانات من واجهة برمجة التطبيقات.

  3. بعد تسجيل تطبيقكم، اختاروا YouTube Data API كإحدى الخدمات التي يستخدمها تطبيقكم:

    1. انتقِلوا إلى Cloud console واختاروا المشروع الذي سجّلتموه للتو.
    2. انتقِلوا إلى صفحة واجهات برمجة التطبيقات المفعّلة. في قائمة واجهات برمجة التطبيقات، تأكّدوا من أنّ حالة YouTube Data API الإصدار 3 هي مفعّلة، وإذا كنتم شريك محتوى على YouTube، تأكّدوا من أنّ حالة YouTube Content ID API هي مفعّلة أيضًا.

  4. تعرّفوا على المفاهيم الأساسية لتنسيق بيانات JavaScript Object Notation‏ (JSON). ‫JSON‏ (JavaScript Object Notation) هو تنسيق بيانات شائع مستقل عن اللغة يقدّم تمثيلاً نصيًا بسيطًا عن بنى عشوائية للبيانات. لمزيد من المعلومات، انتقِلوا إلى json.org‏.

تفويض طلبات واجهة برمجة التطبيقات

كما ذكرنا أعلاه، تستخدم Live Streaming API وظائف تشكّل من الناحية الفنية جزءًا من YouTube Data API أو YouTube Content ID API. يمكنكم استخدام Content ID API لتزويد YouTube بالبيانات الوصفية ومعلومات الملكية ومعلومات السياسة لمواد عرضكم. (يُعد بث الفيديو المباشر مثالاً على مادة العرض.) تتيح لكم واجهة برمجة التطبيقات أيضًا المطالبة بملكية الفيديوهات وضبط سياسات الإعلانات لفيديوهاتكم.

يشرح هذا القسم متطلبات التفويض لطلبات Content ID API، التي تختلف عن متطلبات تفويض طلبات Live Streaming API الأخرى.

طلب بيانات من Data API
يجب تفويض طلب بيانات من واجهة برمجة التطبيقات من خلال حساب Google الذي يملك قناة على YouTube للبث.
طلب بيانات من Content ID API
يجب تفويض طلب بيانات من واجهة برمجة التطبيقات من خلال حساب Google مرتبط بمالك المحتوى الذي يملك قناة على YouTube للبث.

الموارد وأنواع الموارد

المورد هو كيان بيانات فردي له معرّف فريد. يصف الجدول أدناه الأنواع المختلفة من الموارد التي ستتفاعلون معها باستخدام الـ Live Streaming API. من الناحية الفنية، يتم تعريف كل هذه الموارد في الواقع كجزء من إما YouTube Data API أو YouTube Content ID API. ومع ذلك، لا تُستخدم موارد liveBroadcast, liveStream, و cuepoint إلا لإنشاء الأحداث المباشرة وإدارتها.

الموارد
liveBroadcast يتضمّن معلومات عن حدث تبثونه على YouTube. مورد liveBroadcast هو امتداد لمورد فيديو على YouTube ويضبط البيانات الوصفية للفيديو التي ستكون ذات صلة ببث مباشر ولكن ليس بفيديوهات YouTube الأخرى.

على هذا النحو، يتطابق مورد liveBroadcast مع مورد فيديو واحد على YouTube. في الواقع، يتشارك مورد liveBroadcast ومورد video المعرّف نفسه. وبعد إنشاء البث باستخدام Live Streaming API، يمكنكم استخدام الـ YouTube Data API لتوفير بيانات وصفية إضافية حول الفيديو.
liveStream يتضمّن معلومات عن فيديو البث الذي ترسلونه إلى YouTube. يوفّر البث المحتوى الذي سيتم بثه لمستخدمي YouTube. بعد إنشاء مورد liveStream ، يمكن ربطه بمورد liveBroadcast واحد فقط. وبالمثل، لا يمكن ربط مورد liveBroadcast إلا بمورد liveStream واحد.
cuepoint يُدرج نقطة إشارة في فيديو البث، ما قد يؤدي إلى ظهور فاصل إعلاني. استخدِموا طريقة liveBroadcasts.cuepoint لإدراج نقطة إشارة أثناء البث.
video يمثّل فيديو واحدًا على YouTube. كما ذكرنا أعلاه، مورد liveBroadcast هو امتداد لمورد video. يمكنكم استخدام YouTube Data API لتعديل البيانات الوصفية حول الفيديو، مثل موقع التسجيل أو المناطق التي سيتم فيها عرض البث.
videoAdvertisingOptions تحدّد إعدادات الإعلانات لفيديو (أو بث). يمكنكم استخدام YouTube Content ID API لضبط خيارات الإعلانات.
asset يمثّل مادة ملكية فكرية، مثل فيلم أو حلقة من برنامج. في هذه الحالة، يكون فيديو البث هو مادة العرض. ستستخدمون YouTube Content ID API لإنشاء موارد asset وإدارتها.
claim يربط الفيديو بمادة عرض يتطابق معها الفيديو. يمكنكم إنشاء مطالبة باستخدام YouTube Content ID API لتحديد أنفسكم كمالك لفيديو البث.
policy تحدّد القواعد التي تحدّد الظروف التي تريدون بموجبها عرض محتواكم على YouTube أو حظره من الظهور على YouTube. عليكم تطبيق سياسة على فيديو البث، ويمكنكم أيضًا تحديد سياسة سيطبقها YouTube على الفيديوهات التي يحمّلها المستخدمون والتي تتطابق مع فيديو البث.

العمليات المتوافقة

يعرض الجدول التالي الطرق المختلفة التي تتيحها واجهة برمجة التطبيقات:

العمليات
list تسترد (GET) قائمة تضم صفرًا أو أكثر من الموارد.
insert تنشئ (POST) موردًا جديدًا.
update تعدّل (PUT) موردًا حاليًا ليعكس البيانات في طلبكم.
bind تربط مورد liveBroadcast بمورد liveStream أو تزيل هذا الرابط.
transition تغيّر حالة مورد liveBroadcast وتبدأ أي عمليات مرتبطة بالحالة الجديدة. على سبيل المثال، عند تغيير حالة البث إلى testing، يبدأ YouTube في إرسال الفيديو إلى فيديو المراقبة الخاص بهذا البث.
delete تزيل (DELETE) موردًا معيّنًا.

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

العمليات المتوافقة
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

الموارد الجزئية

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

المَعلمة part هي مَعلمة مطلوبة لأي طلب بيانات من واجهة برمجة التطبيقات يسترد أو يعرض مورد YouTube Data API. تحدّد المَعلمة سمة واحدة أو أكثر من سمات المورد ذات المستوى الأعلى (غير المتداخلة) التي يجب تضمينها في ردّ من واجهة برمجة التطبيقات. على سبيل المثال، يحتوي مورد liveStream على الأجزاء التالية:

  • snippet
  • cdn
  • status

كل هذه الأجزاء هي كائنات تحتوي على سمات متداخلة، ويمكنكم اعتبار هذه الكائنات مجموعات من حقول البيانات الوصفية التي قد يستردها خادم واجهة برمجة التطبيقات (أو لا يستردها). على هذا النحو، تتطلب منكم المَعلمة part اختيار مكوّنات المورد التي يستخدمها تطبيقكم فعليًا. يخدم هذا الشرط غرضَين مهمّين:

  • يقلّل من وقت الاستجابة من خلال منع خادم واجهة برمجة التطبيقات من قضاء الوقت في استرداد حقول البيانات الوصفية التي لا يستخدمها تطبيقكم.
  • يقلّل من استخدام النطاق الترددي من خلال تقليل (أو إزالة) كمية البيانات غير الضرورية التي قد يستردها تطبيقكم.

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

النصائح وأفضل الممارسات

المطالبة بملكية المحتوى

إذا كنتم تريدون عرض الإعلانات أثناء البث، عليكم المطالبة بملكية فيديو البث قبل بدء الحدث. للمطالبة بملكية المحتوى، يجب أن تكونوا شريك محتوى على YouTube مشاركًا في برنامج Content ID.

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

معاينة المحتوى واختباره

عند تلقّي فيديو البث الوارد، يمكن لـ YouTube بث هذا الفيديو على فيديوَين مختلفَين من فيديوهات البث الصادرة:

  • يتيح لكم فيديو المراقبة معاينة (واختبار) فيديو البث. وهو فيديو خاص لا يمكنكم الوصول إليه إلا أنتم. لا يمكنكم نقل البث إلى مرحلة testing إلا إذا كان فيديو المراقبة الخاص بالبث مفعّلاً. لا يعرض فيديو المراقبة الفواصل الإعلانية.

  • فيديو البث هو الفيديو المرئي لجمهوركم. يمكنكم ضبط حالة خصوصية البث على public أو private أو unlisted. (لا يظهر البث الخاص إلا للمستخدمين الذين تمت دعوتهم صراحةً لمشاهدته، بينما يظهر البث غير المُدرَج لأي مستخدم لديه رابط لمشاهدته.)

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

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

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

عرض "الإعلانات أثناء التشغيل" خلال فيديو البث

أثناء البث، يمكنكم إدراج cuepoint للإشارة إلى أنّه يجب بدء فاصل إعلاني في البث في أقرب وقت ممكن أو في وقت محدّد. يتيح الفاصل الإعلاني لـ YouTube عرض "الإعلانات أثناء التشغيل" خلال البث.

تتسم الفواصل الإعلانية بالخصائص التالية:

  1. لها مدة محدّدة مسبقًا، والتي تضبطونها باستخدام السمة cuepoint لمورد durationSecs. بعد انتهاء الفاصل الإعلاني، يعود المشاهدون إلى البث المباشر.

  2. عند حدوث فاصل إعلاني، لا يتم عرض الإعلان إلا في مشغّل الفيديو للمشاهدين الذين يشاهدون البث عند إدراج نقطة الإشارة. لا يتم عرض الإعلان عندما يعيد المشاهدون تحميل الصفحة حيث يتم فيها تشغيل البث أو عندما يبدأ الزوّار مشاهدة البث بعد الـ نقطة الإشارة.

يعكس تسلسل الخطوات أدناه أفضل الممارسات لإدراج فاصل إعلاني أثناء البث:

ضبط الإزاحات الزمنية

عند إدراج نقطة إشارة، يمكنكم تحديد أنّه يجب إدراجها على الفور أو أنّه يجب إدراجها في نقطة معيّنة في البث. تعتمد الخيارات على ما إذا كان فيديو البث للفيديو مؤخرًا.

  • إذا لم يكن فيديو البث مؤخرًا، يمكنكم إدراج نقطة الإشارة على الفور أو استخدام السمة walltimeMs لبدء الفاصل الإعلاني في وقت معيّن.

    • لبدء الفاصل الإعلاني على الفور، استدعوا طريقة liveBroadcasts.cuepoint. في المورد في نص الطلب، اضبطوا قيمة السمة insertionOffsetTimeMs على 0 أو لا تحدّدوا قيمة لهذه السمة ولا تحدّدوا قيمة للسمة walltimeMs.

      ملاحظة مهمة: لا يرى المشاهدون محتوى الإعلان الناتج على الفور. قد يكون هناك تأخير لمدة 30 ثانية تقريبًا قبل أن يظهر محتوى الإعلان للمستخدمين. خلال هذا التأخير، سيظل فيديو البث مرئيًا للمشاهدين، وعليكم مشاهدة فيديو البث لتحديد وقت ظهور محتوى الإعلان فعليًا بدلاً من فيديو المراقبة.

    • لبدء الفاصل الإعلاني في وقت معيّن، استدعوا طريقة liveBroadcasts.cuepoint واستخدموا السمة walltimeMs لتحديد الوقت المطلوب. قيمة السمة هي عدد صحيح يمثّل طابعًا زمنيًا لحقبة زمنية.

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

    يتم قياس قيمة الإزاحة بالملّي ثانية من بداية فيديو المراقبة لـ البث. يُرجى العِلم أنّه إذا كان البث يتضمّن مرحلة اختبار، يبدأ فيديو المراقبة عندما ينتقل البث إلى حالة testing بخلاف ذلك، يبدأ فيديو المراقبة عندما ينتقل البث إلى حالة live

    عند إدراج نقطة إشارة، اضبطوا السمة cuepoint لمورد insertionOffsetTimeMs على الإزاحة المطلوبة.

حساب قيمة الإزاحة الزمنية

لاسترداد قيمة الإزاحة، استدعوا الدالة getCurrentTime في YouTube Player API للمشغّل الذي يشغّل فيديو المراقبة. استخدِموا القيمة المستردة لإدراج نقطة الإشارة في فيديو البث في ذلك الوقت.

يمكن حساب القيم المحتمَلة لوقت الإزاحة على النحو التالي:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

‫Δ هو مخزن مؤقت مدته خمس ثوانٍ في بداية ونهاية الإزاحات الزمنية المحتمَلة عندما لا يتمكّن YouTube من إدراج نقطة إشارة بدقة. على سبيل المثال:

  • يحتوي البث على مرحلة اختبار مدتها خمس دقائق.
  • يتم تأخير فيديو البث لمدة 60 ثانية بعد فيديو المراقبة.
  • يُدرج مقدّم البث نقطة الإشارة بعد أربع دقائق من انتقال البث إلى live حالة. (بعد ثلاث دقائق من ظهور فيديو البث)

في هذه الحالة، يكون النطاق المحتمَل لأوقات الإزاحة هو [(485,000), (535,000)].

يتم تحديد هذه الأوقات بالملّي ثانية، ويتم حسابها باستخدام القيم التالية:

  • elapsed_time=540000 : تم تشغيل فيديو المراقبة لمدة تسع دقائق (540 ثانية، 540000 ملّي ثانية) عند استدعاء طريقة liveBroadcasts.cuepoint.
  • broadcast_delay=60000 : يتم تأخير فيديو البث لمدة 60 ثانية، أو 60000 ملّي ثانية.
  • Δ=5000 : المخزن المؤقت لمدة خمس ثوانٍ عندما لا يمكن إدراج نقطة الإشارة بشكل موثوق.

تحديد المشاكل وحلّها ومعالجة الأخطاء

توضح الإرشادات التالية كيفية حلّ مشاكل معيّنة قد تنشأ. للاطّلاع على قوائم الأخطاء التي قد تعرضها كل طريقة من طرق واجهة برمجة التطبيقات ، يُرجى الانتقال إلى YouTube Live Streaming API - الأخطاء.

  • عندما ينتقل البث من حالة إلى أخرى، قد يتم تعيين حالة أخرى له مؤقتًا بينما يكمل YouTube الإجراءات المرتبطة بالانتقال. على سبيل المثال، إذا أرسلتم طلب liveBroadcasts.transition لتغيير حالة البث من ready إلى testing، سيضبط YouTube حالة البث على testStarting ثم يكمل الإجراءات المرتبطة بتغيير الحالة. عند اكتمال كل هذه الإجراءات، سيعدّل YouTube حالة البث إلى testing، ما يشير إلى اكتمال عملية الانتقال.

    إذا توقف البث عند حالة testStarting أو liveStarting، عليكم استدعاء طريقة liveBroadcasts.delete وحذف البث. بعد ذلك، أنشئوا بثًا جديدًا واربطوه بفيديو البث المباشر وواصلوا عملية الاختبار.

    كما هو موضّح في مستندات طريقة liveBroadcasts.transition، عليكم التأكّد من أنّ قيمة السمة status.streamStatus لفيديو البث المرتبط بالبث هي active قبل استدعاء هذه الطريقة.