LiveBroadcasts: cuepoint

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

הערה: השיטה הזו מחליפה את השיטה liveCuepoints.insert, שבה נדרשה הרשאה לבקשות מחשבון שמשויך לבעלי תוכן ב-YouTube. לשיטה הזו אין את אותה דרישת הרשאה.

בקשה

בקשת HTTP

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

אישור

הבקשה הזו דורשת הרשאה עם לפחות אחד מההיקפים הבאים. למידע נוסף על אימות והרשאה, קראו את המאמר הטמעת אימות OAuth 2.0.

היקף
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

פרמטרים

בטבלה הבאה מפורטים הפרמטרים שהשאילתה הזו תומכת בהם. כל הפרמטרים שמפורטים הם פרמטרים של שאילתות.

פרמטרים
פרמטרים נדרשים
id string
הפרמטר id מזהה את השידור שאליו מתווסף נקודת העצירה. השידור צריך להיות פעיל בזמן שמוסיפים את נקודת העצירה.
פרמטרים אופציונליים
onBehalfOfContentOwner string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית.
הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube שבבעלותם מנוהלים הרבה ערוצי YouTube שונים. הוא מאפשר לבעלי תוכן לבצע אימות פעם אחת ולבצע פעולות בשם הערוץ שצוין בערך הפרמטר, בלי לספק פרטי כניסה שונים לאימות לכל ערוץ בנפרד. החשבון שבו המשתמש מבצע אימות חייב להיות מקושר לבעלי התוכן ב-YouTube שצוין.
הפרמטר onBehalfOfContentOwner מציין שפרטי הכניסה של הבקשה מזהים משתמש ב-YouTube שפועל בשם בעל התוכן ב-YouTube שצוין בערך הפרמטר. הפרמטר הזה מיועד לשותפי תוכן ב-YouTube שבבעלותם מנוהלים הרבה ערוצים שונים ב-YouTube.
onBehalfOfContentOwnerChannel string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית.
הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube שבבעלותם מנוהלים הרבה ערוצי YouTube שונים. הוא מאפשר לבעלי תוכן לבצע אימות פעם אחת ולבצע פעולות בשם הערוץ שצוין בערך הפרמטר, בלי לספק פרטי כניסה לאימות לכל ערוץ בנפרד.
הפרמטר onBehalfOfContentOwnerChannel מציין את מזהה ערוץ YouTube של הערוץ שמשויך לשידור שאליו מוכנס נקודת העצירה. הפרמטר הזה נדרש כשבבקשה מצוין ערך לפרמטר onBehalfOfContentOwner, וניתן להשתמש בו רק בשילוב עם הפרמטר הזה. חלות גם הדרישות הבאות:
  • צריך לאשר את הבקשה באמצעות חשבון משתמש שמקושר לבעל התוכן שמצוין בפרמטר onBehalfOfContentOwner.
  • הערוץ שצוין בערך הפרמטר onBehalfOfContentOwnerChannel חייב להיות מקושר לבעלי התוכן שצוין בערך הפרמטר onBehalfOfContentOwner.

גוף הבקשה

מספקים משאב cuepoint בגוף הבקשה. המבנה הבא של JSON מציג את הפורמט של משאב cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
 גוף הבקשה חייב לכלול את השדה cueType, שמוגדרת לו הערך cueTypeAd. אפשר גם להגדיר ערכים לנכסים הבאים:
  • durationSecs
  • insertionOffsetTimeMs (אסור להגדיר את השדה אם walltimeMs מוגדר)
  • walltimeMs (אסור להגדיר את השדה אם השדה insertionOffsetTimeMs מוגדר)

מאפיינים

בטבלה הבאה מפורטים המאפיינים שמופיעים במשאב הזה:

מאפיינים
id string
ערך ש-YouTube מקצה כדי לזהות באופן ייחודי את נקודת העצירה. לתשומת ליבכם: הערך הזה שונה מהפרמטר הנדרש id, שמזהה את השידור. אפשר להשמיט את הערך הזה כששולחים בקשה להוספת נקודת סימון. הערך יאוכלס בתגובה מה-API.
insertionOffsetTimeMs long
ערך המאפיין מזהה את הפרש הזמן, באלפיות השנייה, שבו צריך להוסיף את נקודת הסימון. הערך נמדד מתחילת שידור המעקב, וערך ברירת המחדל שלו הוא 0, שמציין שצריך להוסיף את נקודת ה-cue בהקדם האפשרי. אין לציין ערך לפרמטר הזה אם לשידור אין שידור ביקורת.

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

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

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

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

ה-API מחזיר שגיאה אם בבקשה מנסים להוסיף נקודת סימון שמציינת ערך למאפיין הזה ולמאפיין insertionOffsetTimeMs.
durationSecs unsigned integer
משך הזמן של נקודת הסימון, בשניות. הערך חייב להיות מספר שלם חיובי. ערך ברירת המחדל הוא 30.
cueType string
הסוג של נקודת הסימון. יש להגדיר את ערך המאפיין כ-cueTypeAd.

תשובה

אם הפעולה בוצעה ללא שגיאות, השיטה מחזירה את משאב cuepoint שהוכנס בגוף התגובה.

שגיאות

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

סוג השגיאה פרטי השגיאה תיאור
insufficientPermissions (403) insufficientLivePermissions אין לבקשה הרשאה להוסיף נקודת סימון בשידור החי.
insufficientPermissions (403) liveStreamingNotEnabled למשתמש שהעניק הרשאה לבקשה אין אפשרות לבצע סטרימינג של שידור חי ב-YouTube. המשתמש יכול למצוא מידע נוסף במאמרים תחילת העבודה עם סטרימינג בשידור חי והקריטריונים לשימוש בתכונות.
rateLimitExceeded (403) userRequestsExceedRateLimit המשתמש שלח יותר מדי בקשות בפרק זמן נתון.
required (400) idRequired הפרמטר הנדרש id צריך לזהות את השידור שבו רוצים להוסיף נקודת סימון.
required (400) cueTypeRequired צריך לציין את השדה הנדרש cueType בגוף הבקשה ל-API.
notFound (404) liveBroadcastNotFound השידור שצוין באמצעות הפרמטר id לא קיים.
invalidValue (400) conflictingTimeFields אפשר לציין רק אחד מתוך insertionOffsetTimeMs ו-walltimeMs. הגדרת שני הערכים גורמת לשגיאה. אם לא תגדירו אף אחד מהערכים, מערכת YouTube תשתמש בזמן ברירת המחדל של insertionOffsetTimeMs (0), כלומר נקודת העצירה תוכנס בהקדם האפשרי.
invalidValue (400) invalidInsertionOffsetTimeMs המשאב cuepoint ציין ערך לא חוקי למאפיין insertionOffsetTimeMs. הערך חייב להיות 0 או מספר שלם חיובי.
invalidValue (400) invalidWalltimeMs המשאב cuepoint ציין ערך לא חוקי למאפיין walltimeMs. הערך חייב להיות מספר שלם שמייצג חותמת זמן של עידן (באלפיות שנייה).
backendError (5xx) serviceUnavailable השירות לא זמין. אפשר לנסות שוב את הבקשה בעוד כמה דקות.

נסה בעצמך!

משתמשים ב-APIs Explorer כדי לקרוא ל-API הזה ולראות את הבקשה ואת התשובה של ה-API.