YouTube Live Streaming API به شما امکان میدهد رویدادهای زنده را در YouTube ایجاد، بهروزرسانی، و مدیریت کنید. بااستفاده از API، میتوانید رویدادها (همهفرستیها) را زمانبندی کنید و آنها را با جاریسازیهای ویدیویی که محتوای همهفرستی واقعی را نشان میدهند مرتبط کنید.
«میانای برنامهسازی کاربردی جاریسازی زنده» درواقع از اجزای «میانای برنامهسازی کاربردی داده YouTube» و «میانای برنامهسازی کاربردی Content ID در YouTube» تشکیل شده است. Data API به کاربران YouTube امکان میدهد حسابهای YouTube خود را مدیریت کنند، درحالیکه YouTube Content ID API امکان تعامل با سیستم مدیریت حقوق YouTube را فراهم میکند. بااینحال، تمام منابعی که Live Streaming API را تشکیل میدهند، فقط برای ایجاد و مدیریت رویدادهای زنده استفاده میشوند.
این سند برای توسعهدهندگانی است که میخواهند برنامههایی برای تسهیل پخش مستقیم در YouTube بنویسند. این سند مفاهیم پایه YouTube و خود API را توضیح میدهد. همچنین نمای کلی از عملکردهای مختلفی که API پشتیبانی میکند ارائه میدهد.
مفاهیم اصلی
- همهفرستیها
- همهفرستی نشاندهنده رویدادی است که میتوان آن را در YouTube بهمحض وقوع تماشا کرد. همچنین میتوان پخشها را ضبط کرد و بهعنوان ویدیو YouTube ذخیره کرد تا کاربران بتوانند آنها را بعداز وقوع تماشا کنند.
- جاریسازی
- جاریسازی محتوای صوتی-تصویری را که به YouTube منتقل میشود شناسایی میکند. هر همهفرستی با یک جاریسازی ویدیو مرتبط است.
- نقطههای نشانه
- cuepoint نشاندهنده وقفه آگهی است که میتواند در همهفرستی زنده درج شود.
موارد استفاده از میانای برنامهسازی کاربردی
فهرست زیر چندین روش برای استفاده از API در برنامه شما پیشنهاد میدهد:
-
همهفرستیها را زمانبندی کنید و تنظیمات همهفرستی را تعریف کنید. برنامه شما میتواند به کاربران امکان دهد تنظیمات همهفرستی را ازقبل تعریف کنند و سپس تنظیمات را برای اعمال در یک همهفرستی خاص انتخاب کنند.
-
جاریسازیهای ویدیو و همهفرستیها را مرتبط کنید.
-
به پخشکنندگان امکان میدهد اطلاعات مربوط به یک پخش و ویدیو آن را (بااستفاده از YouTube Data API) بهطور همزمان تعریف کنند.
-
گذار بین وضعیتهای همهفرستی را ساده کنید (برای مثال،
testingیاlive) و به کاربران امکان دهید نشانهای راهنما را درج کنند.
قبلاز شروع
-
برای دسترسی به Google Cloud console، درخواست کلید میانای برنامهسازی کاربردی، و ثبت برنامهتان به حساب Google نیاز دارید.
-
برنامهتان را در Google ثبت کنید تا بتواند درخواستهای میانای برنامهسازی کاربردی را ارسال کند.
-
پساز ثبت کردن برنامهتان، YouTube Data API را بهعنوان یکی از سرویسهایی که برنامهتان استفاده میکند انتخاب کنید:
- به Cloud console بروید و پروژهای را که بهتازگی ثبت کردهاید انتخاب کنید.
- به صفحه میاناهای برنامهسازی کاربردی فعالشده بروید. در فهرست میاناهای برنامهسازی کاربردی، مطمئن شوید که وضعیت YouTube Data API v3 و، اگر «شریک محتوای YouTube» هستید، YouTube Content ID API روی روشن تنظیم شده باشد.
-
با مفاهیم اصلی قالب داده نشانگذاری شیء جاوا اسکریپت (JSON) آشنا شوید. JSON یک قالب داده رایج و مستقل از زبان است که نمایش نوشتاری سادهای از ساختارهای داده دلخواه ارائه میدهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.
درحال صدور مجوز برای درخواستهای میانای برنامهسازی کاربردی
همانطور که در بالا ذکر شد، Live Streaming API از عملکردی استفاده میکند که ازنظر فنی بخشی از YouTube Data API یا YouTube Content ID API است. میتوانید از Content ID API برای ارائه فراداده، اطلاعات مالکیت، و اطلاعات خطمشی داراییهای خود به YouTube استفاده کنید. (همهفرستی ویدیو زنده نمونهای از دارایی است.) این API همچنین به شما امکان میدهد ویدیوها را ادعا کنید و خطمشیهای آگهی را برای ویدیوهای خود تنظیم کنید.
این بخش الزامات مجوز برای درخواستهای Content ID API را توضیح میدهد که با الزامات مجوز برای سایر درخواستهای Live Streaming API متفاوت است.
- درحال تماس با Data API
- درخواست API باید توسط «حساب Google» که مالک کانال YouTube پخشکننده است مجاز شود.
- درحال تماس با Content ID API
- درخواست API باید توسط یک حساب Google که به مالک محتوای مالک کانال YouTube پخش زنده پیوند شده است، مجاز شود.
منابع و انواع منبع
منبع یک موجودیت داده تکی با شناسه یکتا است. جدول زیر انواع مختلف منابعی را که بااستفاده از Live Streaming API با آنها تعامل خواهید داشت شرح میدهد. ازنظر فنی، همه این منابع درواقع بهعنوان بخشی از YouTube Data API
یا YouTube Content ID API تعریف میشوند. بااینحال،
منابع liveBroadcast،
liveStream، و
cuepoint
فقط برای ایجاد و مدیریت رویدادهای زنده استفاده میشوند.
| منابع | |
|---|---|
liveBroadcast |
حاوی اطلاعاتی درباره رویدادی است که در YouTube پخش میکنید. منبع liveBroadcast یک افزونه از منبع ویدیو YouTube است و فراداده ویدیویی را تنظیم میکند که مربوط به یک پخش زنده است اما نه به سایر ویدیوهای YouTube.بنابراین، یک منبع liveBroadcast دقیقاً با یک منبع ویدیو YouTube مطابقت دارد.
درواقع، منبع liveBroadcast و منبع video شناسه یکسانی دارند. و پساز ایجاد کردن همهفرستی بااستفاده از Live Streaming API، میتوانید از YouTube Data API برای ارائه فراداده بیشتر درباره ویدیو استفاده کنید. |
liveStream |
حاوی اطلاعاتی درباره جاریسازی ویدیویی است که به YouTube ارسال میکنید. جاریسازی
محتوایی را که برای کاربران YouTube همهفرستی میشود ارائه میدهد. پساز ایجاد، منبع liveStream
میتواند دقیقاً به یک منبع liveBroadcast محدود شود. بهطور مشابه،
منبع liveBroadcast فقط میتواند به یک منبع liveStream محدود شود. |
cuepoint |
یک نقطه نشانه در جاریسازی ویدیویی همهفرستی درج میکند که ممکن است وقفه آگهی را فعال کند. از روش
liveBroadcasts.cuepoint
برای درج نقطه نشان درطول پخش استفاده کنید.
|
video |
نشاندهنده یک ویدیو YouTube است. همانطور که در بالا ذکر شد، منبع liveBroadcast افزونهای از منبع video است. میتوانید از YouTube Data API برای بهروزرسانی فرادادههای مربوط به ویدیو، مانند مکان ضبط یا مناطقی که پخش در آنها قابلمشاهده خواهد بود، استفاده کنید. |
videoAdvertisingOptions |
تنظیمات تبلیغات برای یک ویدیو (یا پخش زنده) را تعریف میکند. از YouTube Content ID API برای تنظیم گزینههای تبلیغات استفاده میکنید. |
asset |
نشاندهنده یک قطعه مالکیت فکری، مانند یک فیلم یا یک قسمت از یک نمایش است. در این مورد، ویدیو پخش زنده دارایی است. از YouTube Content ID API برای ایجاد و مدیریت منابع asset استفاده خواهید کرد. |
claim |
ویدیو را به داراییای که ویدیو با آن مطابقت دارد پیوند میدهد. شما بااستفاده از YouTube Content ID API ادعایی ایجاد میکنید تا خود را بهعنوان مالک ویدیو همهفرستی معرفی کنید. |
policy |
قوانینی را تعریف میکند که شرایطی را مشخص میکنند که تحت آن میخواهید محتوای شما در YouTube قابل مشاهده باشد یا از نمایش در YouTube مسدود شود. باید خطمشیای را برای ویدیو همهفرستیتان اعمال کنید و همچنین میتوانید خطمشیای را مشخص کنید که YouTube برای ویدیوهای بارگذاریشده توسط کاربر که با ویدیو همهفرستی شما مطابقت دارند اعمال کند. |
عملیات پشتیبانیشده
جدول زیر روشهای مختلفی را که API پشتیبانی میکند نشان میدهد:
| عملیات | |
|---|---|
list |
فهرستی از صفر یا چند منبع را بازیابی میکند (GET). |
insert |
منبع جدیدی (POST) ایجاد میکند. |
update |
منبع موجود را اصلاح میکند (PUT) تا دادههای درخواستتان را منعکس کند. |
bind |
منبع liveBroadcast را به منبع liveStream پیوند میدهد یا چنین پیوندی را برمیدارد. |
transition |
وضعیت منبع liveBroadcast را تغییر میدهد و هر فرایند مرتبط با وضعیت جدید را آغاز میکند. برای مثال، وقتی وضعیت همهفرستی را به testing تغییر میدهید، YouTube شروع به انتقال ویدیو به جاریسازی مانیتور آن همهفرستی میکند. |
delete |
منبع خاصی را برمیدارد (DELETE). |
جدول زیر عملیات پشتیبانیشده برای انواع مختلف منابع را مشخص میکند. عملیاتی که منابع را درج، بهروزرسانی، یا حذف میکنند همیشه به مجوز کاربر نیاز دارند. در برخی موارد، روشهای list از درخواستهای مجاز و غیرمجاز پشتیبانی میکنند، درحالیکه درخواستهای غیرمجاز فقط دادههای عمومی را بازیابی میکنند و درخواستهای مجاز میتوانند اطلاعاتی را که برای کاربر اصیلسازیشده محدود شده است نیز بازیابی کنند.
| عملیات پشتیبانیشده | |||||||
|---|---|---|---|---|---|---|---|
| list | insert | update | bind | transition | cuepoint | delete | |
| liveBroadcast | |||||||
| liveStream | |||||||
منابع جزئی
این API امکان بازیابی منابع جزئی را فراهم میکند و درواقع آن را الزامی میکند تا برنامهها از انتقال، تجزیه، و ذخیره دادههای غیرضروری اجتناب کنند. این رویکرد همچنین تضمین میکند که API از منابع شبکه، CPU و حافظه بهطور کارآمدتری استفاده کند.
پارامتر part پارامتری الزامی برای هر درخواست API است که منبع YouTube Data API را بازیابی یا برمیگرداند. این پارامتر یک یا چند دارایی منبع سطح بالا (غیرتودرتو) را که باید در پاسخ API گنجانده شود شناسایی میکند. برای مثال، منبع liveStream دارای بخشهای زیر است:
snippetcdnstatus
همه این بخشها اشیایی هستند که حاوی داراییهای تودرتو هستند و میتوانید این اشیا را بهعنوان گروههایی از فیلدهای فراداده درنظر بگیرید که ممکن است کارگزار API آنها را بازیابی کند (یا نکند). به همین دلیل، پارامتر part از شما میخواهد مؤلفههای منبعی را که برنامهتان واقعاً استفاده میکند انتخاب کنید. این الزام دو هدف مهم را دنبال میکند:
- این کار با جلوگیری از صرف وقت سرور API برای بازیابی فیلدهای فرادادهای که برنامه شما از آنها استفاده نمیکند، تأخیر را کاهش میدهد.
- این کار با کاهش (یا حذف) مقدار دادههای غیرضروری که برنامه شما ممکن است بازیابی کند، استفاده از پهنای باند را کاهش میدهد.
با گذشت زمان، با افزودن بخشهای بیشتر توسط منابع، این مزایا افزایش مییابد زیرا برنامه شما ویژگیهای جدید معرفیشدهای را که پشتیبانی نمیکند درخواست نخواهد کرد.
نکات و روالهای مطلوب
ادعای مالکیت محتوا
اگر میخواهید درطول همهفرستیتان آگهی نشان دهید، باید پیشاز شروع رویداد، ویدیو همهفرستی را ادعای مالکیت کنید. برای ادعای مالکیت محتوا، باید شریک محتوای YouTube باشید که در برنامه Content ID شرکت میکند.
فرایند ادعای مالکیت ویدیو پخش زنده شما با فرایند عادی ادعای مالکیت ویدیو متفاوت است. هنگام ادعای مالکیت ویدیو زنده، باید ادعای خود را قبلاز اینکه ویدیو واقعاً وجود داشته باشد ایجاد کنید. این API از این ویژگی پشتیبانی میکند و سند چرخه عمر همهفرستی فراخوانیهای YouTube Content ID API را که به شما امکان میدهد ادعای خود را ایجاد کنید، توضیح میدهد.
پیشدید و آزمایش محتوا
پساز دریافت جاریسازی ویدیویی ورودی شما، YouTube میتواند آن ویدیو را در دو جاریسازی خروجی مختلف پخش کند:
-
جاریسازی پایش به شما امکان میدهد پخش ویدیویی خود را پیشنمایش (و آزمایش) کنید. این یک جاریسازی خصوصی است که فقط برای شما قابلدسترسی است. فقط درصورتی میتوانید همهفرستی را به مرحله
testingانتقال دهید که جاریسازی پایش همهفرستی فعال باشد. جاریسازی پایشگر وقفههای آگهی را نشان نمیدهد. -
جاریسازی همهفرستی جاریسازیای است که برای مخاطبان شما قابلمشاهده است. میتوانید وضعیت حریم خصوصی همهفرستی را روی
public،private، یاunlistedتنظیم کنید. (یک پخش خصوصی فقط برای کاربرانی قابل مشاهده است که صریحاً برای تماشای آن دعوت شدهاند، در حالی که یک پخش فهرستنشده برای هر کسی که پیوندی برای مشاهده آن داشته باشد قابل مشاهده است.)میتوانید انتخاب کنید که جاریسازی همهفرستی را بهتأخیر بیندازید تا بهطور همزمان با جاریسازی پایش اجرا نشود. با تأخیر در جاریسازی همهفرستی، میتوانید کنترل دقیقتری بر زمانی که نقاط نشان را در همهفرستی درج میکنید داشته باشید.
اما تأخیر در جاریسازی همهفرستی باعث میشود ارائهدهندگان زنده شما بهسختی بتوانند با مخاطبان بیننده تعامل برقرار کنند. علاوهبراین، تأخیر در پخش احتمال اینکه بینندگان جزئیات کلیدی رویداد را از منابعی غیراز پخش شما کشف کنند افزایش میدهد. برای مثال، اگر رویدادی ورزشی را با ۶۰ ثانیه تأخیر پخش میکنید، ممکن است بینندگان لحظات حساس رویداد را از منابع خبری همزمان دیگر قبلاز دیدن آنها در پخش شما متوجه شوند.
YouTube توصیه میکند که جاریسازی پایش را برای همهفرستی خود فعال کنید تا بتوانید محتوای خود را آزمایش کنید. باید انتخاب کنید که آیا میخواهید پخش خود را نیز به تأخیر بیندازید، براساس تمایل شما به کنترل زمانبندی نقاط نشانگر در مقابل تمایل شما به تعامل با مخاطبان یا ارائه پوشش همزمان از یک رویداد.
اجرای آگهیهای میانویدیویی درطول جاریسازی همهفرستی
درطول همهفرستی، میتوانید یک cuepoint درج کنید تا نشان دهید که وقفه آگهی باید در اسرع وقت یا در زمان مشخصی در همهفرستی شروع شود. وقفه آگهی به YouTube امکان میدهد آگهیهای میانویدیویی را درطول پخش اجرا کند.
وقفه آگهی دارای ویژگیهای زیر است:
-
این ویژگی دارای طول زمان ازپیشتعیینشدهای است که بااستفاده از دارایی
cuepointdurationSecsتنظیم میکنید. پساز پایان وقفه آگهی، بینندگان به پخش زنده برمیگردند. -
وقتی وقفه آگهی اتفاق میافتد، آگهی فقط در پخشکننده ویدیو برای بینندگانی پخش میشود که درحال تماشای پخش همزمان در زمان درج نقطه نشانگر هستند. وقتی بینندگان صفحهای را که پخش در آن درحال اجرا است بازآوری میکنند یا وقتی بازدیدکنندگان پساز درج نقطه راهنما شروع به تماشای پخش میکنند، آگهی اجرا نمیشود.
ترتیب مراحل زیر نشاندهنده بهترین روش برای درج وقفه آگهی درطول پخش شما است:
تنظیم کردن اختلاف زمانی
هنگام درج نقطه اشاره، میتوانید مشخص کنید که باید بلافاصله درج شود یا در نقطه خاصی از همهفرستی درج شود. گزینههای شما به این بستگی دارد که آیا جاریسازی همهفرستی برای ویدیو شما تأخیر دارد یا نه.
-
اگر جاریسازی همهفرستی شما تأخیر ندارد، میتوانید نقطه نشان را فوراً درج کنید یا از ویژگی
walltimeMsاستفاده کنید تا وقفه آگهی در زمان خاصی شروع شود.-
برای شروع فوری وقفه آگهی، روش
liveBroadcasts.cuepointرا فراخوانی کنید. در منبع در بدنه درخواست، مقدار داراییinsertionOffsetTimeMsرا روی0تنظیم کنید یا مقداری برای آن دارایی مشخص نکنید و مقداری برای داراییwalltimeMsمشخص نکنید.مهم: توجه داشته باشید که بینندگان محتوای آگهی حاصل را بلافاصله نمیبینند. ممکن است حدود ۳۰ ثانیه طول بکشد تا محتوای آگهی برای کاربران نمایان شود. درطول این تأخیر، جاریسازی همهفرستی شما همچنان برای بینندگان شما قابلمشاهده خواهد بود و شما باید جاریسازی همهفرستی را تماشا کنید تا تعیین کنید محتوای آگهی چه زمانی بهجای جاریسازی مانیتور شما نمایش داده میشود.
-
برای شروع وقفه آگهی در زمانی خاص، روش
liveBroadcasts.cuepointرا فراخوانی کنید و از ویژگیwalltimeMsبرای مشخص کردن زمان موردنظر استفاده کنید. مقدار دارایی عدد صحیحی است که نشاندهنده مُهر زمان دوره است.
-
-
اگر جاریسازی همهفرستی شما با تأخیر مواجه است، میتوانید نقطه اشاره را بلافاصله همانطور که در بالا توضیح داده شد درج کنید، زمان ساعت را همانطور که در بالا توضیح داده شد مشخص کنید، یا میتوانید یک انحراف زمانی را برای تعیین زمان شروع وقفه آگهی مشخص کنید. انحراف زمان نقطهای را در همهفرستی شما مشخص میکند که بینندگان باید آگهی را ببینند.
مقدار آفست برحسب میلیثانیه از ابتدای جریان مانیتور برای پخش شما اندازهگیری میشود. توجه داشته باشید که اگر پخش شما دارای فاز آزمایشی باشد، جاریسازی مانیتور زمانی شروع میشود که پخش شما به وضعیت
testingمنتقل شود. درغیراینصورت، جاریسازی مانیتور شما زمانی شروع میشود که همهفرستی شما به وضعیتliveتغییر کند.هنگام درج نقطه نشانه، ویژگی
insertionOffsetTimeMsمنبعcuepointرا روی افست موردنظر تنظیم کنید.
محاسبه مقدار انحراف زمانی
برای بازیابی مقدار آفست، تابع getCurrentTime YouTube Player API را برای پخشکنندهای که درحال پخش جریان مانیتور است فراخوانی کنید. از مقدار بازیابیشده برای درج نقطه نشانه در جریان همهفرستی در آن زمان استفاده کنید.
مقادیر ممکن برای زمان انحراف را میتوان بهصورت محدوده زیر محاسبه کرد:
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
Δ یک بافر پنج ثانیهای در ابتدا و انتهای افستهای زمانی ممکن است که YouTube نتواند یک نقطه نشانه را بهطور دقیق درج کند. برای مثال:
- همهفرستی یک مرحله آزمایشی پنج دقیقهای دارد.
- جاریسازی همهفرستی ۶۰ ثانیه بعداز جاریسازی پایشگر بهتأخیر میافتد.
- فرستنده نقطه نشان را چهار دقیقه پساز انتقال همهفرستی به وضعیت
liveدرج میکند. (این سه دقیقه پساز نمایان شدن جاریسازی همهفرستی است.)
دراینصورت، محدوده احتمالی زمانهای جابهجایی [(485,000), (535,000)] است.
این زمانها برحسب میلیثانیه مشخص میشوند و بااستفاده از مقادیر زیر محاسبه میشوند:
elapsed_time=540000– وقتی روشliveBroadcasts.cuepointفراخوانی میشود، جاریسازی پایشگر بهمدت نه دقیقه (۵۴۰ ثانیه، ۵۴۰۰۰۰ میلیثانیه) اجرا شده است.broadcast_delay=60000– جاریسازی همهفرستی ۶۰ ثانیه یا ۶۰۰۰۰ میلیثانیه تأخیر دارد.Δ=5000– میانگیر پنج ثانیهای زمانی که نقطه نشانه نمیتواند بهطور مطمئن درج شود.
عیبیابی و مدیریت خطا
دستورالعملهای زیر نحوه حل مشکلات خاصی را که ممکن است پیش بیاید توضیح میدهند. برای فهرست خطاهایی که هر روش API ممکن است برگرداند، به API جاریسازی زنده YouTube - خطاها مراجعه کنید.
-
وقتی یک پخش از یک وضعیت به وضعیت دیگر منتقل میشود، ممکن است بهطور موقت وضعیت دیگری به آن اختصاص داده شود تا زمانی که YouTube اقدامات مربوط به انتقال را تکمیل کند. برای مثال، اگر درخواست
liveBroadcasts.transitionرا برای تغییر وضعیت پخش ازreadyبهtestingارسال کنید، YouTube وضعیت پخش را رویtestStartingتنظیم میکند و سپس اقدامات مرتبط با تغییر وضعیت را تکمیل میکند. وقتی همه آن اقدامات تکمیل شد، YouTube وضعیت همهفرستی را بهtestingبهروز میکند و بدین ترتیب نشان میدهد که انتقال کامل شده است.اگر یک همهفرستی با وضعیت
testStartingیاliveStartingگیر کرد، باید روشliveBroadcasts.deleteرا فراخوانی کنید و همهفرستی را حذف کنید. سپس یک پخش جدید ایجاد کنید، آن را به جاریسازی زنده خود متصل کنید و فرایند آزمایش را ادامه دهید.همانطور که در مستندات روش
liveBroadcasts.transitionذکر شده است، قبلاز فراخوانی آن روش، باید تأیید کنید که مقدار داراییstatus.streamStatusبرای جاریسازی پیوندشده به همهفرستی شماactiveاست.