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 که پخش زنده را شناسایی می‌کند متفاوت است. این مقدار را می‌توان هنگام ارسال درخواست برای درج نقطه راهنما حذف کرد. مقدار در پاسخ API تکمیل خواهد شد.
insertionOffsetTimeMs long
مقدار ویژگی، زمان انحراف را برحسب میلی‌ثانیه مشخص می‌کند که نقطه راهنما باید در آن درج شود. این مقدار از ابتدای جریان مانیتور اندازه‌گیری می‌شود و مقدار پیش‌فرض آن 0 است که نشان می‌دهد نقطه نشان باید در اسرع وقت درج شود. اگر همه‌فرستی شما جاری‌سازی پایش ندارد، نباید مقداری برای این پارامتر مشخص کنید.

اگرچه این مقدار برحسب میلی‌ثانیه اندازه‌گیری می‌شود، اما درواقع تقریبی است و YouTube نقطه نشان را تا حد امکان نزدیک به آن زمان درج خواهد کرد.

مقادیر غیرصفر برای این فیلد فقط درصورتی پشتیبانی می‌شوند که جاری‌سازی همه‌فرستی با تأخیر باشد. اگر جاری‌سازی همه‌فرستی شما تأخیر ندارد، تنها مقدار معتبر 0 است. برای جزئیات بیشتر، به شروع به کار مراجعه کنید.

توجه: اگر همه‌فرستی شما فاز آزمایشی داشته باشد، انحراف از زمانی که فاز آزمایشی شروع شده است اندازه‌گیری می‌شود.

اگر درخواستی سعی کند یک نقطه نشانه را درج کند که مقداری را برای این دارایی و دارایی walltimeMs مشخص می‌کند، میانای برنامه‌سازی کاربردی خطا برمی‌گرداند.
walltimeMs integer
مقدار ویژگی، زمان ساعت دیواری را که نقطه راهنما باید در آن درج شود مشخص می‌کند. این مقدار یک عدد صحیح است که نشان‌دهنده مُهر زمان دوره (به میلی‌ثانیه) است.

اگر در درخواستی سعی شود یک نقطه اشاره‌ای درج شود که مقداری را برای این دارایی و برای دارایی insertionOffsetTimeMs مشخص می‌کند، API خطا برمی‌گرداند.
durationSecs unsigned integer
مدت‌زمان نقطه نشانه، برحسب ثانیه. مقدار باید عدد صحیح مثبت باشد. مقدار پیش‌فرض 30 است.
cueType string
نوع نقطه نشانه. مقدار دارایی باید روی cueTypeAd تنظیم شود.

پاسخ

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

خطاها

جدول زیر پیام‌های خطایی را که ممکن است «میانای برنامه‌سازی کاربردی» در پاسخ به فراخوانی این روش برگرداند مشخص می‌کند. برای جزئیات بیشتر، به YouTube Live Streaming API - Errors مراجعه کنید.

نوع خطا جزئیات خطا شرح
insufficientPermissions (403) insufficientLivePermissions درخواست اجازه ندارد نقطه نشان را در همه‌فرستی زنده درج کند.
insufficientPermissions (403) liveStreamingNotEnabled کاربری که درخواست را مجاز کرده است برای جاری‌سازی ویدیو زنده در YouTube فعال نیست. کاربر می‌تواند اطلاعات بیشتر را در شروع کردن جاری‌سازی زنده و واجدشرایط بودن برای ویژگی پیدا کند.
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 سرویس دردسترس نیست. چند دقیقه دیگر درخواستتان را دوباره امتحان کنید.

امتحان کنید!

برای فراخوانی این API و دیدن درخواست و پاسخ API، از APIs Explorer استفاده کنید.