وضعیت یک همه‌فرستی زنده YouTube را تغییر می‌دهد و هر فرایندی را که با وضعیت جدید مرتبط است آغاز می‌کند. برای مثال، وقتی وضعیت همه‌فرستی را به testing تغییر می‌دهید، YouTube شروع به انتقال ویدیو به جاری‌سازی مانیتور آن همه‌فرستی می‌کند. قبل‌از فراخوانی این روش، باید تأیید کنید که مقدار ویژگی status.streamStatus برای جاری‌سازی محدود به همه‌فرستی شما active است.
موارد استفاده رایج
درخواست
درخواست HTTP
POST https://www.googleapis.com/youtube/v3/liveBroadcasts/transition
صدور مجوز
این درخواست به مجوز با حداقل یکی از دامنه‌های زیر نیاز دارد. برای کسب اطلاعات بیشتر درباره اصالت‌سنجی و صدور مجوز، به پیاده‌سازی اصالت‌سنجی OAuth 2.0 مراجعه کنید.
| حوزه |
|---|
https://www.googleapis.com/auth/youtube |
https://www.googleapis.com/auth/youtube.force-ssl |
پارامترها
جدول زیر پارامترهایی را که این پُرسمان پشتیبانی می‌کند فهرست می‌کند. همه پارامترهای فهرست‌شده پارامترهای پُرسمان هستند.
| پارامترها | ||
|---|---|---|
| پارامترهای الزامی | ||
broadcastStatus |
stringپارامتر broadcastStatus وضعیتی را که همه‌فرستی به آن تغییر می‌کند شناسایی می‌کند. توجه داشته باشید که برای انتقال یک پخش به حالت testing یا live، status.streamStatus باید برای جریانی که پخش به آن محدود شده است، active باشد.مقادیر قابل قبول عبارتند از:
|
|
id |
stringپارامتر id شناسه یکتای همه‌فرستی را که درحال انتقال به وضعیت دیگری است مشخص می‌کند. |
|
part |
stringپارامتر part فهرستی از یک یا چند دارایی منبع liveBroadcast را مشخص می‌کند که با کاما از هم جدا شده‌اند و پاسخ «میانای برنامه‌سازی کاربردی» شامل آن‌ها خواهد بود. نام‌های part که می‌توانید در مقدار پارامتر بگنجانید عبارت‌اند از id، snippet، contentDetails، و status. |
|
| پارامترهای اختیاری | ||
onBehalfOfContentOwner |
stringاین پارامتر فقط در درخواست مجاز مناسب قابل‌استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است. پارامتر onBehalfOfContentOwner نشان می‌دهد که اطلاعات کاربری مجاز درخواست، کاربر CMS YouTube را که ازطرف مالک محتوای مشخص‌شده در مقدار پارامتر اقدام می‌کند شناسایی می‌کند. این پارامتر برای شرکای محتوای YouTube که مالک و مدیر بسیاری از کانال‌های مختلف YouTube هستند درنظر گرفته شده است. این ویژگی به مالکان محتوا اجازه می‌دهد یک‌بار اصالت‌سنجی کنند و به همه داده‌های ویدیو و کانال خود دسترسی پیدا کنند، بدون اینکه نیاز باشد برای هر کانال به‌طور جداگانه اعتبارنامه‌های اصالت‌سنجی ارائه دهند. حساب CMS که کاربر با آن اصالت‌سنجی می‌کند باید به مالک محتوای YouTube مشخص‌شده پیوند داده شده باشد. |
|
onBehalfOfContentOwnerChannel |
stringاین پارامتر فقط در درخواست مجاز مناسب قابل‌استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است. پارامتر onBehalfOfContentOwnerChannel شناسه کانال YouTube را برای کانالی که ویدیو به آن اضافه می‌شود مشخص می‌کند. این پارامتر زمانی لازم است که درخواستی مقداری را برای پارامتر onBehalfOfContentOwner مشخص کند و فقط می‌تواند همراه با آن پارامتر استفاده شود. علاوه‌براین، درخواست باید بااستفاده از حساب CMS که به مالک محتوایی که پارامتر onBehalfOfContentOwner مشخص می‌کند پیوند داده شده است، مجاز شود. درنهایت، کانالی که مقدار پارامتر onBehalfOfContentOwnerChannel مشخص می‌کند باید به مالک محتوایی که پارامتر onBehalfOfContentOwner مشخص می‌کند پیوند داده شود.این پارامتر برای شرکای محتوای YouTube درنظر گرفته شده است که مالک کانال‌های YouTube مختلفی هستند و آن‌ها را مدیریت می‌کنند. این پارامتر به مالکان محتوا اجازه می‌دهد یک‌بار اصالت‌سنجی کنند و ازطرف کانال مشخص‌شده در مقدار پارامتر اقداماتی را انجام دهند، بدون اینکه نیاز باشد برای هر کانال جداگانه اعتبارنامه‌های اصالت‌سنجی ارائه دهند. |
|
متن درخواست
هنگام فراخوانی این روش، بدنه درخواست ارائه نکنید.
پاسخ
درصورت موفقیت، این روش یک منبع پخش زنده را در بدنه پاسخ برمی‌گرداند.
خطاها
جدول زیر پیام‌های خطایی را که ممکن است «میانای برنامه‌سازی کاربردی» در پاسخ به فراخوانی این روش برگرداند مشخص می‌کند. برای جزئیات بیشتر، به YouTube Live Streaming API - Errors مراجعه کنید.
| نوع خطا | جزئیات خطا | شرح |
|---|---|---|
backendError |
errorExecutingTransition |
هنگام تغییر وضعیت همه‌فرستی خطایی روی داد. |
forbidden (403) |
errorStreamInactive |
وقتی جاری‌سازی‌ای که به همه‌فرستی محدود شده است غیرفعال باشد، انتقال درخواست‌شده مجاز نیست. |
forbidden (403) |
invalidTransition |
پخش زنده نمی‌تواند از وضعیت فعلی به وضعیت درخواستی تغییر کند. |
forbidden (403) |
redundantTransition |
پخش زنده درحال‌حاضر در وضعیت درخواستی است یا درحال پردازش برای رسیدن به وضعیت درخواستی است. |
insufficientPermissions |
insufficientLivePermissions |
درخواست برای انتقال همه‌فرستی زنده مجاز نیست. |
insufficientPermissions |
livePermissionBlocked |
کاربری که درخواست را مجاز کرده است درحال‌حاضر نمی‌تواند ویدیو زنده در YouTube جاری‌سازی کند. برای جزئیات توضیح‌دهنده اینکه چرا کاربر نمی‌تواند ویدیو زنده جاری‌سازی کند، به تنظیمات کانال کاربر در واجدشرایط بودن برای ویژگی مراجعه کنید. |
insufficientPermissions |
liveStreamingNotEnabled |
کاربری که درخواست را مجاز کرده است، برای جاری‌سازی ویدیو زنده در YouTube فعال نیست. برای اطلاعات بیشتر، به واجدشرایط بودن برای ویژگی مراجعه کنید. |
notFound (404) |
liveBroadcastNotFound |
پخش زنده مشخص‌شده توسط پارامتر id وجود ندارد. |
rateLimitExceeded (403) |
userRequestsExceedRateLimit |
کاربر در بازه زمانی مشخصی درخواست‌های زیادی ارسال کرده است. |
rateLimitExceeded (403) |
concurrentBroadcastsExceedLimit |
این کانال درحال‌حاضر حداکثر تعداد پخش زنده همزمان را دارد. قبل‌از اینکه همه‌فرستی دیگری در کانال شروع شود، یک یا چند همه‌فرستی که درحال‌حاضر زنده هستند باید متوقف شوند. |
rateLimitExceeded (403) |
sharedIngestionBroadcastsExceedLimit |
کانال درحال‌حاضر دارای حداکثر تعداد پخش‌های زنده است که منبع انتقال داده را هم‌رسانی می‌کنند. برای شروع همه‌فرستی درخواست‌شده، یک یا چند همه‌فرستی باید متوقف شود. |
required (400) |
idRequired |
پارامتر الزامی id باید همه‌فرستی را که می‌خواهید وضعیت آن را تغییر دهید مشخص کند. |
required (400) |
statusRequired |
درخواست API باید مقداری برای پارامتر status مشخص کند. |
امتحان کنید!
از APIs Explorer برای فراخوانی این API و دیدن درخواست و پاسخ API استفاده کنید.