LiveBroadcasts: cuepoint

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

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

الطلب

طلب HTTP

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

التفويض

يتطلب هذا الطلب تفويضًا باستخدام نطاق واحد على الأقل من النطاقات التالية (مزيد من المعلومات حول المصادقة والتفويض).

النطاق
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 الذي تم إدراجه في نص الاستجابة.

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
insufficientPermissions (403) insufficientLivePermissions إنّ الطلب غير مصرّح به لإدراج نقطة إشارة في البث المباشر.
insufficientPermissions (403) liveStreamingNotEnabled لم يتم تفعيل المستخدم الذي فوّضت الطلب ببث الفيديو المباشر على YouTube. يمكن للمستخدم العثور على مزيد من المعلومات على الرابطَين https://support.google.com/youtube/answer/2474026 وhttps://www.youtube.com/features.
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 لاستدعاء واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات من واجهة برمجة التطبيقات والرد عليها.