Videos: list

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

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

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

בקשה

בקשת HTTP

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

פרמטרים

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

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

אם הפרמטר מזהה נכס שמכיל נכסי צאצא, מאפייני הצאצאים ייכללו בתגובה. לדוגמה, במשאב video, המאפיין snippet מכיל את הנכסים channelId, title, description, tags ו-categoryId. לכן, אם מגדירים part=snippet, תגובת ה-API תכלול את כל המאפיינים האלה.

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

הערכים הקבילים הם:
id string
הפרמטר id מציין רשימה מופרדת בפסיקים של מזהי הווידאו ב-YouTube של המשאבים שמאוחזרים. במשאב video, המאפיין id מציין את מזהה הסרטון.
myRating string
ניתן להשתמש בפרמטר הזה רק במסגרת בקשה מורשית תקינה. יש להגדיר את ערך הפרמטר הזה ל-like או ל-dislike כדי להורות ל-API להחזיר רק סרטונים שסומנו בלייק או בדיסלייק על ידי המשתמש המאומת.

הערכים הקבילים הם:
  • dislike – מחזירה רק סרטונים שהמשתמש המאומת לא אהבו.
  • like – מחזיר רק סרטונים שסומנו בלייק על ידי המשתמש המאומת.
פרמטרים אופציונליים
hl string
הפרמטר hl מורה ל-API לאחזר מטא-נתונים של משאבים מותאמים לשוק המקומי בשפת אפליקציה ספציפית שנתמכת באתר YouTube. ערך הפרמטר חייב להיות קוד שפה שנכלל ברשימה שמוחזרת באמצעות השיטה i18nLanguages.list.

אם פרטי המשאב המותאמים לשוק המקומי זמינים בשפה הזו, האובייקט snippet.localized של המשאב יכלול את הערכים המותאמים לשוק המקומי. עם זאת, אם אין פרטים שמותאמים לשוק המקומי, האובייקט snippet.localized יכיל את פרטי המשאב בשפת ברירת המחדל של המשאב.
maxHeight unsigned integer
הפרמטר maxHeight מציין את הגובה המקסימלי של הנגן המוטמע שהוחזר במאפיין player.embedHtml. ניתן להשתמש בפרמטר זה כדי לציין שבמקום מאפייני ברירת המחדל, קוד ההטמעה צריך להשתמש בגובה המתאים לפריסת האפליקציה. אם מוסיפים גם את הפרמטר maxWidth, יכול להיות שהנגן יהיה קצר יותר מהנגן maxHeight כדי לא להפר את הרוחב המקסימלי. הערכים הקבילים הם 72 עד 8192, כולל.
maxResults unsigned integer
הפרמטר maxResults מציין את מספר הפריטים המקסימלי שצריך להחזיר בקבוצת התוצאות.

הערה: אפשר להשתמש בפרמטר הזה בשילוב עם הפרמטר myRating, אבל הוא לא נתמך לשימוש בשילוב עם הפרמטר id. הערכים הקבילים הם 1 עד 50, כולל. ערך ברירת המחדל הוא 5.
maxWidth unsigned integer
הפרמטר maxWidth מציין את הרוחב המקסימלי של הנגן המוטמע שהוחזר במאפיין player.embedHtml. אפשר להשתמש בפרמטר הזה כדי לציין שבמקום מאפייני ברירת המחדל, קוד ההטמעה צריך להיות ברוחב שמתאים לפריסת האפליקציה.

אם מוסיפים גם את הפרמטר maxHeight, יכול להיות שהנגן יהיה צר יותר מ-maxWidth כדי לא להפר את הגובה המקסימלי. הערכים הקבילים הם 72 עד 8192, כולל.
onBehalfOfContentOwner string
ניתן להשתמש בפרמטר הזה רק במסגרת בקשה מורשית תקינה. הערה: הפרמטר הזה מיועד אך ורק לשותפי תוכן של YouTube.

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

הערה: הפרמטר הזה נתמך לשימוש בשילוב עם הפרמטר myRating, אך אין תמיכה בו בשילוב עם הפרמטר id.
regionCode string
הפרמטר regionCode מורה ל-API לבחור תרשים וידאו שזמין באזור שצוין. אפשר להשתמש בפרמטר הזה רק בשילוב עם הפרמטר chart. ערך הפרמטר הוא קוד מדינה לפי תקן ISO 3166-1 alpha-2.
videoCategoryId string
הפרמטר videoCategoryId מזהה את קטגוריית הסרטון שעבורה יש לאחזר את התרשים. אפשר להשתמש בפרמטר הזה רק בשילוב עם הפרמטר chart. כברירת מחדל, התרשימים אינם מוגבלים לקטגוריה מסוימת. ערך ברירת המחדל הוא 0.

גוף הבקשה

אין לציין את גוף הבקשה בקריאה לשיטה הזו.

תשובה

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

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

תכונות

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

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

שגיאות

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

סוג השגיאה פרטי השגיאה תיאור
badRequest (400) videoChartNotFound תרשים הווידאו המבוקש לא נתמך או שאינו זמין.
forbidden (403) forbidden לבקשה אין הרשאה מתאימה לגשת לקובץ הווידאו או למידע לעיבוד. חשוב לשים לב שהחלקים fileDetails, processingDetails ו-suggestions זמינים רק לבעלים של הסרטון.
forbidden (403) forbidden הבקשה לא יכולה לגשת למידע על דירוגי משתמשים. יכול להיות שהשגיאה הזו מתרחשת כי הבקשה לא מורשית להשתמש כראוי בפרמטר myRating.
notFound (404) videoNotFound לא ניתן למצוא את הסרטון שאתם מנסים לאחזר. צריך לבדוק את ערך הפרמטר id של הבקשה כדי לוודא שהוא נכון.

רוצה לנסות?

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