PlaylistItems: update

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

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

תרחישים נפוצים לדוגמה

בקשה

בקשת HTTP

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

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

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

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

גוף הבקשה

מציינים playlistItem resource בגוף הבקשה. במשאב הזה:

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

    • id
    • snippet.playlistId
    • snippet.resourceId

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

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

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

תשובה

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

שגיאות

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

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

רוצה לנסות?

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