מחזור החיים של שידור

מבוא

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

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

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

מקורות מידע של YouTube Live Streaming API

משאבי YouTube Data API

משאבי YouTube Content ID API

יצירה וניהול של שידור חי

בשלבים הבאים נסביר איך ליצור ולנהל אירוע בשידור חי ב-YouTube. השלבים נחלקים לשלבים הבאים:

  1. הגדרת השידור
  2. תביעת בעלות על התוכן שלכם
  3. בדיקה
  4. שידור
  5. סיום השידור
  6. יצירת קובץ עזר

שלב 1: הגדרת השידור

שלב 1.1: יצירת שידור

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

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

  • אם אתם רוצים לשלב את שלב הבדיקה בשידור, כאשר אתם יכולים להציג את שידור הווידאו שלכם גם אם הצופים האחרים לא יכולים לראות את השידור, עליכם להגדיר את המאפיין contentDetails.monitorStream.enableMonitorStream כ-true ואת המאפיין contentDetails.enableAutoStart כ-false. אלו הם ערכי ברירת המחדל לשני הנכסים.

  • כדי ליצור קובץ עזר מהשידור המוקלט, צריך להגדיר את המאפיין contentDetails.recordFromStart של השידור כ-true. אם אתם רוצים שהסרטון המוקלט יהיה זמין להפעלה מיד אחרי סיום השידור, תצטרכו גם להגדיר את המאפיין contentDetails.enableDvr כ-true. (ערך הנכסים של שני הנכסים האלה הוא true).

  • ניתן לעדכן כל אחד מהנכסים של contentDetails, כל עוד סטטוס השידור שלך הוא עדיין created או ready.

  • ניתן לעדכן את שעת ההתחלה המתוזמנת ואת שעת הסיום המתוכננת של השידור, כל עוד הסטטוס של השידור הוא created, ready או testing.

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

    הערה: אם רוצים שהסרטון יהיה זמין רק למשתמשי YouTube ספציפיים, מגדירים את ערך המאפיין של status.privacyStatus כ-unlisted או כ-private לפי הצרכים.

עיבוד התגובה ל-API

כשקוראים לשיטה liveBroadcasts.insert, התשובה ב-API מכילה את המשאב liveBroadcast שיצרתם. יש לחלץ את הקוד ולשמור את ה-id מהמשאב הזה. הערך הזה יעזור לכם לזהות את השידור בבקשות API עתידיות. (אפשר גם לזהות את המשאב video שתואם למשאב liveBroadcast באמצעות אותו מזהה.)

שלב 1.2: יוצרים שידור

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

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

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

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

  • snippet.description – בדומה לכותרת השידור, אפשר לעדכן את תיאור השידור לאחר יצירת השידור. הכותרת והתיאור לא גלויים למשתמשי YouTube.

  • contentDetails.isReusable – מציין אם אפשר להשתמש שוב בשידור. כלומר, הוא יכול להיות משויך לכמה שידורים. הערך של הנכס הזה קובע בפועל אם לערוץ יש קשר אחד-לאחד או אחד-לאחד בין המשאבים liveBroadcast ו-liveStream:

    • אם משתמשים בערך ברירת המחדל של הנכס true, אפשר להשתמש באותו משאב liveStream בכל השידורים של ערוץ. כלומר, אין צורך לחזור על השלב הזה (1.2) עבור כל שידור. במקום זאת, תוכלו פשוט להשתמש שוב במזהה השידור לשידורים הבאים.
    • אם הערך שמוגדר לנכס הוא false, צריך ליצור שידור חדש לכל שידור.

אחרי ששולחים את מקור ה-API, התגובה ל-API מכילה את המשאב liveStream שיצרתם. יש לחלץ את הקוד ולשמור אותו id מהמשאב הזה. הערך הזה יעזור לכם לזהות את מקור התנועה בבקשות API בעתיד.

שלב 1.3: קישור השידור לזרם שלו

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

בקריאה לשיטה liveBroadcasts.bind, מגדירים את הפרמטר id למזהה השידור שהתקבל בשלב 1.1 ואת הפרמטר streamId למזהה השידור שהתקבל בשלב 1.2.

שלב 2: מצהירים על זכויות יוצרים בתוכן

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

שלב 2.1: יצירת נכס

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

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

שלב 2.2: הגדרת הבעלות על הנכס

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

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

כדי להגדיר את האזורים שבהם יש לכם בעלות על הנכס, עליכם לקרוא לשיטה ownership.update. באותה בקשה, מגדירים את הפרמטר assetId לערך id שאחסנת בשלב 2.1.

שלב 2.3: הגדרת מדיניות ההתאמה של הנכס

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

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

כדי להגדיר את מדיניות ההתאמה, קודם צריך לזהות את המדיניות שאתם רוצים להחיל. אתם יכולים לאחזר רשימה של כללי המדיניות הקיימים על ידי קריאה לשיטה policies.list, או להגדיר שיטה חדשה על ידי קריאה לשיטה policies.insert. בכל מקרה, צריך לתעד את id המדיניות שרוצים להחיל.

אחרי שמאתרים את המדיניות, צריך לקרוא לשיטה assetMatchPolicy.update. בבקשה הזו, מגדירים את הפרמטר assetId לערך id שאחסנת בשלב 2.1.

שלב 2.4: מצהירים על זכויות יוצרים בסרטון

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

כדי ליצור תלונה, צריך להפעיל את השיטה claims.insert. במשאב claim שמוסיפים, צריך להגדיר ערכים למאפיינים הבאים:

  • assetId – השגת את הערך הזה בשלב 2.1.
  • videoId – מזהה השידור שקיבלת בשלב 1.1.
  • policy – זהו משאב מסוג policy. כדי להחיל מדיניות קיימת, צריך להגדיר את המאפיין id של המשאב לפי המזהה של המדיניות הקיימת. בשלב הקודם מוסבר איך לאחזר את המזהה של מדיניות קיימת.
  • contentType – יש להגדיר את הערך הזה ל-audiovisual.

עיבוד התגובה ל-API

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

שלב 2.5: עדכון הגדרות המודעות של השידור

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

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

כדי להפעיל מודעות, צריך להפעיל את השיטה videoAdvertisingOptions.update. בבקשה שלכם, שלחו את הפרמטר videoId לשידור id שקיבלתם בשלב 1.1. השתמשו בנכס adFormats[] של המשאב videoAdvertisingOption כדי לזהות את הפורמטים של המודעות (preroll, midroll או postroll) שאתם רוצים להפעיל.

שלב 3: בדיקה

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

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

שלב 3.1: הטמעת נגן סטרימר

מאחזרים את השידור באמצעות שיטת liveBroadcasts.list, וחלצים את הערך של המאפיין contentDetails.streamDetails.monitorStreamEmbedHtml. הערך הזה מכיל את ה-HTML שצריך להטמיע כדי להטמיע נגן YouTube שמציג את השידור.

שלב 3.2: מתחילים לצפות בסרטון

מתחילים לשדר וידאו בסטרימינג של הסרטון.

שלב 3.3: מוודאים ששידור הווידאו שלכם פעיל

מומלץ לקרוא לשיטה liveStreams.list כדי לאחזר את המשאב של liveStream המשויך לשידור שלכם. בדקו שהערך של הנכס status.streamStatus הוא active. הערך הזה מציין ששרתי YouTube מקבלים נתונים מהמקודד שלכם בצורה נכונה.

שלב 3.4: העברת הסטטוס של השידור שלך לבדיקה

מתקשרים לשיטה liveBroadcasts.transition כדי לעדכן את הסטטוס של השידור. מגדירים את ערך הפרמטר id למזהה השידור שהתקבל בשלב 1.1, ומגדירים את ערך הפרמטר broadcastStatus לערך testing.

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

שלב 3.5: השלמה של הבדיקה

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

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

  1. כדי לבטל את הקישור לשידור הווידאו, יש להפעיל את השיטה liveBroadcasts.bind בשלב 1.3. בבקשת ה-API, מגדירים את הפרמטר id לערך id שמתקבל בשלב 1.1. אין לכלול בבקשה את הפרמטר streamId.

  2. כדי למחוק את שידור הווידאו, יש להפעיל את השיטה liveStreams.delete. בבקשה, מגדירים את הפרמטר id לערך id שמתקבל בשלב 1.2.

  3. יש לחזור על שלב 1.2 כדי ליצור משאב liveStream חדש שיוגדר כהלכה. אחר כך חוזרים על שלב 1.3 כדי לקשר את השידור החדש לשידור, ואת שלבים 3.1 עד 3.3 כדי לבדוק את השידור החדש.

שלב 3.6: מפעילים את הנכסים של autoStart ושל autoStop

אחרי שמשלימים את שלב הבדיקה, אפשר להגדיר את מאפייני השידור contentDetails.enableAutoStart ו-contentDetails.enableAutoStop של true לפני שהשידור מתחיל בפועל. לא ניתן להגדיר את המאפיינים האלו כ-true לפני שלב הבדיקה, מכיוון שהבדיקה תגרום בפועל להתחלת השידור.

שלב 4: שידור

במהלך השלב הזה, הסרטון של השידור שלך יהיה זמין לצפייה לקהל שלך.

שלב 4.1: מתחילים לצפות בסרטון

מתחילים לשדר וידאו בסטרימינג של הסרטון.

שלב 4.2: מוודאים ששידור הווידאו שלכם פעיל

מומלץ לקרוא לשיטה liveStreams.list כדי לאחזר את המשאב של liveStream המשויך לשידור שלכם. בדקו שהערך של הנכס status.streamStatus הוא active. הערך הזה מציין ששרתי YouTube מקבלים נתונים מהמקודד שלכם בצורה נכונה.

שלב 4.3: העברת הסטטוס של השידור החי

חשוב: השלב הזה הופך את הסרטון לגלוי לקהל שלך.

מתקשרים לשיטה liveBroadcasts.transition כדי לעדכן את הסטטוס של השידור. מגדירים את ערך הפרמטר id למזהה השידור שהתקבל בשלב 1.1, ומגדירים את ערך הפרמטר broadcastStatus לערך live.

אם מגדירים את המאפיין contentDetails.enableAutoStart של המשאב liveBroadcast לערך true, לא צריך להפעיל את השיטה liveBroadcasts.transition.

אחרי ביצוע הקריאה ל-API, או אם הערך של המאפיין contentDetails.enableAutoStart הוא true לאחר תחילת השידור, בדרך כלל צריך לחכות 5 עד 10 שניות להשלמת המעבר. המעבר עשוי להימשך עד דקה. במהלך פרק הזמן הזה, צריך לבדוק את הסטטוס של השידור ב-API. עד שהמעבר יושלם, סטטוס השידור יהיה liveStarting. הסטטוס יהיה live לאחר שהמעבר יושלם, והצופים יוכלו לצפות בשידור שלך מנקודה זו בשידור החי בצ'אט.

שימו לב להשפעות הבאות של הפקודה הזו:

  • אם הפעלתם את זרם המעקב לשידור שלכם – ראו שלב 3.1 – תוכלו לראות את זרם המעקב בנגן מוטמע.
  • אם הגדרתם ערך עבור הנכס contentDetails.streamDetails.broadcastStreamDelayMs של השידור, שידור השידור, שיהיה גלוי לצופים אחרים, יתעכב בפרק הזמן הזה.

שלב 4.4: הוספת הפסקות למודעות לשידור

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

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

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

שלב 5: סיום השידור

שלב 5.1: מפסיקים את השידור

כאן מסתיימת הבדיקה של מערכת השידור החי של YouTube.

שלב 5.2: העברת הסטטוס של השידור להשלמת התהליך

כשתהיו מוכנים להפסיק את השידור, קראו לשיטה liveBroadcasts.transition של ה-API כדי לעדכן את סטטוס השידור. מגדירים את ערך הפרמטר id כמזהה השידור שמתקבל בשלב 1.1, ומגדירים את ערך הפרמטר broadcastStatus כ-complete.

אם הגדרתם את מאפייני השידור contentDetails.recordFromStart ואתcontentDetails.enableDvr השידור בתור true, בסיום האירוע בשידור חי, הקהל יוכל לצפות מיד בהפעלת האירוע בשידור חי.

שלב 6: יצירת קובץ עזר

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

חשוב: כדי שתוכלו ליצור את קובץ העזר, עליכם להגדיר את נכס השידור של contentDetails.recordFromStart לערך true.

שלב 6.1: עריכת הסקר ב-Data API לגבי סטטוס הסרטון

כדי ליצור קובץ עזר מ-YouTube, צריך לסיים את העיבוד של שידור או סרטון שהועלה. כדי לקבוע אם העיבוד של הסרטון הסתיים, מומלץ לבדוק את השיטה videos.list של ממשק ה-API של YouTube Data ולהגדיר את הפרמטר part ל-status ואת הפרמטר id למזהה השידור ששמרתם בשלב 1.1.

תגובת ה-API לבקשת הסקר תכלול משאב video. כאשר הערך של נכס status.uploadStatus של המשאב הזה הוא processed, ממשיכים לשלב 6.2.

שלב 6.2: יוצרים קובץ עזר מהסרטון שעבר עיבוד

כדי ליצור את קובץ העזר, קראו לשיטה references.insert של Content ID API והגדירו את הפרמטר claimId למזהה התביעה ששמרתם בשלב 2.4.

העברת Content ID בשידור חי

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

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