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

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

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

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

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

الْإِعْلَانَاتْ عَلَى كُلِّ الْأَجْهِزَة

يمثل البث حدثًا يمكن مشاهدته على YouTube أثناء حدوثه. كما يمكن تسجيل عمليات البث وحفظها كمقاطع فيديو على YouTube لكي يتمكن المستخدمون من مشاهدتها بعد حدوثها.

جداول مائية

يحدّد البث محتوى الصوت والفيديو الذي يتم إرساله إلى YouTube. يتم ربط كل عملية بث ببث فيديو واحد.

نقاط تشغيل

تمثّل نقطة الإشارة فاصلاً إعلانيًا يمكن إدراجه في بث مباشر.

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

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

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

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

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

• يمكنك تبسيط الانتقالات بين حالات البث (على سبيل المثال، testing أو live) والسماح للمستخدمين بإدراج نقاط بدء.

قبل البدء

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

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

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

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

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

الموافقة على طلبات البيانات من واجهة برمجة التطبيقات

كما هو موضّح أعلاه، تستخدم واجهة برمجة التطبيقات Live Streaming API وظائف تشكِّل جزءًا من الناحية الفنية إما في YouTube Data API أو واجهة برمجة تطبيقات Content ID في YouTube. يمكنك استخدام 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 يتشاركان نفس المعرّف. بعد إنشاء البث باستخدام واجهة برمجة تطبيقات البث المباشر، يمكنك استخدام YouTube Data API لتوفير بيانات وصفية إضافية حول الفيديو.
liveStream	يحتوي على معلومات عن الفيديو المضمّن الذي تنقله إلى YouTube. توفر مجموعة البث المحتوى الذي سيتم بثه لمستخدمي YouTube. بعد إنشاء مورد liveStream، يمكن ربط مورد liveBroadcast واحد فقط بمورد 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 على الفيديوهات التي يحمّلها المستخدم والتي تتطابق مع فيديو البث.

العمليات المتاحة

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

العمليات
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 بتفعيل بث المراقبة للبث حتى تتمكن من اختبار المحتوى. يجب أيضًا اختيار ما إذا كنت تريد تأجيل البث أيضًا بناءً على رغبتك في التحكم في توقيت نقاط الإشارات بدلاً من رغبتك في التفاعل مع الجمهور أو توفير تغطية في الوقت الفعلي لحدث ما.

عرض إعلانات أثناء التشغيل خلال بث مباشر

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

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

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

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

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

تعيين معادلة الوقت

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

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

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

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

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

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

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

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

حساب قيمة معادلة الوقت

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

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

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

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

• يستغرق البث مرحلة اختبار لمدة خمس دقائق.
• يتأخر بث البث لمدة 60 ثانية بعد بث الشاشة.
• يقوم القائم بالبث بإدخال نقطة إشارة البدء بعد أربع دقائق من انتقالات البث إلى الحالة: live (يستغرق هذا الإجراء ثلاث دقائق بعد أن يصبح بث البث مرئيًا.)

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

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

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

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

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

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

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

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