YouTube Live Streaming API به شما امکان می‌دهد رویدادهای زنده را در YouTube ایجاد، به‌روزرسانی و مدیریت کنید. با استفاده از API، می‌توانید رویدادها (پخش‌ها) را زمان‌بندی کنید و آنها را با جریان‌های ویدیویی مرتبط کنید، که نشان‌دهنده محتوای پخش واقعی است.
Live Streaming API در واقع از اجزای YouTube Data API و YouTube Content ID API تشکیل شده است. Data API به کاربران YouTube امکان می دهد حساب های YouTube خود را مدیریت کنند، در حالی که YouTube Content ID API تعامل با سیستم مدیریت حقوق YouTube را امکان پذیر می کند. با این حال، تمام منابعی که Live Streaming API را تشکیل می‌دهند، فقط برای ایجاد و مدیریت رویدادهای زنده استفاده می‌شوند.
این سند برای توسعه دهندگانی در نظر گرفته شده است که می خواهند برنامه هایی را برای تسهیل پخش زنده در YouTube بنویسند. مفاهیم اساسی YouTube و خود API را توضیح می دهد. همچنین یک نمای کلی از عملکردهای مختلفی که API پشتیبانی می کند ارائه می دهد.
مفاهیم اصلی
- پخش می کند
- پخش رویدادی را نشان می‌دهد که می‌توان آن را در YouTube تماشا کرد. پخش‌ها همچنین می‌توانند به‌عنوان ویدیوهای YouTube ضبط و ذخیره شوند تا کاربران بتوانند پس از وقوع آنها را تماشا کنند.
- جریان ها
- یک جریان، محتوای صوتی-تصویری را که به YouTube منتقل می‌شود، شناسایی می‌کند. هر پخش با یک جریان ویدئو همراه است.
- نقاط نشانه
- نقطه نشانه نشان دهنده یک وقفه تبلیغاتی است که می تواند در پخش زنده درج شود.
موارد استفاده API
لیست زیر چندین روش برای استفاده از API در برنامه شما پیشنهاد می کند:
برنامه ریزی پخش و تعریف تنظیمات پخش. برنامه شما می تواند به کاربران امکان دهد تنظیمات پخش را از پیش تعریف کنند و سپس تنظیماتی را برای اعمال در یک پخش خاص انتخاب کنند.
جریان‌ها و پخش‌های ویدیویی را مرتبط کنید.
پخش‌کنندگان را فعال کنید تا اطلاعات مربوط به پخش و ویدیوی آن را (با استفاده از YouTube Data API ) به طور همزمان تعریف کنند.
انتقال بین حالت های پخش (
testing،live، و غیره) را ساده کنید و کاربران را قادر به درج نقطه نشانه کنید.
قبل از اینکه تو شروع کنی
برای دسترسی به Google API Console ، درخواست کلید API و ثبت برنامه خود، به یک حساب Google نیاز دارید.
برنامه خود را در گوگل ثبت کنید تا بتواند درخواست های API را ارسال کند.
پس از ثبت برنامه، YouTube Data API به عنوان یکی از خدماتی که برنامه شما از آن استفاده می کند، انتخاب کنید:
- به API Console بروید و پروژه ای را که به تازگی ثبت کرده اید انتخاب کنید.
- از صفحه Enabled APIs دیدن کنید. در فهرست APIها، مطمئن شوید وضعیت برای YouTube Data API نسخه 3 و اگر شریک محتوای YouTube هستید، API Content ID YouTube روشن است.
با مفاهیم اصلی قالب داده JSON (جاوا اسکریپت Object Notation) آشنا شوید. JSON یک فرمت داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.
مجوز درخواست های API
همانطور که در بالا ذکر شد، 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 | نشان دهنده یک ویدیوی یوتیوب است. همانطور که در بالا ذکر شد، یک منبع liveBroadcast توسعه یک منبع video است. می‌توانید از YouTube Data API برای به‌روزرسانی فراداده‌های مربوط به ویدیو، مانند مکان ضبط یا مناطقی که پخش قابل مشاهده است، استفاده کنید. |
videoAdvertisingOptions | تنظیمات تبلیغات را برای یک ویدیو (یا پخش) تعریف می کند. برای تنظیم گزینه‌های تبلیغاتی از YouTube Content ID API استفاده می‌کنید. |
asset | نمایانگر بخشی از مالکیت معنوی، مانند یک فیلم یا قسمتی از یک نمایش است. در این حالت، ویدیوی پخش شده دارایی است. برای ایجاد و مدیریت منابع asset از YouTube Content ID API استفاده خواهید کرد. |
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 | |
| پخش زنده | |||||||
| پخش زنده |
منابع جزئی
API اجازه می دهد و در واقع به بازیابی منابع جزئی نیاز دارد تا برنامه ها از انتقال، تجزیه و ذخیره داده های غیر ضروری جلوگیری کنند. این رویکرد همچنین تضمین می کند که API از منابع شبکه، CPU و حافظه به طور موثرتری استفاده می کند.
پارامتر part یک پارامتر ضروری برای هر درخواست API است که منبع YouTube Data API را بازیابی یا برمی گرداند. این پارامتر یک یا چند ویژگی منبع سطح بالا (غیر تودرتو) را که باید در یک پاسخ API گنجانده شوند، شناسایی می کند. به عنوان مثال، یک منبع liveStream دارای بخش های زیر است:
-
snippet -
cdn -
status
همه این بخش‌ها اشیایی هستند که دارای ویژگی‌های تودرتو هستند، و می‌توانید این اشیاء را به عنوان گروه‌هایی از فیلدهای ابرداده در نظر بگیرید که سرور API ممکن است (یا نه) آنها را بازیابی کند. به این ترتیب، پارامتر part از شما می‌خواهد که مؤلفه‌های منبعی را انتخاب کنید که برنامه شما واقعاً از آنها استفاده می‌کند. این الزام دو هدف مهم را دنبال می کند:
- با جلوگیری از صرف زمان سرور API برای بازیابی فیلدهای ابرداده ای که برنامه شما از آنها استفاده نمی کند، تأخیر را کاهش می دهد.
- با کاهش (یا حذف) مقدار داده های غیر ضروری که برنامه شما ممکن است بازیابی کند، استفاده از پهنای باند را کاهش می دهد.
با گذشت زمان، همانطور که منابع بخش‌های بیشتری را اضافه می‌کنند، این مزایا فقط افزایش می‌یابد زیرا برنامه شما ویژگی‌های تازه معرفی‌شده‌ای را که پشتیبانی نمی‌کند درخواست نمی‌کند.
نکات و بهترین شیوه ها
مطالب خود را ادعا کنید
اگر می‌خواهید در طول پخش خود تبلیغات نشان دهید، باید قبل از شروع رویداد، ویدیوی پخش را ادعا کنید. برای ادعای محتوا، باید شریک محتوای YouTube شرکت کننده در برنامه Content ID باشید.
روند ادعای ادعای ویدیوی پخش زنده شما با روند عادی ادعای یک ویدیو متفاوت است. هنگام ادعای ویدیوی زنده، باید قبل از اینکه ویدیو واقعاً وجود داشته باشد، ادعای خود را ایجاد کنید. API از این پشتیبانی می‌کند، و عمر یک سند پخش ، فراخوان‌های YouTube Content ID API را توضیح می‌دهد که به شما امکان می‌دهد ادعای خود را ایجاد کنید.
محتوای خود را پیش نمایش و آزمایش کنید
پس از دریافت جریان ویدیوی ورودی، YouTube می‌تواند آن ویدیو را در دو جریان خروجی مختلف پخش کند:
جریان مانیتور به شما امکان می دهد پخش ویدیوی خود را پیش نمایش (و آزمایش) کنید. این یک جریان خصوصی است که فقط برای شما قابل دسترسی است. تنها در صورتی می‌توانید یک پخش را به مرحله
testingانتقال دهید که جریان مانیتور پخش فعال باشد. جریان مانیتور وقفه های تبلیغاتی را نشان نمی دهد.جریان پخش جریانی است که برای مخاطبان شما قابل مشاهده است. می‌توانید وضعیت حریم خصوصی پخش را روی
public،privateیاunlistedتنظیم کنید. (پخش خصوصی فقط برای کاربرانی قابل مشاهده است که صریحاً برای تماشای آن دعوت شده اند، در حالی که پخش فهرست نشده برای هر کسی که پیوندی برای مشاهده آن داشته باشد قابل مشاهده است.)می‌توانید پخش جریانی را به تأخیر بیندازید تا همزمان با جریان مانیتور اجرا نشود. با تأخیر در پخش جریانی، می‌توانید کنترل دقیق‌تری بر زمانی که نقاط نشانه را در پخش قرار می‌دهید داشته باشید.
با این حال، تاخیر در پخش جریانی، تعامل مجریان زنده شما با مخاطبان بیننده شما را دشوار می کند. به علاوه، تأخیر در پخش، احتمال اینکه بینندگان جزئیات اصلی رویداد را از منابعی غیر از پخش شما کشف کنند، افزایش می‌دهد. به عنوان مثال، اگر یک رویداد ورزشی را با تاخیر 60 ثانیه پخش می کنید، بینندگان ممکن است قبل از اینکه واقعاً آنها را در پخش ببینند، در مورد لحظات حساس رویداد از سایر منابع خبری بیدرنگ مطلع شوند.
یوتیوب توصیه می کند که جریان مانیتور را برای پخش خود فعال کنید تا بتوانید محتوای خود را آزمایش کنید. شما باید انتخاب کنید که آیا پخش خود را نیز بر اساس تمایل خود به کنترل زمان بندی نقاط نشانه به تعویق بیندازید، در مقابل تمایل شما به تعامل با مخاطبان یا ارائه پوشش بلادرنگ یک رویداد.
اجرای تبلیغات میان‌روی در طول پخش جریانی
در طول پخش، می‌توانید یک نقطه نشانه وارد کنید تا نشان دهد که یک وقفه تبلیغاتی باید در اسرع وقت یا در زمان مشخصی در پخش شروع شود. وقفه تبلیغاتی به YouTube امکان می‌دهد تا تبلیغات میان‌افزاری را در طول پخش اجرا کند.
وقفه های تبلیغاتی دارای ویژگی های زیر هستند:
این یک مدت زمان از پیش تعریف شده دارد که با استفاده از ویژگی
durationSecsمنبعcuepointتنظیم می کنید. پس از پایان وقفه تبلیغاتی، بینندگان به پخش زنده باز می گردند.وقتی یک وقفه تبلیغاتی اتفاق می‌افتد، یک آگهی فقط در پخش‌کننده ویدیو برای بینندگانی پخش می‌شود که وقتی نقطه نشانه درج می‌شود، پخش را تماشا می‌کنند. هنگامی که بینندگان صفحه ای را که در آن پخش پخش می شود بازخوانی می کنند یا هنگامی که بازدیدکنندگان پس از درج نقطه نشانه شروع به تماشای پخش می کنند، تبلیغ اجرا نمی شود.
دنباله مراحل زیر بهترین روش برای درج وقفه تبلیغاتی در طول پخش شما را نشان می دهد:
تعدیل زمان را تنظیم کنید
هنگام درج نقطه نشانه، می توانید مشخص کنید که باید فوراً درج شود یا در نقطه خاصی از پخش درج شود. گزینه‌های شما به تأخیر پخش جریانی ویدیوی شما بستگی دارد.
اگر پخش جریانی شما تأخیر نداشته باشد، می‌توانید فوراً نقطه نشانه را وارد کنید یا از ویژگی
walltimeMsاستفاده کنید تا وقفه آگهی در زمان خاصی شروع شود.- برای شروع فورا وقفه تبلیغاتی، با روش
liveBroadcasts.cuepointتماس بگیرید. در منبع موجود در بدنه درخواست، مقدار ویژگیinsertionOffsetTimeMsرا روی0قرار دهید یا مقداری برای آن ویژگی و مقداری برای ویژگیwalltimeMsتعیین نکنید.مهم: توجه داشته باشید که بینندگان محتوای تبلیغاتی را بلافاصله نمی بینند. ممکن است حدود 30 ثانیه تأخیر وجود داشته باشد تا محتوای تبلیغ برای کاربران قابل مشاهده باشد. در طول آن تأخیر، جریان پخش شما همچنان برای بینندگان شما قابل مشاهده خواهد بود، و شما باید جریان پخش را تماشا کنید تا مشخص کنید محتوای تبلیغات واقعاً چه زمانی به جای جریان مانیتور شما نمایش داده می‌شود.
برای شروع وقفه تبلیغاتی در یک زمان خاص، روش
liveBroadcasts.cuepointرا فراخوانی کنید و از ویژگیwalltimeMsبرای تعیین زمان مورد نظر استفاده کنید. مقدار ویژگی یک عدد صحیح است که نشان دهنده یک مهر زمانی است.
- برای شروع فورا وقفه تبلیغاتی، با روش
اگر پخش جریانی شما تأخیر داشته باشد، می‌توانید فوراً نقطه نشانه را همانطور که در بالا توضیح داده شد وارد کنید، زمان ساعت را همانطور که در بالا توضیح داده شد مشخص کنید، یا می‌توانید یک تغییر زمانی برای تعیین زمان شروع وقفه تبلیغاتی تعیین کنید. افست زمان نقطه ای را در پخش شما مشخص می کند که بینندگان باید آگهی را ببینند.
مقدار افست از ابتدای پخش جریان مانیتور برای پخش شما بر حسب میلی ثانیه اندازه گیری می شود. توجه داشته باشید که اگر پخش شما مرحله آزمایشی داشته باشد، پس از انتقال پخش شما به وضعیت
testing، جریان مانیتور شروع می شود. در غیر این صورت، پخش جریانی مانیتور شما زمانی شروع می شود که پخش شما به وضعیتliveتبدیل شود.هنگام درج نقطه نشانه، ویژگی
insertionOffsetTimeMsمنبعcuepointرا روی افست مورد نظر تنظیم کنید.
مقدار افست زمان را محاسبه کنید
برای بازیابی مقدار افست، تابع getCurrentTime API YouTube Player را برای پخش کننده ای که جریان مانیتور را پخش می کند تماس بگیرید. از مقدار بازیابی شده برای درج نقطه نشانه در جریان پخش در آن زمان استفاده کنید.
مقادیر ممکن برای زمان افست را می توان به صورت محدوده زیر محاسبه کرد:
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
Δ یک بافر پنج ثانیه‌ای در ابتدا و انتهای زمان‌هایی است که یوتیوب نمی‌تواند دقیقاً نقطه نشانه را وارد کند. مثلا:
- یک پخش یک مرحله آزمایشی پنج دقیقه ای دارد.
- پخش جریانی 60 ثانیه پس از پخش جریان مانیتور به تاخیر می افتد.
- پخش کننده در حال وارد کردن نقطه نشانه چهار دقیقه پس از انتقال پخش به وضعیت
liveاست. (این سه دقیقه پس از نمایان شدن جریان پخش است.)
در این مورد، محدوده احتمالی زمان های افست [(485,000), (535,000)] است.
این زمان ها بر حسب میلی ثانیه مشخص می شوند و با استفاده از مقادیر زیر محاسبه می شوند:
-
elapsed_time=540000– هنگامی که روشliveBroadcasts.cuepointفراخوانی می شود، جریان مانیتور به مدت نه دقیقه (540 ثانیه، 540000 میلی ثانیه) اجرا می شود. -
broadcast_delay=60000– پخش جریانی با 60 ثانیه یا 60000 میلی ثانیه تاخیر دارد. -
Δ=5000– بافر پنج ثانیه ای زمانی که نقطه نشانه به طور قابل اعتمادی درج نمی شود.
عیب یابی و رسیدگی به خطاها
دستورالعمل های زیر نحوه حل مشکلات خاصی را که ممکن است ایجاد شود توضیح می دهد. همچنین برای لیست خطاهایی که هر روش API ممکن است برگرداند، به مستندات خطا مراجعه کنید.
هنگامی که یک پخش از یک وضعیت به وضعیت دیگر منتقل می شود، ممکن است به طور موقت به وضعیت دیگری اختصاص داده شود در حالی که YouTube اقدامات مرتبط با انتقال را تکمیل می کند. برای مثال، اگر یک درخواست
liveBroadcasts.transitionبرای تغییر وضعیت پخش ازreadyبهtestingارسال کنید، YouTube وضعیت پخش را رویtestStartingتنظیم می‌کند و سپس اقدامات مرتبط با تغییر وضعیت را تکمیل می‌کند. وقتی همه این اقدامات تکمیل شد، YouTube وضعیت پخش را بهtestingبه‌روزرسانی می‌کند و بدین ترتیب نشان می‌دهد که انتقال کامل شده است.اگر پخش با وضعیت
testStartingیاliveStartingگیر کرد، باید با روشliveBroadcasts.deleteتماس بگیرید و پخش را حذف کنید. سپس یک پخش جدید ایجاد کنید، آن را به پخش زنده خود متصل کنید و به روند آزمایش ادامه دهید.همانطور که در مستندات روش
liveBroadcasts.transitionذکر شده است، قبل از فراخوانی آن متد باید تأیید کنید که مقدار ویژگیstatus.streamStatusبرای جریان محدود شده به پخش شماactiveاست.