PlaylistItems: insert

הוספת משאב לפלייליסט.

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

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

שליחת בקשה

בקשת HTTP

POST https://www.googleapis.com/youtube/v3/playlistItems

הרשאה

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

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

פרמטרים

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

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

הרשימה הבאה מכילה את שמות ה-part שניתן לכלול בערך הפרמטר:
  • contentDetails
  • id
  • snippet
  • status
פרמטרים אופציונליים
onBehalfOfContentOwner string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube.

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

גוף הבקשה

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

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

    • snippet.playlistId
    • snippet.resourceId

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

    • snippet.playlistId
    • snippet.position
    • snippet.resourceId
    • contentDetails.note
    • contentDetails.startAt
    • contentDetails.endAt

תשובה

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

שגיאות

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

סוג השגיאה פרטי השגיאה תיאור
forbidden (403) playlistContainsMaximumNumberOfVideos הפלייליסט כולל את מספר הפריטים המקסימלי המותר.
forbidden (403) playlistItemsNotAccessible הבקשה אינה מורשית להוסיף את פריט הפלייליסט שצוין.
invalidValue (400) invalidContentDetails נכס contentDetails בבקשה לא חוקי. סיבה אפשרית לכך היא שהשדה contentDetails.note ארוך מ-280 תווים.
invalidValue (400) invalidPlaylistItemPosition הבקשה מנסה להגדיר את המיקום של פריט הפלייליסט כערך לא חוקי או לא נתמך. צריך לבדוק את הערך של המאפיין position ב-snippet של המשאב.
invalidValue (400) invalidResourceType type שצוינו עבור מזהה המשאב אינו נתמך עבור פעולה זו. מזהה המשאב מזהה את הפריט שרוצים להוסיף לפלייליסט – למשל youtube#video.
invalidValue (400) manualSortRequired הבקשה מנסה להגדיר את מיקום הפריט בפלייליסט, אבל הפלייליסט לא משתמש במיון ידני. (לדוגמה, אפשר למיין את פריטי הפלייליסט לפי תאריך או פופולריות). כדי לתקן את השגיאה, אפשר להסיר את הרכיב snippet.position מהמשאב שהבקשה נוספה. אם אתם רוצים שלפריט הפלייליסט יהיה מיקום מסוים ברשימה, עליכם קודם לעדכן את האפשרות סידור של הפלייליסט לידני בהגדרות הפלייליסט. אפשר לשנות את ההגדרות האלה במנהל הסרטונים ב-YouTube.
invalidValue (400) videoAlreadyInAnotherSeriesPlaylist הסרטון שאתם מנסים להוסיף לפלייליסט כבר נמצא בפלייליסט אחר של סדרה.
notFound (404) playlistNotFound לא ניתן למצוא את הפלייליסט שמזוהה באמצעות הפרמטר playlistId של הבקשה.
notFound (404) videoNotFound הסרטון שאתם מנסים להוסיף לפלייליסט לא נמצא. יש לבדוק את הערך של המאפיין videoId כדי לוודא שהוא נכון.
required (400) channelIdRequired בבקשה לא צוין ערך למאפיין החובה channelId.
required (400) playlistIdRequired בבקשה לא צוין ערך למאפיין החובה playlistId.
required (400) resourceIdRequired הבקשה חייבת להכיל משאב שבו האובייקט snippet מציין resourceId.
invalidValue (400) playlistOperationUnsupported ממשק ה-API לא תומך באפשרות להוסיף סרטונים לפלייליסט שצוין. לדוגמה, לא ניתן להוסיף סרטון לפלייליסט של הסרטונים שהעליתם.

רוצה לנסות?

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