Videos: list

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

השפעה על המכסה: קריאה ל-method הזה מנצלת יחידה אחת מהמכסה.

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

בקשה

בקשת 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 שאפשר לכלול בערך הפרמטר:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
מסננים (צריך לציין בדיוק אחד מהפרמטרים הבאים)
chart ‫string
הפרמטר chart מזהה את התרשים שרוצים לאחזר.

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

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



ה-API מגביל את קבוצת התוצאות שמוחזרות ל-1,000 סרטונים לכל היותר. גם אם המאפיין pageInfo.totalResults של התשובה מציין סכום כולל גבוה יותר, עימוד באמצעות הפרמטר pageToken מאפשר לאחזר רק את 1,000 הפריטים האחרונים.



הפרמטר מקבל את הערכים הבאים:

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

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

גוף הבקשה

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

תשובה

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

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

מאפיינים

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

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

שגיאות

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

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

רוצה לנסות?

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