סקירה כללית על YouTube Live Streaming API

ממשק ה-API לסטרימינג בשידור חי של YouTube מאפשר ליצור, לעדכן ולנהל אירועים בשידור חי ב-YouTube. באמצעות ה-API ניתן לתזמן אירועים (שידורים) ולשייך אותם לזרמי וידאו שמייצגים את תוכן השידור עצמו.

ממשק ה-API של הסטרימינג בשידור חי מורכב למעשה מרכיבים של ממשק ה-API של נתונים של YouTube ושל ממשק ה-API של Content ID ב-YouTube. ממשק Data API מאפשר למשתמשי YouTube לנהל את חשבונות YouTube שלהם, ו-YouTube Content ID API מאפשר אינטראקציה עם מערכת ניהול הזכויות של YouTube. עם זאת, כל המשאבים שמרכיבים את ממשק ה-API של סטרימינג בשידור חי משמשים אך ורק ליצירה ולניהול של אירועים בשידור חי.

מסמך זה מיועד למפתחים שרוצים לכתוב אפליקציות שיקלו על שידור חי ב-YouTube. המאמר מסביר את המושגים הבסיסיים של YouTube ושל ממשק ה-API עצמו. יש כאן גם סקירה כללית של הפונקציות השונות שנתמכות ב-API.

מושגים בסיסיים

שידורים

שידור מייצג אירוע שאפשר לצפות בו ב-YouTube בזמן שהוא מתרחש. ניתן גם להקליט ולשמור את השידורים כסרטוני YouTube, כדי שמשתמשים יוכלו לצפות בהם לאחר מכן.

זרמים

סטרימינג הוא מזהה של תוכן וידאו האודיו שמועבר אל YouTube. כל שידור משויך לזרם וידאו אחד.

נקודות סימון

נקודת סימון מייצגת הפסקה למודעה שניתן להוסיף לשידור חי.

תרחישים לדוגמה ל-API

הרשימה הבאה מציעה מספר דרכים לשימוש ב-API באפליקציה שלכם:

• תזמון שידורים וקביעת הגדרות שידור. האפליקציה שלך יכולה לאפשר למשתמשים להגדיר מראש הגדרות שידור, ולאחר מכן לבחור את ההגדרות שיחולו על שידור מסוים.

• שיוך שידורי וידאו ושידורים חיים.

• תוכלו לאפשר לשדרנים להגדיר פרטים לגבי שידור מסוים ולגבי הסרטון שלו (באמצעות YouTube Data API) בו-זמנית.

• פשט את המעברים בין מצבי השידור (testing, live וכו') ואפשר למשתמשים להוסיף נקודות עצירה (Ccuepoints).

לפני שמתחילים

1. נדרש חשבון Google כדי לגשת ל-Google API Console, לבקש מפתח API ולרשום את האפליקציה.

2. יש לרשום את הבקשה ב-Google כדי שהיא תוכל לשלוח בקשות API.

3. לאחר רישום הבקשה, צריך לבחור ב-YouTube Data API כאחד מהשירותים שבהם האפליקציה משתמשת:

   1. צריך לעבור אל API Console ולבחור את הפרויקט שרשמת כרגע.
   2. נכנסים לדף של ממשקי ה-API שמופעלים. ברשימת ממשקי ה-API, מוודאים שהסטטוס של YouTube Data API v3 הוא ON. אם אתם שותפי תוכן של YouTube, עליכם לוודא שממשק ה-API של YouTube Content ID API.

4. להכיר את המושגים הבסיסיים של פורמט הנתונים JSON (JavaScript Object Notation). JSON הוא פורמט נתונים נפוץ ובלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף: json.org.

הרשאת בקשות API

כפי שצוין קודם לכן, 'ממשק API לסטרימינג בשידור חי' משתמש בפונקציונליות שהיא חלק מבחינה טכנית מה-YouTube Data API או מה-YouTube Content ID API. תוכלו להשתמש בממשק ה-API של Content ID כדי לספק ל-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 יש אותו מזהה. אחרי יצירת השידור באמצעות ממשק ה-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 כולל את החלקים הבאים:

• snippet
• cdn
• status

כל החלקים האלה הם אובייקטים שמכילים מאפיינים מקוננים, ורואים את האובייקטים האלה כקבוצות של שדות מטא-נתונים ששרת ה-API עשוי לאחזר (או לא יכול). לכן, כדי להשתמש בפרמטר part צריך לבחור את רכיבי המשאבים שבהם האפליקציה משתמשת בפועל. דרישה זו משרתת שתי מטרות חשובות:

• התכונה הזו מפחיתה את זמן האחזור בכך שהיא מונעת משרת ה-API לבזבז זמן באחזור שדות מטא-נתונים שהאפליקציה שלך לא משתמשת בהם.
• הוא מפחית את השימוש ברוחב הפס על ידי הפחתה (או ביטול) של כמות הנתונים המיותרים שהיישום שלך עשוי לאחזר.

עם הזמן, ככל שהמשאבים מתווספים, כך היתרונות האלה רק גדלים, מאחר שהאפליקציה לא תבקש נכסים חדשים שהיא לא תומכת בהם.

טיפים ושיטות מומלצות

הצהרה על זכויות יוצרים בתוכן

אם ברצונך להציג מודעות במהלך השידור, עליך לתבוע בעלות על סרטון השידור לפני תחילת האירוע. כדי לשלוח תלונה על הפרת זכויות יוצרים בתוכן, עליכם להיות שותפי תוכן של YouTube שמשתתפים בתוכנית Content ID.

תהליך תביעת הבעלות על סרטון משידור חי שונה מהתהליך הרגיל של הצהרה על זכויות יוצרים בסרטון. בעת הצהרה על זכויות יוצרים בסרטון בשידור חי, עליכם ליצור הצהרה על זכויות יוצרים לפני שהסרטון קיים בפועל. ה-API תומך בכך, והמסמך חיי השידור מסביר את הקריאות ל-YouTube Content ID API שמאפשרות ליצור את הטענה שלכם.

תצוגה מקדימה ובדיקה של התוכן

לאחר קבלת זרם הווידאו הנכנס, YouTube יוכל לשדר את הסרטון בשני שידורים יוצאים שונים:

• המעקב אחרי השידור מאפשר לכם לצפות בתצוגה מקדימה של שידור הווידאו (ולבדוק אותו). זהו שידור פרטי שנגיש רק לכם. אפשר להעביר שידור לשלב testing רק אם השידור המוניטור מופעל. בשידור המעקב לא מוצגות הפסקות למודעות.

• השידור החי הוא הסטרימינג שגלוי לקהל שלכם. אפשר להגדיר את סטטוס הפרטיות של השידור ל-public, ל-private או ל-unlisted. (שידור פרטי גלוי רק למשתמשים שהוזמנו במפורש לצפות בו, בעוד ששידור לא רשום גלוי לכל מי שיש לו קישור לצפות בו).

  אפשר לבחור לעכב את השידור, כך שלא יופעל בו-זמנית עם זרם המעקב. על ידי השהיית זרם השידור, אתה יכול לקבל שליטה מדויקת יותר על הזמן שבו אתה מכניס נקודות עצירה לשידור.

  עם זאת, השהיה של השידור החי עשויה להקשות על מי שצופה בשידור החי ליצור אינטראקציה עם הצופים. בנוסף, השהיית השידור מעלה את הסבירות שצופים יגלו פרטים חשובים לגבי האירוע ממקורות אחרים שאינם השידור שלך. לדוגמה, אם אתם משדרים אירוע ספורט בהשהיה של 60 שניות, הצופים עשויים לקבל מידע על רגעים קריטיים באירוע ממקורות חדשותיים אחרים בזמן אמת לפני שהם יראו אותם בשידור.

YouTube ממליץ להפעיל את זרם המעקב עבור השידור שלך כדי שתוכל לבדוק את התוכן שלך. עליך לבחור אם להשהות את השידור גם בהתבסס על הרצון שלך לשלוט בתזמון של נקודות הרמז, ולא ברצון שלך לקיים אינטראקציה עם הקהל או לספק כיסוי בזמן אמת של אירוע.

הצגת מודעות באמצע הסרטון (mid-roll) במהלך שידור חי

במהלך שידור, אפשר להוסיף נקודת סימון כדי לציין שההפסקה למודעה צריכה להתחיל בשידור בהקדם האפשרי או במועד ספציפי. ההפסקה למודעות מאפשרת ל-YouTube להציג מודעות באמצע הסרטון במהלך השידור.

להפסקות למודעות יש את המאפיינים הבאים:

1. יש לו משך זמן מוגדר מראש, שאותו מגדירים באמצעות המאפיין durationSecs של המשאב cuepoint. כשההפסקה למודעה מסתיימת, הצופים חוזרים לשידור החי.

2. כשמתרחשת הפסקה למודעה, מודעה מופעלת בנגן הווידאו רק עבור צופים שצופים בשידור לאחר הכנסת נקודת ה-Cuepoint. מודעה לא מוצגת כשהצופים מרעננים את הדף שבו מופעל השידור, או כשמבקרים מתחילים לצפות בשידור לאחר הכנסת נקודת ה-Cuepoint.

רצף השלבים הבאים משקף את השיטה המומלצת להוספת הפסקה למודעה במהלך השידור:

הגדרת הפרשי זמן

בעת הכנסת נקודת רמז, ניתן לציין שהיא תוכנס מיד או שיש להכניס אותה בנקודה ספציפית בשידור. האפשרויות שעומדות לרשותך משתנות אם השידור של הסרטון מתעכב.

• אם השידור החי שלך לא מתעכב, אפשר להוסיף את נקודת העצירה מיד או להשתמש בנכס walltimeMs כדי שההפסקה למודעות תתחיל בזמן מסוים.

  • כדי להתחיל את ההפסקה למודעה מיד, צריך להפעיל את השיטה liveBroadcasts.cuepoint. במשאב בגוף הבקשה, מגדירים את הערך של המאפיין insertionOffsetTimeMs ל-0, או לא מציינים ערך לנכס הזה ולא מציינים ערך עבור המאפיין walltimeMs.

    חשוב: לתשומת ליבכם: הצופים לא רואים את תוכן המודעה שמתקבל באופן מיידי. ייתכן עיכוב של כ-30 שניות עד שתוכן המודעה יהיה גלוי למשתמשים. במהלך העיכוב הזה, השידור עדיין יהיה גלוי לצופים שלך, ועליך לצפות בשידור כדי לקבוע מתי תוכן המודעה יוצג בפועל במקום השידור למעקב.

  • כדי להתחיל את ההפסקה למודעה במועד מסוים, צריך לקרוא לשיטה liveBroadcasts.cuepoint ולהשתמש במאפיין walltimeMs כדי לציין את השעה הרצויה. ערך המאפיין הוא מספר שלם שמייצג חותמת זמן של תקופה של זמן מערכת.

• אם השידור החי שלך מתעכב, אפשר להוסיף את נקודת הסימון מיד כפי שמתואר למעלה, לציין את שעת השעון כפי שמתואר למעלה או לציין קיזוז זמן כדי לקבוע מתי ההפסקה למודעות תתחיל. קיזוז הזמן מציין נקודה בשידור שבה הצופים אמורים לראות מודעה.

  ערך ההיסט נמדד באלפיות שנייה מתחילת השידור של הצג עבור השידור שלך. חשוב לשים לב שאם בשידור יש שלב בדיקה, השידור של המוניטור יתחיל כשהשידור שלך יעבור לסטטוס testing. אחרת, השידור של הצג יתחיל כשהשידור שלך יעבור לסטטוס live.

  כשמוסיפים נקודת סימון, צריך להגדיר את המאפיין insertionOffsetTimeMs של המשאב cuepoint בהתאם לקיזוז הרצוי.

חשבו את ערך ההיסט הזמן

כדי לאחזר את ערך ההיסט, צריך לקרוא לפונקציה getCurrentTime של ממשק ה-API של נגן YouTube עבור הנגן שמפעיל את השידור המוניטור. אפשר להשתמש בערך שאוחזר כדי להוסיף את נקודת הרמז לשידור בזמן אמת.

את הערכים האפשריים לזמן ההיסט ניתן לחשב כטווח הבא:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ הוא מאגר של חמש שניות בתחילת הזמן הקצוב לתפוגה האפשרי ובסיום פרק הזמן האפשרי, כשמערכת YouTube לא יכולה להוסיף נקודת ציון באופן מדויק. לדוגמה:

• בשידור יש שלב בדיקה באורך חמש דקות.
• השידור מתעכב 60 שניות אחרי השידור בצג.
• השדרן מוסיף את נקודת הסימון ארבע דקות אחרי המעבר לסטטוס live. (שלוש דקות לאחר ששידור השידור הופך לגלוי.)

במקרה הזה, הטווח האפשרי של זמני ההיסט הוא [(485,000), (535,000)].

המועדים האלה מצוינים באלפיות שנייה ומחושבים לפי הערכים הבאים:

• elapsed_time=540000 – השידור של הצג פעל במשך תשע דקות (540 שניות, 540,000 אלפיות השנייה) כשמתבצעת קריאה ל-method liveBroadcasts.cuepoint.
• broadcast_delay=60000 – שידור השידור בהשהיה של 60 שניות, או 60,000 אלפיות השנייה.
• Δ=5000 – מאגר הנתונים הזמני של חמש השניות שבהן לא ניתן להכניס את נקודת הסימן בצורה אמינה.

פתרון בעיות וטיפול בשגיאות

ההנחיות הבאות מסבירות איך לפתור בעיות ספציפיות שעלולות להתעורר. מומלץ גם לעיין בתיעוד השגיאות כדי לראות רשימות של שגיאות שכל שיטת API עשויה להחזיר.

• כששידור עובר מסטטוס אחד לאחר, יכול להיות שהוא יוקצה באופן זמני לסטטוס אחר בזמן שהמערכת של YouTube משלים את הפעולות שקשורות למעבר. לדוגמה, אם תשלחו בקשת liveBroadcasts.transition לשינוי הסטטוס של שידור מסוים מready לtesting, המערכת של YouTube תגדיר את סטטוס השידור ל-testStarting ואז תבצע את הפעולות שקשורות לשינוי הסטטוס. לאחר שכל הפעולות האלה יושלמו, YouTube יעדכן את סטטוס השידור לtesting, ויציין שהמעבר הושלם.

  אם שידור נתקע בסטטוס testStarting או liveStarting, עליך להפעיל את השיטה liveBroadcasts.delete ולמחוק את השידור. לאחר מכן אפשר ליצור שידור חדש, לקשר אותו לשידור החי ולהמשיך בתהליך הבדיקה.

  כפי שצוין בתיעוד של השיטה liveBroadcasts.transition, עליך לוודא שהערך של המאפיין status.streamStatus עבור הזרם המשויך לשידור שלך הוא active לפני הקריאה לשיטה הזו.