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

‫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. כל שידור משויך לשידור וידאו אחד.
נקודות סימון
cuepoint מייצגת הפסקה למודעות שאפשר להוסיף לשידור חי.

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

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

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

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

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

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

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

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

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

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

    1. עוברים אל Cloud console ובוחרים את הפרויקט שרשמתם.
    2. נכנסים לדף ממשקי ה-API המופעלים. ברשימת ממשקי ה-API, מוודאים שהסטטוס של YouTube Data API גרסה 3 הוא ON, ואם אתם שותפי תוכן של 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 יש את אותו מזהה. אחרי שיוצרים את השידור באמצעות 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 ישתמש במשאבי הרשת, המעבד והזיכרון בצורה יעילה יותר.

הפרמטר 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) במהלך שידור

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

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

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

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

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

הגדרת הזמן שחלף

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

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

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

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

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

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

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

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

חישוב הערך של הזמן שחלף

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

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

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

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

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

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

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

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

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

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

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

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

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