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 مورد نیاز که پخش را مشخص می کند متفاوت است. این مقدار می تواند هنگام ارسال درخواست برای درج نقطه نشانه حذف شود. مقدار در پاسخ API پر می شود.
insertionOffsetTimeMs	long مقدار مشخصه زمانی را که نقطه نشانه باید درج شود، در میلی ثانیه تعیین می کند. مقدار از ابتدای جریان مانیتور اندازه گیری می شود و مقدار پیش فرض آن 0 است که نشان می دهد نقطه نقطه باید در اسرع وقت درج شود. اگر پخش شما جریان مانیتور ندارد، نباید مقداری برای این پارامتر تعیین کنید. اگرچه در میلی ثانیه اندازه گیری می شود، اما در واقع یک تقریبی است و YouTube نقطه نشانه را تا حد امکان به آن زمان نزدیک می کند. مقادیر غیر صفر برای این فیلد فقط در صورت تأخیر پخش جریانی پشتیبانی می‌شوند. اگر پخش جریانی شما تاخیر نداشته باشد، 0 تنها مقدار معتبر است. برای جزئیات بیشتر به راهنمای شروع کار مراجعه کنید. توجه: اگر پخش شما مرحله آزمایشی داشت، افست از زمانی که مرحله آزمایش شروع شد اندازه گیری می شود. اگر درخواستی بخواهد نقطه ای را وارد کند که مقداری برای این ویژگی و ویژگی walltimeMs مشخص می کند، API یک خطا برمی گرداند.
walltimeMs	integer مقدار ویژگی زمان ساعت دیواری را که در آن نقطه نشانه باید درج شود مشخص می کند. مقدار یک عدد صحیح است که نشان دهنده یک مهر زمانی دوره است (بر حسب میلی ثانیه). اگر درخواستی بخواهد نقطه ای را وارد کند که مقداری برای این ویژگی و ویژگی insertionOffsetTimeMs مشخص می کند، API یک خطا برمی گرداند.
durationSecs	unsigned integer مدت زمان نقطه نشانه، بر حسب ثانیه. مقدار باید یک عدد صحیح مثبت باشد. مقدار پیش فرض 30 است.
cueType	string نوع نقطه نشانه. مقدار ویژگی باید روی cueTypeAd تنظیم شود.

واکنش

در صورت موفقیت آمیز بودن، این روش منبع cuepoint درج شده را در بدنه پاسخ برمی گرداند.

خطاها

جدول زیر پیام های خطایی را مشخص می کند که API می تواند در پاسخ به تماس با این روش بازگرداند. مستندات پیام خطا همه خطاهایی را که API پخش جریانی زنده می تواند بازگرداند را شناسایی می کند.

نوع خطا	جزئیات خطا	شرح
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 مورد نیاز باید در بدنه درخواست API مشخص شود.
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 برای فراخوانی این API و مشاهده درخواست و پاسخ API استفاده کنید.