Videos: update

ה-API תומך עכשיו ביכולת לסמן את הערוץ או את הסרטונים שלך כ'במיוחד לילדים'. נוסף על כך, המשאבים של channel ושל video כוללים עכשיו נכס שמזהה את הסטטוס 'במיוחד לילדים' עבור הערוץ או הסרטון האלה. התנאים וההגבלות של YouTube API ומדיניות המפתחים עודכנו גם ב-10 בינואר 2020. למידע נוסף, כדאי לעיין בהיסטוריית הגרסאות של שירות YouTube Data API ובתנאים ובהגבלות של שירותי YouTube API.

עדכון המטא-נתונים של הסרטון.

ההשפעה על המכסה: קריאה לשיטה זו כוללת עלות מכסה של 50 יחידות.

תרחישים נפוצים

שליחת בקשה

בקשת HTTP

PUT https://www.googleapis.com/youtube/v3/videos

הרשאה

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

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

פרמטרים

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

פרמטרים
פרמטרים נדרשים
part string
הפרמטר part משמש לשתי מטרות בפעולה הזו. היא מזהה את המאפיינים שפעולת הכתיבה תגדיר, וגם את המאפיינים שתגובת ה-API תכלול.

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

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

הרשימה הבאה מכילה את שמות part שאפשר לכלול בערך הפרמטר:
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
פרמטרים אופציונליים
onBehalfOfContentOwner string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube.

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

גוף הבקשה

יש לספק משאב סרטון בגוף הבקשה. לגבי המשאב הזה:

  • צריך לציין ערך למאפיינים הבאים:

    • id
    • snippet.title – הנכס הזה נדרש רק אם הבקשה מעדכנת את snippet של המשאב video.
    • snippet.categoryId – הנכס הזה נדרש רק אם הבקשה מעדכנת את snippet של המשאב video.

  • אפשר להגדיר ערכים לנכסים האלה:

    • snippet.categoryId
    • snippet.defaultLanguage
    • snippet.description
    • snippet.tags[]
    • snippet.title
    • status.embeddable
    • status.license
    • status.privacyStatus
    • status.publicStatsViewable
    • status.publishAt – אם מגדירים ערך עבור הנכס, חובה להגדיר גם את המאפיין status.privacyStatus כ-private.
    • status.selfDeclaredMadeForKids
    • recordingDetails.locationDescription (הוצא משימוש)
    • recordingDetails.location.latitude (הוצא משימוש)
    • recordingDetails.location.longitude (הוצא משימוש)
    • recordingDetails.recordingDate
    • localizations.(key)
    • localizations.(key).title
    • localizations.(key).description

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

תשובה

אם הצלחת, השיטה הזו מחזירה משאב וידאו בגוף התגובה.

שגיאות

הטבלה הבאה מזהה הודעות שגיאה שה-API יכול להחזיר בתגובה לקריאה לשיטה הזו. מידע נוסף זמין בתיעוד של הודעת השגיאה.

סוג השגיאה פרטי השגיאה תיאור
badRequest (400) defaultLanguageNotSet בקשת ה-API מנסה להוסיף פרטים לסרטון המותאמים לשוק המקומי, בלי לציין את שפת ברירת המחדל של פרטי הסרטון.
badRequest (400) invalidCategoryId המאפיין snippet.categoryId מציין מזהה קטגוריה לא חוקי. צריך להשתמש בשיטה videoCategories.list כדי לאחזר קטגוריות נתמכות.
badRequest (400) invalidDefaultBroadcastPrivacySetting הבקשה מנסה לקבוע הגדרת פרטיות לא חוקית עבור שידור ברירת המחדל.
badRequest (400) invalidDescription המטא-נתונים של הבקשה מציינים תיאור סרטון לא חוקי.
badRequest (400) invalidPublishAt המטא-נתונים של הבקשה מציינים זמן פרסום מתוזמן לא חוקי.
badRequest (400) invalidRecordingDetails האובייקט recordingDetails במטא-נתונים של הבקשה מציין פרטי הקלטה לא חוקיים.
badRequest (400) invalidTags המטא-נתונים של הבקשה מציינים מילות מפתח לא חוקיות.
badRequest (400) invalidTitle המטא-נתונים של הבקשה מציינים כותרת סרטון לא חוקית או ריקה.
badRequest (400) invalidVideoMetadata המטא-נתונים של הבקשה לא חוקיים.
forbidden (403) forbidden
forbidden (403) forbiddenEmbedSetting הבקשה מנסה להגדיר הגדרת הטמעה לא חוקית עבור הסרטון. לידיעתכם, יכול להיות שערוצים מסוימים לא יקבלו הרשאה להציע נגנים מוטמעים עבור שידורים חיים. במרכז העזרה של YouTube תוכלו למצוא מידע נוסף.
forbidden (403) forbiddenLicenseSetting הבקשה מנסה להגדיר רישיון לא חוקי עבור הסרטון.
forbidden (403) forbiddenPrivacySetting הבקשה מנסה לקבוע הגדרת פרטיות לא חוקית עבור הסרטון.
notFound (404) videoNotFound הסרטון שניסית לעדכן לא נמצא. עליך לבדוק את הערך שבשדה id בגוף הבקשה כדי לוודא שהוא נכון.

רוצה לנסות?

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