LiveBroadcasts: cuepoint

لإدراج نقطة بداية في بث مباشر قد يؤدي نقطة البدء إلى تشغيل فاصل إعلاني.

ملاحظة: تحلّ هذه الطريقة محلّ الطريقة liveCuepoints.insert التي كانت تتطلّب تفويض الطلبات من خلال حساب مرتبط بأحد مالكي المحتوى على YouTube. لا تتطلب هذه الطريقة متطلبات التفويض نفسها.

الطلب

طلب HTTP

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

التفويض

يتطلب هذا الطلب تفويضًا بنطاق واحد على الأقل من النطاقات التالية. للاطّلاع على مزيد من المعلومات عن المصادقة والتفويض، يُرجى الاطّلاع على مقالة تنفيذ مصادقة OAuth 2.0.

النطاق
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

المعلمات

يعرض الجدول التالي المَعلمات التي يتيح طلب البحث استخدامها. جميع المَعلمات المُدرَجة هي مَعلمات طلب بحث.

المعلمات
المَعلمات المطلوبة
id string
تُحدِّد المَعلمة id البث الذي يتم فيه إدراج نقطة البدء. يجب أن يكون البث قيد البث بشكل نشط عند إدراج نقطة البدء.
المَعلمات الاختيارية
onBehalfOfContentOwner string
لا يمكن استخدام هذه المَعلمة إلا في طلب مفوَّض بشكل صحيح.
ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء محتوى YouTube الذين يملكون ويديرون العديد من قنوات YouTube المختلفة. ويسمح هذا المقياس لمالكي المحتوى بالمصادقة مرة واحدة وتنفيذ الإجراءات نيابةً عن القناة المحدّدة في قيمة المَعلمة، بدون الحاجة إلى تقديم بيانات اعتماد مصادقة مختلفة لكل قناة منفصلة. يجب أن يكون الحساب الذي يستخدمه المستخدم لتأكيد هويته مرتبطًا بمالك المحتوى المحدّد على YouTube.
تشير المَعلمة onBehalfOfContentOwner إلى أنّ بيانات اعتماد التفويض الخاصة بالطلب تحدّد مستخدمًا على YouTube يتصرّف نيابةً عن صاحب المحتوى على YouTube المحدّد في قيمة المَعلمة. هذه المَعلمة مخصّصة لشركاء محتوى YouTube الذين يملكون ويديرون العديد من القنوات المختلفة على YouTube.
onBehalfOfContentOwnerChannel string
لا يمكن استخدام هذه المَعلمة إلا في طلب مفوَّض بشكل صحيح.
ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء محتوى YouTube الذين يملكون ويديرون العديد من قنوات YouTube المختلفة. ويسمح هذا الإجراء لمالكي المحتوى بالمصادقة مرة واحدة وتنفيذ الإجراءات نيابةً عن القناة المحدّدة في قيمة المَعلمة ، بدون الحاجة إلى تقديم بيانات اعتماد المصادقة لكل قناة منفصلة.
تحدِّد المَعلمة onBehalfOfContentOwnerChannel معرّف قناة YouTube للقناة المرتبطة بالبث الذي يتم إدراج نقطة البدء فيه. تكون هذه المَعلمة مطلوبة عندما يحدّد الطلب قيمة للمَعلمة onBehalfOfContentOwner، ولا يمكن استخدامها إلا مع هذه المَعلمة. تنطبق أيضًا المتطلبات التالية:
  • يجب أن يكون الطلب مفوَّضًا من خلال حساب مستخدم مرتبط بمالك المحتوى الذي تحدد المَعلمة onBehalfOfContentOwner.
  • يجب أن تكون القناة التي تحدّدها قيمة المَعلمة onBehalfOfContentOwnerChannel مرتبطة بصاحب المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner.

نص الطلب

قدِّم مورد cuepoint في نص الطلب. تعرض بنية JSON التالية تنسيق مورد cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
 في نص الطلب، يجب ملء حقل cueType ويجب ضبطه على cueTypeAd. يمكنك أيضًا ضبط قيم لهذه السمات:
  • durationSecs
  • insertionOffsetTimeMs (يجب عدم ضبطها إذا تم ضبط walltimeMs)
  • walltimeMs (يجب عدم ضبطها إذا تم ضبط insertionOffsetTimeMs)

الخصائص

يحدِّد الجدول التالي السمات التي تظهر في هذا المرجع:

الخصائص
id string
قيمة تحدّدها YouTube لتحديد نقطة البدء بشكل فريد يُرجى العلم أنّ هذه القيمة تختلف عن المَعلمة المطلوبة id التي تحدد البث. يمكن حذف هذه القيمة عند إرسال طلب لإدراج نقطة بدء. ستتم تعبئة القيمة في ردّ واجهة برمجة التطبيقات.
insertionOffsetTimeMs long
تحدِّد قيمة السمة وقت البدء، بالملي ثانية، الذي يجب فيه إدراج نقطة البدء. يتم قياس القيمة من بداية بث الشاشة، وتكون القيمة التلقائية لها هي 0، ما يشير إلى أنّه يجب إدراج نقطة البدء في أقرب وقت ممكن. يجب عدم تحديد قيمة لهذه المَعلمة إذا لم يكن البث يحتوي على بث مراقبة.

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

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

ملاحظة: إذا كان البث قد مرّ بمرحلة اختبار، يتم قياس المدة الفاصلة من وقت بدء مرحلة الاختبار.

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

تعرِض واجهة برمجة التطبيقات خطأً إذا حاول طلب إدراج نقطة إشارة تحدّد قيمة لهذه السمة وسمة insertionOffsetTimeMs.
durationSecs unsigned integer
مدّة نقطة البدء، بالثواني يجب أن تكون القيمة عددًا صحيحًا موجبًا. القيمة التلقائية هي 30.
cueType string
نوع نقطة البدء. يجب ضبط قيمة السمة على cueTypeAd.

الردّ

في حال نجاح هذه الطريقة، ستُرجع القيمة المُدرَجة cuepoint resource في نص الاستجابة.

الأخطاء

يحدِّد الجدول التالي رسائل الخطأ التي يمكن أن تعرِضها واجهة برمجة التطبيقات استجابةً لطلب باستخدام هذه الطريقة. لمزيد من التفاصيل، يُرجى الاطّلاع على YouTube Live Streaming API - Errors.

نوع الخطأ تفاصيل الخطأ الوصف
insufficientPermissions (403) insufficientLivePermissions الطلب غير مصرّح له بإدراج نقطة بداية في البث المباشر.
insufficientPermissions (403) liveStreamingNotEnabled المستخدم الذي فوّض الطلب غير مفعّل له بث فيديو مباًع على YouTube. يمكن للمستخدم العثور على مزيد من المعلومات في مقالتَي: بدء البث المباشر ومتطلبات الأهلية لاستخدام الميزات.
rateLimitExceeded (403) userRequestsExceedRateLimit أرسل المستخدم عددًا كبيرًا جدًا من الطلبات في إطار زمني معيّن.
required (400) idRequired يجب أن تحدّد المَعلمة المطلوبة id البث الذي تريد إدراج نقطة إشارة فيه.
required (400) cueTypeRequired يجب تحديد الحقل المطلوب cueType في نص طلب واجهة برمجة التطبيقات.
notFound (404) liveBroadcastNotFound البث المحدّد بالمَعلمة id غير متوفّر.
invalidValue (400) conflictingTimeFields يمكن تحديد قيمة واحدة فقط من insertionOffsetTimeMs و walltimeMs. يؤدي ضبط كلتا القيمتَين إلى حدوث خطأ. إذا لم تضبط أيًّا من القيمتَين، ستستخدم YouTube وقت insertionOffsetTimeMs التلقائي (0)، ما يعني أنّه سيتم إدراج نقطة البدء في أقرب وقت ممكن.
invalidValue (400) invalidInsertionOffsetTimeMs حدّد المورد cuepoint قيمة غير صالحة لسمة insertionOffsetTimeMs. يجب أن تكون القيمة 0 أو عددًا صحيحًا موجبًا.
invalidValue (400) invalidWalltimeMs حدّد المورد cuepoint قيمة غير صالحة لسمة walltimeMs. يجب أن تكون القيمة عددًا صحيحًا يمثّل طابعًا زمنيًا لبداية الحقبة (بالملي ثانية).
backendError (5xx) serviceUnavailable الخدمة غير متاحة. يُرجى إعادة إرسال طلبك بعد بضع دقائق.

جرّب الآن

استخدِم APIs Explorer للاتّصال بهذه الواجهة والاطّلاع على طلب البيانات والاستجابة من واجهة برمجة التطبيقات.