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 מציין שפרטי הכניסה להרשאה של הבקשה מזהים משתמש CMS ב-YouTube שפועל בשם בעלי התוכן שצוין בערך הפרמטר. הפרמטר הזה מיועד לשותפי תוכן של 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.

גוף הבקשה

אין להזין גוף בקשה בעת הפעלת שיטה זו.

תשובה

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

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

נכסים

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

נכסים
kind string
מזהה את סוג המשאב של ה-API. הערך יהיה youtube#videoListResponse.
etag etag
התג של המשאב הזה.
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 ואת התשובה.