Playlists: list

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

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

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

בקשה

בקשת HTTP

GET https://www.googleapis.com/youtube/v3/playlists

פרמטרים

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

פרמטרים
פרמטרים נדרשים
part string
הפרמטר part מציין רשימה מופרדת בפסיקים של מאפיין אחד או יותר של משאב playlist שהתגובה מה-API תכלול.

אם הפרמטר מזהה מאפיין שמכיל מאפייני צאצא, מאפייני הצאצא ייכללו בתגובה. לדוגמה, במשאב playlist, המאפיין snippet מכיל מאפיינים כמו author, title, description ו-timeCreated. לכן, אם מגדירים את part=snippet, התגובה מה-API תכיל את כל המאפיינים האלה.

הרשימה הבאה מכילה את השמות של part שאפשר לכלול בערך הפרמטר:
  • contentDetails
  • id
  • localizations
  • player
  • snippet
  • status
מסננים (צריך לציין בדיוק אחד מהפרמטרים הבאים)
channelId string
הערך הזה מציין שה-API צריך להחזיר רק את הפלייליסטים של הערוץ שצוין.
id ‫string
הפרמטר id מציין רשימה מופרדת בפסיקים של מזהי הפלייליסטים ב-YouTube של המשאבים שאותם מאחזרים. במשאב playlist, המאפיין id מציין את מזהה הפלייליסט ב-YouTube.
mine boolean
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית כראוי. כדי להורות ל-API להחזיר רק פלייליסטים שנמצאים בבעלות המשתמש המאומת, צריך להגדיר את ערך הפרמטר הזה ל-true.
פרמטרים אופציונליים
hl ‫string
הפרמטר hl מורה לממשק ה-API לאחזר מטא-נתונים של משאבים שעברו לוקליזציה עבור שפת אפליקציה ספציפית שאתר YouTube תומך בה. ערך הפרמטר צריך להיות קוד שפה שמופיע ברשימה שמוחזרת על ידי השיטה i18nLanguages.list.

אם פרטי המשאב מותאמים לשוק המקומי בשפה הזו, אובייקט snippet.localized של המשאב יכיל את הערכים המותאמים. עם זאת, אם אין פרטים מותאמים לשפה המקומית, האובייקט snippet.localized יכיל פרטי משאבים בשפת ברירת המחדל של המשאב.
maxResults ‫unsigned integer
הפרמטר maxResults מציין את המספר המקסימלי של פריטים שיוחזרו בקבוצת התוצאות. הערכים הקבילים הם 0 עד 50, כולל. ערך ברירת המחדל הוא 5.
onBehalfOfContentOwner string
אפשר להשתמש בפרמטר הזה רק בבקשה מורשית. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube.

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

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

הפרמטר הזה מיועד לשותפי תוכן של YouTube שבבעלותם ובניהולם ערוצי YouTube רבים ושונים. היא מאפשרת לבעלי תוכן לבצע אימות חד-פעמי ולבצע פעולות בשם הערוץ שצוין בערך הפרמטר, בלי לספק פרטי כניסה לאימות לכל ערוץ בנפרד.
pageToken string
הפרמטר pageToken מזהה דף ספציפי בקבוצת התוצאות שצריך להחזיר. בתגובה מה-API, המאפיינים nextPageToken ו-prevPageToken מזהים דפים אחרים שאפשר לאחזר.

גוף הבקשה

אל תספקו גוף בקשה כשאתם קוראים ל-method הזו.

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-method מחזירה גוף תגובה במבנה הבא:

{
  "kind": "youtube#playlistListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    playlist Resource
  ]
}

מאפיינים

בטבלה הבאה מוגדרים המאפיינים שמופיעים במשאב הזה:

מאפיינים
kind ‫string
מזהה את סוג משאב ה-API. הערך יהיה youtube#playlistListResponse.
etag etag
ה-Etag של המשאב הזה.
nextPageToken string
האסימון שאפשר להשתמש בו כערך של הפרמטר pageToken כדי לאחזר את הדף הבא בקבוצת התוצאות.
prevPageToken string
הטוקן שאפשר להשתמש בו כערך של הפרמטר pageToken כדי לאחזר את הדף הקודם בקבוצת התוצאות.
pageInfo object
האובייקט pageInfo כולל מידע על הדפים של קבוצת התוצאות.
pageInfo.totalResults integer
המספר הכולל של התוצאות בקבוצת התוצאות.
pageInfo.resultsPerPage integer
מספר התוצאות שכלולות בתגובה מה-API.
items[] list
רשימה של פלייליסטים שתואמים לקריטריונים של הבקשה.

שגיאות

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

סוג השגיאה פרטי השגיאה תיאור
forbidden (403) channelClosed הערוץ שצוין בפרמטר channelId נסגר.
forbidden (403) channelSuspended הערוץ שצוין בפרמטר channelId הושעה.
forbidden (403) playlistForbidden הפלייליסט שזוהה באמצעות הפרמטר id של הבקשה לא תומך בבקשה, או שהבקשה לא אושרה כראוי.
notFound (404) channelNotFound לא נמצא הערוץ שצוין בפרמטר channelId.
notFound (404) playlistNotFound לא נמצאה רשימת ההשמעה שמזוהה באמצעות הפרמטר id של הבקשה.
invalidValue (400) playlistOperationUnsupported ה-API לא תומך באפשרות להציג את הפלייליסט שצוין. לדוגמה, אי אפשר להציג את הפלייליסט "לצפייה בהמשך".

רוצה לנסות?

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