ממשק ה-API תומך עכשיו באפשרות לסמן את השידורים
החיים שלך בקטגוריה 'במיוחד לילדים', והמשאב
liveBroadcast
מכיל עכשיו
מאפיין שמזהה את הסטטוס 'במיוחד לילדים' של השידור החי. ב-10 בינואר 2020 עודכנו גם התנאים וההגבלות של שירותי YouTube API
והמדיניות למפתחים. למידע
נוסף, ניתן לעיין בהיסטוריית הגרסאות של
שירות YouTube Live Streaming API ובתנאים ובהגבלות של שירותי YouTube API.
משאב liveBroadcast
מייצג אירוע שישודר ב-YouTube באמצעות וידאו בשידור חי.
שיטות
ה-API תומך בשיטות הבאות למשאבי liveBroadcasts
:
- list
- מחזיר רשימה של שידורי YouTube שתואמים לפרמטרים של בקשת ה-API. כדאי לנסות עכשיו.
- הוספה
- יצירת שידור. כדאי לנסות עכשיו.
- עדכון
- מעדכן שידור. לדוגמה, אפשר לשנות את הגדרות השידור שהוגדרו באובייקט
contentDetails
של המשאבliveBroadcast
. רוצים לנסות עכשיו? - מחיקה
- מחיקת שידור. כדאי לנסות עכשיו.
- קישור
- מקשר שידור מ-YouTube לשידור או מסיר קישור קיים בין שידור לשידור. שידור יכול להיות מקושר רק לזרם וידאו אחד, אך זרם וידאו עשוי להיות מקושר ליותר משידור אחד. כדאי לנסות עכשיו.
- מעבר
- משנה את הסטטוס של שידור חי ב-YouTube ומתחיל תהליכים שמשויכים לסטטוס החדש. לדוגמה, כשמעבירים סטטוס של שידור ל-
testing
, המערכת של YouTube מתחילה לשדר וידאו לשידור המוניטור של אותו שידור. לפני קריאה לשיטה הזו, צריך לוודא שהערך של המאפייןstatus.streamStatus
עבור השידור שקשור לשידור שלך הואactive
. רוצים לנסות עכשיו? - cuepoint
- הוספת נקודת סימון לשידור חי. נקודת הסימון עשויה להפעיל הפסקה למודעה.
ייצוג משאבים
מבנה ה-JSON הבא מציג את הפורמט של משאב liveBroadcasts
:
{ "kind": "youtube#liveBroadcast", "etag": etag, "id": string, "snippet": { "publishedAt": datetime, "channelId": string, "title": string, "description": string, "thumbnails": { (key): { "url": string, "width": unsigned integer, "height": unsigned integer } }, "scheduledStartTime": datetime, "scheduledEndTime": datetime, "actualStartTime": datetime, "actualEndTime": datetime, "isDefaultBroadcast": boolean, "liveChatId": string }, "status": { "lifeCycleStatus": string, "privacyStatus": string, "recordingStatus": string, "madeForKids": string, "selfDeclaredMadeForKids": string, }, "contentDetails": { "boundStreamId": string, "boundStreamLastUpdateTimeMs": datetime, "monitorStream": { "enableMonitorStream": boolean, "broadcastStreamDelayMs": unsigned integer, "embedHtml": string }, "enableEmbed": boolean, "enableDvr": boolean, "recordFromStart": boolean, "enableClosedCaptions": boolean, "closedCaptionsType": string, "projection": string, "enableLowLatency": boolean, "latencyPreference": boolean, "enableAutoStart": boolean, "enableAutoStop": boolean }, "statistics": { "totalChatCount": unsigned long }, "monetizationDetails": { "cuepointSchedule": { "enabled": boolean, "pauseAdsUntil": datetime, "scheduleStrategy": string, "repeatIntervalSecs": unsigned integer, } } }
מאפיינים
בטבלה הבאה מוגדרים המאפיינים שמופיעים במשאב הזה:
מאפיינים | |
---|---|
kind |
string זהו הסוג של משאב ה-API. הערך יהיה youtube#liveBroadcast . |
etag |
etag ה-Etag של המשאב הזה. |
id |
string המזהה שמערכת YouTube מקצה כדי לזהות באופן ייחודי את השידור. |
snippet |
object האובייקט snippet מכיל פרטים בסיסיים על האירוע, כולל השם, התיאור, שעת ההתחלה ושעת הסיום שלו. |
snippet.publishedAt |
datetime התאריך והשעה שבהם השידור נוסף ללוח הזמנים של השידור החי ב-YouTube. הערך מצוין בפורמט ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.channelId |
string המזהה שמשמש את YouTube לזיהוי ייחודי של הערוץ שמפרסם את השידור. |
snippet.title |
string שם השידור. חשוב לזכור שהשידור מייצג רק סרטון YouTube אחד. ניתן להגדיר את השדה הזה על ידי שינוי משאב השידור או על ידי הגדרת השדה title של משאב הווידאו המתאים. |
snippet.description |
string תיאור השידור. כמו ב- title , אפשר להגדיר את השדה הזה על ידי שינוי משאב השידור או הגדרת השדה description של משאב הווידאו המתאים. |
snippet.thumbnails |
object מפה של תמונות ממוזערות המשויכות לשידור. לכל אובייקט בתוך אובייקט באובייקט הזה, המפתח הוא השם של התמונה הממוזערת והערך הוא אובייקט שמכיל מידע נוסף על התמונה הממוזערת. |
snippet.thumbnails.(key) |
object ערכי המפתח החוקיים הם:
|
snippet.thumbnails.(key).url |
string כתובת ה-URL של התמונה. |
snippet.thumbnails.(key).width |
unsigned integer רוחב התמונה. |
snippet.thumbnails.(key).height |
unsigned integer גובה התמונה. |
snippet.scheduledStartTime |
datetime התאריך והשעה שבהם השידור מתוכנן להתחיל. הערך מצוין בפורמט ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). הסטודיו ליוצרים תומך באפשרות ליצור שידור בלי לתזמן שעת התחלה. במקרה כזה, השידור יתחיל בכל פעם שבעלי הערוץ מתחילים לשדר. בשידורים האלה, הערך datetime תואם לאפס זמן UNIX, ולא ניתן לשנות את הערך הזה דרך ה-API או ב-YouTube Studio. |
snippet.scheduledEndTime |
datetime התאריך והשעה שבהם השידור מתוזמן להסתיים. הערך מצוין בפורמט ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). אם במשאב liveBroadcast לא מצוין ערך למאפיין הזה, השידור מתוזמן להימשך ללא הגבלת זמן. באופן דומה, אם לא תציינו ערך לנכס הזה, המערכת של YouTube תתייחס לשידור כאילו הוא יימשך ללא הגבלה. |
snippet.actualStartTime |
datetime התאריך והשעה שבהם השידור התחיל בפועל. המידע הזה זמין רק כשמצב השידור הוא live . הערך מצוין בפורמט ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.actualEndTime |
datetime התאריך והשעה שבהם השידור הסתיים בפועל. המידע הזה זמין רק כשמצב השידור הוא complete . הערך מצוין בפורמט ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.isDefaultBroadcast |
boolean
הנכס הזה יצא משימוש ב-1 בספטמבר 2020 או לאחר מכן. בתאריך הזה, אם מופעלת בערוץ
האפשרות לסטרימינג בשידור חי, מערכת YouTube
תפסיק ליצור שידור ברירת מחדל ושידור ברירת מחדל. לפרטים נוספים, יש לעיין בהודעה על ההוצאה משימוש.
המאפיין הזה מציין אם השידור הזה הוא שידור ברירת המחדל.איך פועלים שידורי ברירת מחדל כשמפעילים בערוץ YouTube סטרימינג בשידור חי, המערכת של YouTube יוצרת עבור הערוץ שידור ברירת מחדל ושידור ברירת מחדל. השידור מגדיר את האופן שבו בעלי הערוץ שולחים וידאו בשידור חי ל-YouTube, ואופן השידור מאפשר לצופים לראות את שידור ברירת המחדל. בעלים של ערוץ יכולים להשתמש בשיטות liveStreams.list ו-liveBroadcasts.list כדי לזהות את המשאבים האלה.כשערוץ מתחיל לשדר וידאו בסטרימינג המוגדר כברירת מחדל, הסרטון גלוי בשידור ברירת המחדל של הערוץ. בסיום השידור, המערכת של YouTube ממירה את השידור שהושלם לסרטון YouTube ומקצה לסרטון מזהה וידאו ב-YouTube. לאחר השלמת ההמרה, הסרטון ייכלל ברשימת הסרטונים שהועלו לערוץ. הסרטון אינו זמין מיד לאחר סיום השידור, ומשך העיכוב קשור למשך השידור בפועל. |
snippet.liveChatId |
string המזהה של הצ'אט בשידור חי ב-YouTube. באמצעות המזהה הזה אפשר להשתמש בשיטות של המשאב liveChatMessage כדי לאחזר, להוסיף או למחוק הודעות צ'אט. תוכלו גם להוסיף או להסיר מנהלי צ'אט, לחסום את ההשתתפות של משתמשים בצ'אטים בשידור חי או להסיר חסימות קיימות. |
status |
object האובייקט status מכיל מידע על סטטוס האירוע. |
status.lifeCycleStatus |
string סטטוס השידור. אפשר לעדכן את הסטטוס באמצעות השיטה liveBroadcasts.transition של ה-API.הערכים החוקיים לנכס הזה הם:
|
status.privacyStatus |
string סטטוס הפרטיות של השידור. שימו לב שהשידור מייצג רק סרטון אחד של YouTube, ולכן הגדרות הפרטיות זהות להגדרות שנתמכות עבור סרטונים. בנוסף, אפשר להגדיר את השדה הזה על ידי שינוי משאב השידור או הגדרת השדה privacyStatus של משאב הווידאו המתאים.הערכים החוקיים לנכס הזה הם:
|
status.recordingStatus |
string סטטוס ההקלטה של השידור. הערכים החוקיים לנכס הזה הם:
|
status.madeForKids |
boolean הערך הזה מציין אם השידור מסווג כמיועד לילדים. הערך של המאפיין הזה הוא לקריאה בלבד. |
status.selfDeclaredMadeForKids |
boolean בבקשת liveBroadcasts.insert , הנכס הזה מאפשר לבעלים של הערוץ להגדיר את השידור
כמיועד לילדים. בבקשת
liveBroadcasts.list
ערך הנכס מוחזר רק אם בעלי הערוץ אישרו את בקשת
ה-API. |
contentDetails |
object האובייקט contentDetails מכיל מידע על תוכן הווידאו של האירוע. למשל, אם אפשר להציג את התוכן בנגן וידאו מוטמע או אם הוא יועבר לארכיון ויהיה זמין לצפייה בסיום האירוע. |
contentDetails.boundStreamId |
string הערך הזה מזהה באופן ייחודי את live stream שקשור לשידור. |
contentDetails.boundStreamLastUpdateTimeMs |
datetime התאריך והשעה שבהם בוצע העדכון האחרון של השידור החי boundStreamId . |
contentDetails.monitorStream |
object האובייקט monitorStream מכיל מידע על השידור החי, והוא יכול להשתמש בו כדי לבדוק את תוכן האירוע לפני השידור הציבורי שמוצג בו. |
contentDetails.monitorStream.enableMonitorStream |
boolean הערך הזה קובע אם השידור לצורכי מעקב מופעל עבור השידור. אם השידור למעקב מופעל, YouTube ישדר את תוכן האירוע בשידור מיוחד המיועד רק לצרכני השידור. המשדר יכול להשתמש בסטרימינג כדי לעיין בתוכן האירוע וגם לזהות את הזמנים האופטימליים להוספת נקודות סימון. עליך להגדיר את הערך הזה כ- true אם בכוונתך ליצור שלב testing בשידור או אם ברצונך שיהיה עיכוב בשידור עבור האירוע. בנוסף, אם הערך של המאפיין הזה הוא true , עליך להעביר את השידור שלך למצב testing לפני שתהיה אפשרות להעביר אותו למצב live . (אם הערך של המאפיין הוא false , השידור לא יכול להכיל שלב testing , לכן אפשר להעביר את השידור ישירות למצב live ).ב update a broadcast , צריך להגדיר את המאפיין הזה אם בקשת ה-API כוללת את החלק contentDetails בערך הפרמטר part . עם זאת, כשבוחרים באפשרות insert a broadcast , המאפיין הוא אופציונלי וערך ברירת המחדל שלו הוא true .חשוב: לא ניתן לעדכן את המאפיין הזה אחרי שהשידור במצב testing או live . |
contentDetails.monitorStream.broadcastStreamDelayMs |
unsigned integer אם הגדרת את המאפיין enableMonitorStream לערך true , המאפיין הזה יקבע את משך העיכוב בשידור החי.ב update a broadcast , צריך להגדיר את המאפיין הזה אם בקשת ה-API כוללת את החלק contentDetails בערך הפרמטר part . עם זאת, כשבוחרים באפשרות insert a broadcast , המאפיין הוא אופציונלי וערך ברירת המחדל שלו הוא 0 . הערך הזה מציין שאין עיכוב בשידור. הערה: לא ניתן לעדכן את המאפיין הזה אחרי שהשידור נמצא במצב testing או live . |
contentDetails.monitorStream.embedHtml |
string קוד HTML שמוטמע בו נגן שמפעיל את הסטרימינג של הצג. |
contentDetails.enableEmbed |
boolean ההגדרה הזו קובעת אם אפשר להפעיל את סרטון השידור בנגן מוטמע. אם בוחרים להעביר את הסרטון לארכיון (באמצעות המאפיין enableArchive ), ההגדרה הזו תחול גם על הסרטון שהועבר לארכיון.ב update a broadcast , צריך להגדיר את המאפיין הזה אם בקשת ה-API כוללת את החלק contentDetails בערך הפרמטר part . עם זאת, כשבוחרים באפשרות insert a broadcast , המאפיין הוא אופציונלי וערך ברירת המחדל שלו הוא true .הערה: לא ניתן לעדכן את המאפיין הזה אחרי שהשידור במצב testing או live . |
contentDetails.enableDvr |
boolean ההגדרה הזו קובעת אם הצופים יוכלו לגשת לפקדי ה-DVR בזמן הצפייה בסרטון. פקדי DVR מאפשרים לצופה לשלוט בחוויית ההפעלה של הסרטונים על ידי השהיה, הרצה אחורה או העברה מהירה של התוכן. ערך ברירת המחדל של הנכס הזה הוא true . ב update a broadcast , צריך להגדיר את המאפיין הזה אם בקשת ה-API כוללת את החלק contentDetails בערך הפרמטר part . עם זאת, כשבוחרים באפשרות insert a broadcast , המאפיין הוא אופציונלי וערך ברירת המחדל שלו הוא true .חשוב: צריך להגדיר את הערך true וגם להגדיר את ערך המאפיין enableArchive כ-true אם רוצים שההפעלה תהיה זמינה מיד לאחר סיום השידור. בנוסף, לא ניתן לעדכן את המאפיין הזה אחרי שהשידור נמצא במצב testing או live . |
contentDetails.recordFromStart |
boolean ההגדרה הזו קובעת אם המערכת של YouTube תתחיל להקליט את השידור באופן אוטומטי אחרי שסטטוס האירוע ישתנה ל'שידור חי'. ערך ברירת המחדל של הנכס הזה הוא true , וניתן להגדיר אותו ל-false רק אם בערוץ המשדר מותר להשבית הקלטות לשידורים חיים.אם לערוץ שלך אין הרשאה להשבית הקלטות, ותנסו להוסיף שידור עם מאפיין recordFromStart שהוגדר כ-false , ה-API יחזיר שגיאת Forbidden . בנוסף, אם לערוץ שלכם אין את ההרשאה הזו ותנסו לעדכן שידור כדי להגדיר את המאפיין recordFromStart לערך false , ה-API יחזיר שגיאת modificationNotAllowed .ב update a broadcast , צריך להגדיר את המאפיין הזה אם בקשת ה-API כוללת את החלק contentDetails בערך הפרמטר part . עם זאת, כשבוחרים באפשרות insert a broadcast , המאפיין הוא אופציונלי וערך ברירת המחדל שלו הוא true .חשוב: חובה להגדיר גם את הערך של המאפיין enableDvr ל-true אם רוצים שההפעלה תהיה זמינה מיד לאחר סיום השידור. אם הגדרת את ערך הנכס הזה כ-true אבל לא הגדרת גם את המאפיין enableDvr כ-true , ייתכן שיעבור בערך יום אחד עד שהסרטון שהועבר לארכיון יהיה זמין להפעלה.הערה: לא ניתן לעדכן את המאפיין הזה אחרי שהשידור במצב testing או live . |
contentDetails.enableClosedCaptions |
boolean הנכס הזה הוצא משימוש ב-17 בדצמבר 2015. במקום זאת, צריך להשתמש במאפיין contentDetails.closedCaptionsType .ההגדרה קובעת אם כתוביות HTTP POST מופעלות בשידור הזה. עבור לקוחות API שכבר משתמשים בנכס זה:
|
contentDetails.closedCaptionsType |
string הערה: הנכס הזה מחליף את הנכס contentDetails.enableClosedCaptions .המאפיין הזה מציין אם הכתוביות מופעלות בשידור שלך, ואם כן, איזה סוג של כתוביות אתם מספקים:
|
contentDetails.projection |
string פורמט ההקרנה של השידור הזה. ערך ברירת המחדל של הנכס הוא rectangular .הערכים החוקיים לנכס הזה הם:
|
contentDetails.enableLowLatency |
boolean מציין אם השידור הזה מקודד לסטרימינג עם זמן אחזור קצר. סטרימינג עם זמן אחזור קצר יכול לצמצם את משך הזמן שלוקח לסרטון להיות גלוי למשתמשים שצופים בשידור, למרות שהוא יכול גם להשפיע על הרזולוציה עבור הצופים בשידור. |
contentDetails.latencyPreference |
string מציין באיזו הגדרת זמן אחזור להשתמש לשידור הזה. אפשר להשתמש במאפיין הזה במקום ב- enableLowLatency , שאינו תומך ב-ultraLow .שידור עם זמן אחזור נמוך עשוי לקצר את משך הזמן שלוקח לסרטון להיות גלוי למשתמשים שצופים בשידור, למרות שהוא יכול גם להשפיע על החלקת ההפעלה. שידור עם זמן אחזור נמוך במיוחד מפחית עוד יותר את הזמן שלוקח לסרטון להיות גלוי לצופים, ובכך מקצר את משך הזמן שנדרש לצופים כדי לצפות בכתוביות, אבל הוא לא תומך בזמני אחזור ארוכים במיוחד, אך לא תומך בזמני אחזור ארוכים במיוחד .
|
contentDetails.enableAutoStart |
boolean מציין אם השידור הזה צריך להתחיל באופן אוטומטי כשמתחילים סטרימינג של וידאו ב- live stream . |
contentDetails.enableAutoStop |
boolean מציין אם השידור הזה יופסק באופן אוטומטי כדקה אחרי שבעלי הערוץ מפסיקים את הסטרימינג של הווידאו בסטרימינג. |
statistics |
object האובייקט statistics מכיל נתונים סטטיסטיים שקשורים לשידור חי. הערכים של סטטיסטיקות אלה עשויים להשתנות במהלך השידור וניתן לאחזר אותם רק בזמן השידור החי. |
statistics.totalChatCount |
unsigned long המספר הכולל של הודעות צ'אט בשידור חי המשויכות לשידור. הנכס והערך שלו קיימים אם השידור גלוי למשתמש, אם תכונת הצ'אט בשידור חי מופעלת בו ויש בו הודעה אחת לפחות. שימו לב שהמאפיין הזה לא יציין ערך לאחר סיום השידור. לכן, הנכס הזה לא יזהה את מספר הודעות הצ'אט עבור סרטון שהועבר לארכיון של שידור חי שהושלם. |
monetizationDetails |
object האובייקט monetizationDetails מכיל מידע על פרטי המונטיזציה
של השידור. למשל, אם הכלי האוטומטי של המודעות מופעל או אם יש עיכוב בהוספת המודעות באמצע הסרטון. |
monetizationDetails.cuepointSchedule |
object האובייקט cuepointSchedule מציין את ההגדרות לאוטומציה של מודעות
השידור. |
monetizationDetails.cuepointSchedule.enabled |
boolean הערך הזה קובע אם מודעות יוכנסו באופן אוטומטי לשידור. אם הערך הוא true , המערכת של YouTube תכניס לשידור באופן אוטומטי מודעות באמצע הסרטון. לוח הזמנים
להצגת מודעות ייקבע לפי הערך של השדות האחרים
באובייקט monetizationDetails.cuepointSchedule .
|
monetizationDetails.cuepointSchedule.pauseAdsUntil |
datetime הערך הזה מציין שאסור שהמערכת של YouTube תוסיף לשידור מודעות באמצע הסרטון עד התאריך והשעה שצוינו. הערך מצוין בפורמט ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). כדי להשהות מודעות, צריך להגדיר את הערך לתאריך ושעה בעתיד. אפשר גם להגדיר את ערך השדה לתאריך ושעה קרובים, כדי לבטל את ההשהיה של המודעות כשהזמן חולף. |
monetizationDetails.cuepointSchedule.scheduleStrategy |
string הערך הזה מציין את השיטה שבה מערכת YouTube צריכה להשתמש כדי לתזמן נקודות סימון. הערכים החוקיים הם:
|
monetizationDetails.cuepointSchedule.repeatIntervalSecs |
unsigned integer הערך הזה מציין את המרווח בשניות, בין הוספה אוטומטית של מודעה במהלך שידור. לדוגמה, אם הערך הוא 300 , מערכת YouTube יכולה להוסיף נקודות סימון למודעות באמצע סרטון במרווחי זמן של חמש דקות.חשוב לזכור שהערך הזה מציין את הזמן שחולף בין תחילת נקודות הסימון הבאות. כלומר, המרווח לא נמדד החל מסופו של נקודת סימון אחת לתחילתה של נקודת המוצא הבאה. |