LiveBroadcasts: cuepoint

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

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

בקשה

בקשת HTTP

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

הרשאה

לבקשה הזו נדרשת הרשאה עם היקף הרשאות אחד לפחות (מידע נוסף על אימות והרשאה).

היקף
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. הערך הזה מציין שצריך להוסיף את נקודת המבט בהקדם האפשרי. אין לציין ערך לפרמטר הזה אם לשידור אין זרם מעקב.

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

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

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

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

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

תשובה

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

שגיאות

בטבלה הבאה מפורטות הודעות שגיאה שה-API יכול להחזיר בתגובה לקריאה לשיטה הזו. התיעוד של הודעת השגיאה מזהה את כל השגיאות שעשויות להתרחש ב-Live Streaming API.

סוג השגיאה פרטי השגיאה תיאור
insufficientPermissions (403) insufficientLivePermissions לבקשה אין הרשאה להוסיף סימן אישור בשידור החי.
insufficientPermissions (403) liveStreamingNotEnabled המשתמש שהעניק הרשאה לבקשה לא מורשה לשדר וידאו בשידור חי ב-YouTube. המשתמש יכול למצוא מידע נוסף בכתובת https://support.google.com/youtube/answer/2474026 ובכתובת https://www.youtube.com/features.
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.