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

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

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

هذا المستند مخصّص للمطوّرين الذين يريدون إنشاء تطبيقات لتسهيل البث المباشر على 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 في YouTube إذا كنت أحد شركاء المحتوى في YouTube.

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

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

كما أشرنا أعلاه، تستخدم واجهة برمجة التطبيقات للبث المباشر وظائف تشكل جزءًا من الناحية الفنية من 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 بمورد 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

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

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

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

  • snippet
  • cdn
  • status

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط فواصل زمنية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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