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

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

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

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

מושגי ליבה

שידורים

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

האזנות

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

נקודות סימון

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

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

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

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

• שיוך שידורי וידאו וסטרימינג.

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

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

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

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

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

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

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

4. להכיר את מושגי הליבה של פורמט הנתונים JavaScript Object Notation (JSON). 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 חולקים את אותו מזהה. לאחר יצירת השידור באמצעות ממשק ה-API של סטרימינג בשידור חי, תוכלו להשתמש ממשק API של נתונים ב-YouTube כדי לספק מטא-נתונים נוספים על הסרטון.
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 לפעול מודעות באמצע הסרטון (mid-roll) במהלך השידור.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[(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 – מאגר הנתונים הזמני של 5 השניות כשאי אפשר להכניס את נקודת הרמז בצורה אמינה.

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

ההנחיות הבאות מסבירות כיצד לפתור בעיות ספציפיות שעלולות להתעורר. לרשימות שגיאות שכל שיטת API עשויה להחזיר, כדאי לעיין במאמר YouTube Live Streaming API – שגיאות.

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

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

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