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 Studio.

גוף הבקשה

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

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

    • id
    • snippet.playlistId
    • snippet.resourceId

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

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

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

תשובה

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

שגיאות

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

סוג השגיאה פרטי השגיאה תיאור
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 ואת התשובה.