API Reference

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

במדריך הזה מוסבר איך להשתמש ב-API כדי לבצע את כל הפעולות האלה. המדריך מאורגן לפי סוג המשאב. מקור מידע מייצג סוג של פריט שמהווה חלק מחוויית השימוש ב-YouTube, כמו סרטון, פלייליסט או מינוי. לכל סוג משאב, המדריך מפרט ייצוג נתונים אחד או יותר, והמשאבים מיוצגים כאובייקטים בפורמט JSON. במדריך מפורטות גם שיטה אחת או יותר נתמכות (LIST, ‏ POST, ‏ DELETE וכו') לכל סוג משאב, ומוסבר איך להשתמש בשיטות האלה באפליקציה.

שליחת קריאה ל-API

הדרישות הבאות חלות על בקשות ל-YouTube Data API:

  1. בכל בקשה צריך לציין מפתח API (באמצעות הפרמטר key) או לספק טוקן OAuth 2.0. מפתח ה-API זמין בחלונית API Access (גישת API) בDeveloper Console של הפרויקט.

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

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

  3. ממשק ה-API תומך בפרוטוקול האימות OAuth 2.0. אפשר לספק אסימון OAuth 2.0 באחת מהדרכים הבאות:

    • משתמשים בפרמטר השאילתה access_token כך: ?access_token=oauth2-token
    • משתמשים בכותרת HTTP Authorization באופן הבא: Authorization: Bearer oauth2-token

    הוראות מלאות להטמעת אימות OAuth 2.0 באפליקציה זמינות במדריך האימות.

סוגי המשאבים

פעילויות

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

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /activities הפונקציה מחזירה רשימה של אירועי פעילות בערוץ שתואמים לקריטריונים של הבקשה. לדוגמה, אפשר לאחזר אירועים שמשויכים לערוץ מסוים או לערוץ של המשתמש עצמו.

כתוביות

משאב caption מייצג רצועת כתוביות ב-YouTube. כל רצועת כתוביות משויכת לסרטון אחד בלבד ב-YouTube.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
delete DELETE /captions מחיקת רצועת הכתוביות שצוינה.
download GET /captions/id הורדה של רצועת כתוביות. רצועת הכתוביות מוחזרת בפורמט המקורי שלה, אלא אם הבקשה מציינת ערך לפרמטר tfmt, ובשפה המקורית שלה, אלא אם הבקשה מציינת ערך לפרמטר tlang.
insert POST /captions העלאה של רצועת כתוביות.
list GET /captions מחזירה רשימה של רצועות כתוביות שמשויכות לסרטון שצוין. תגובת ה-API לא מכילה את הכתוביות בפועל, ושיטת captions.download מאפשרת לאחזר רצועת כתוביות.
update PUT /captions עדכון של רצועת כתוביות. כשמעדכנים רצועת כתוביות, אפשר לשנות את סטטוס הטיוטה של הרצועה, להעלות קובץ כתוביות חדש לרצועה או לעשות את שתי הפעולות.

ChannelBanners

channelBanner משאב מכיל את כתובת ה-URL שבה משתמשים כדי להגדיר תמונה שהועלתה לאחרונה כתמונת הבאנר של הערוץ.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
insert POST /channelBanners/insert מעלה תמונת באנר של ערוץ ל-YouTube. השיטה הזו מייצגת את שני השלבים הראשונים בתהליך של שלושה שלבים לעדכון תמונת הבאנר של ערוץ:
  1. מבצעים קריאה ל-channelBanners.insert כדי להעלות את נתוני התמונה הבינאריים ל-YouTube. התמונה צריכה להיות ביחס גובה-רוחב של 16:9 ובגודל של ‎2048x1152 פיקסלים לפחות. מומלץ להעלות תמונה בגודל 2560x1440 פיקסלים.
  2. מחפשים בתשובה שה-API מחזיר לשלב 1 את הערך של המאפיין url.
  3. קוראים לשיטה channels.update כדי לעדכן את הגדרות המיתוג של הערוץ. מגדירים את הערך של המאפיין brandingSettings.image.bannerExternalUrl לכתובת ה-URL שהתקבלה בשלב 2.

ChannelSections

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

הקטעים של הערוץ גלויים רק אם התוכן של הערוץ מוצג בתצוגת עיון (ולא בתצוגת פיד). כדי לאפשר לערוץ להציג תוכן בתצוגת דפדוף, צריך להגדיר את המאפיין brandingSettings.channel.showBrowseView לערך true עבור הערוץ שצוין.

כל ערוץ יכול ליצור עד 10 מדפים.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
delete DELETE /channelSections מחיקת קטע בערוץ.
insert POST /channelSections הפעולה מוסיפה קטע לערוץ של המשתמש המאומת. כל ערוץ יכול ליצור עד 10 מדפים.
list GET /channelSections הפונקציה מחזירה רשימה של משאבי channelSection שתואמים לקריטריונים של בקשת ה-API.
update PUT /channelSections עדכון של קטע בערוץ.

ערוצים

משאב channel מכיל מידע על ערוץ YouTube.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /channels מחזירה אוסף של אפס או יותר משאבי channel שתואמים לקריטריוני הבקשה.
update PUT /channels עדכון המטא-נתונים של ערוץ. השיטה הזו תומכת רק בעדכונים של אובייקטים מסוג channel ו-brandingSettings במשאב invideoPromotion ושל מאפייני הצאצא שלהם.

CommentThreads

commentThread משאב מכיל מידע על שרשור תגובות ב-YouTube, שכולל תגובה ברמה העליונה ותגובות, אם יש כאלה, לתגובה הזו. commentThread משאב יכול לייצג תגובות על סרטון או על ערוץ.

גם התגובה ברמה העליונה וגם התשובות הן למעשה משאבי comment שמוטמעים בתוך משאב commentThread. יכול להיות שהמשאב commentThread לא יכיל את כל התשובות לתגובה, ותצטרכו להשתמש בשיטה comments.list אם אתם רוצים לאחזר את כל התשובות לתגובה מסוימת. בנוסף, לחלק מההערות אין תשובות.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /commentThreads מחזירה רשימה של שרשורי תגובות שתואמים לפרמטרים של בקשת ה-API.
insert POST /commentThreads יצירת תגובה חדשה ברמה העליונה. כדי להוסיף תשובה לתגובה קיימת, צריך להשתמש בשיטה comments.insert.

תגובות

משאב comment מכיל מידע על תגובה אחת ב-YouTube. משאב comment יכול לייצג תגובה על סרטון או על ערוץ. בנוסף, התגובה יכולה להיות תגובה ברמה העליונה או תשובה לתגובה ברמה העליונה.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /comments מחזירה רשימה של תגובות שתואמות לפרמטרים של בקשת ה-API.
setModerationStatus POST /comments/setModerationStatus הגדרת סטטוס ניהול של תגובה אחת או יותר. הבקשה ל-API צריכה להיות מאושרת על ידי הבעלים של הערוץ או הסרטון שאליהם משויכות התגובות.
insert POST /comments יצירת תשובה לתגובה קיימת. הערה: כדי ליצור תגובה ברמה העליונה, משתמשים בשיטה commentThreads.insert.
delete DELETE /comments מחיקת תגובה.
update PUT /comments שינוי תגובה.

I18nLanguages

משאב i18nLanguage מציין את שפת האפליקציה שאתר YouTube תומך בה. שפת האפליקציה נקראת גם שפת ממשק המשתמש. באתר YouTube, שפת האפליקציה יכולה להיבחר באופן אוטומטי על סמך ההגדרות בחשבון Google, שפת הדפדפן או המיקום לפי כתובת ה-IP. משתמשים יכולים גם לבחור ידנית את שפת ממשק המשתמש בכותרת התחתונה של האתר של YouTube.

כל משאב i18nLanguage מזהה קוד שפה ושם. אפשר להשתמש בקוד השפה כערך של הפרמטר hl כשקוראים ל-API methods כמו videoCategories.list.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /i18nLanguages הפונקציה מחזירה רשימה של שפות אפליקציה שאתר YouTube תומך בהן.

I18nRegions

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

כל משאב i18nRegion מזהה קוד אזור ושם. אפשר להשתמש בקוד האזור כערך של הפרמטר regionCode כשקוראים לשיטות API כמו search.list,‏ videos.list,‏ activities.list ו-videoCategories.list.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /i18nRegions הפונקציה מחזירה רשימה של אזורים שבהם יש תוכן באתר YouTube.

חברי מועדון

משאב member מייצג חבר מועדון בערוץ YouTube. חברי המועדון תומכים ביוצרים באופן כספי קבוע ומקבלים הטבות מיוחדות. לדוגמה, חברי המועדון יכולים לשוחח בצ'אט כשהיוצר מפעיל את המצב 'צ'אט לחברי מועדון בלבד'.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /members רשימת חברי המועדון (לשעבר 'ספונסרים') של ערוץ מסוים. הבקשה ל-API חייבת להיות מאושרת על ידי הבעלים של הערוץ.

MembershipsLevels

משאב membershipsLevel מזהה רמת תמחור ליוצר שאישר את בקשת ה-API.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /membershipsLevels הפונקציה מחזירה אוסף של אפס או יותר משאבי membershipsLevel שנמצאים בבעלות הערוץ שאישר את בקשת ה-API. הרמות מוחזרות בסדר תצוגה מרומז.

PlaylistItems

משאב playlistItem מזהה משאב אחר, כמו סרטון, שנכלל בפלייליסט. בנוסף, המשאב playlistItem מכיל פרטים על המשאב הכלול שקשורים באופן ספציפי לאופן השימוש במשאב הזה בפלייליסט.

מערכת YouTube משתמשת גם בפלייליסט כדי לזהות את רשימת הסרטונים שהועלו לערוץ. כל פריט playlistItem ברשימה הזו מייצג סרטון שהועלה. אפשר לאחזר את מזהה הפלייליסט של הרשימה הזו מתוך channel resource של ערוץ מסוים. אחר כך אפשר להשתמש ב-method‏ playlistItems.list כדי לאחזר את הרשימה.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
delete DELETE /playlistItems מחיקת פריט בפלייליסט.
insert POST /playlistItems הוספת מקור לפלייליסט.
list GET /playlistItems הפונקציה מחזירה אוסף של פריטים בפלייליסט שתואמים לפרמטרים של בקשת ה-API. אפשר לאחזר את כל הפריטים בפלייליסט מסוים, או לאחזר פריט אחד או יותר בפלייליסט לפי המזהים הייחודיים שלהם.
update PUT /playlistItems שינוי פריט בפלייליסט. לדוגמה, אפשר לעדכן את המיקום של הפריט בפלייליסט.

פלייליסטים

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

מערכת YouTube משתמשת גם בפלייליסטים כדי לזהות אוספים מיוחדים של סרטונים בערוץ, כמו:

  • סרטונים שהועלו
  • סרטונים שקיבלו דירוג חיובי (אהבתי)
  • היסטוריית צפייה
  • לצפייה בהמשך

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

לאחר מכן תוכלו להשתמש בשיטה playlistItems.list כדי לאחזר כל אחת מהרשימות האלה. אפשר גם להוסיף פריטים לרשימות האלה או להסיר מהן פריטים באמצעות הקריאה לשיטות playlistItems.insert ו-playlistItems.delete.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
delete DELETE /playlists מחיקת פלייליסט.
list GET /playlists הפונקציה מחזירה אוסף של פלייליסטים שתואמים לפרמטרים של בקשת ה-API. לדוגמה, אפשר לאחזר את כל הפלייליסטים שבבעלות המשתמש המאומת, או לאחזר פלייליסט אחד או יותר לפי המזהים הייחודיים שלהם.
insert POST /playlists יצירת פלייליסט.
update PUT /playlists שינוי של פלייליסט. לדוגמה, אפשר לשנות את השם, התיאור או סטטוס הפרטיות של פלייליסט.

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

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /search הפונקציה מחזירה אוסף של תוצאות חיפוש שתואמות לפרמטרים של השאילתה שצוינו בבקשת ה-API. כברירת מחדל, קבוצת תוצאות החיפוש מזהה משאבים תואמים מסוג video, channel ו-playlist, אבל אפשר גם להגדיר שאילתות כך שיאחזרו רק סוג מסוים של משאב.

מינויים

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

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
delete DELETE /subscriptions מחיקת מינוי.
insert POST /subscriptions הוספת מינוי לערוץ של המשתמש המאומת.
list GET /subscriptions הפונקציה מחזירה משאבי מינוי שתואמים לקריטריונים של בקשת ה-API.

תמונות ממוזערות

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

  • המאפיין snippet.thumbnails של משאב הוא אובייקט שמזהה את התמונות הממוזערות שזמינות למשאב הזה.
  • משאב thumbnail מכיל סדרה של אובייקטים. השם של כל אובייקט (default,‏ medium,‏ high וכו') מתייחס לגודל התמונה הממוזערת.
  • יכול להיות שסוגים שונים של נכסים יתמכו בגדלים שונים של תמונות ממוזערות.
  • יכול להיות שסוגים שונים של משאבים יגדירו גדלים שונים לתמונות ממוזערות עם אותו שם. לדוגמה, התמונה הממוזערת default של משאב video היא בדרך כלל בגודל ‎120x90 פיקסלים, והתמונה הממוזערת default של משאב channel היא בדרך כלל בגודל ‎88x88 פיקסלים.
  • יכול להיות שלתמונות מסוימות יהיו גדלים שונים של תמונות ממוזערות, בהתאם לרזולוציה של התמונה המקורית או של התוכן שהועלה ל-YouTube. לדוגמה, יכול להיות שסרטון באיכות HD יתמוך בתמונות ממוזערות ברזולוציה גבוהה יותר מאשר סרטונים שלא באיכות HD.
  • לכל אובייקט שמכיל מידע על גודל תמונה ממוזערת יש מאפיין width ומאפיין height. עם זאת, יכול להיות שהמאפיינים של הרוחב והגובה לא יוחזרו עבור התמונה הזו.
  • אם תמונה ממוזערת שהועלתה לא תואמת למידות הנדרשות, המערכת משנה את הגודל של התמונה כך שתתאים לגודל הנכון בלי לשנות את יחס הגובה-רוחב שלה. התמונה לא חתוכה, אבל יכול להיות שהיא כוללת פסים שחורים כדי שהגודל שלה יהיה נכון.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
set POST /thumbnails/set מעלה תמונה ממוזערת מותאמת אישית של סרטון ל-YouTube ומגדיר אותה לסרטון.

VideoAbuseReportReasons

videoAbuseReportReason משאב מכיל מידע על הסיבה לסימון סרטון כסרטון שמכיל תוכן פוגעני. כשהאפליקציה שלכם קוראת לשיטה videos.reportAbuse כדי לדווח על סרטון פוגע, הבקשה משתמשת במידע ממקור videoAbuseReportReason כדי לזהות את הסיבה לדיווח על הסרטון.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /videoAbuseReportReasons אחזור רשימת הסיבות שאפשר להשתמש בהן כדי לדווח על סרטונים פוגעניים.

VideoCategories

משאב videoCategory מזהה קטגוריה ששויכה לסרטונים שהועלו או שאפשר לשייך לה סרטונים שהועלו.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
list GET /videoCategories מחזירה רשימה של קטגוריות שאפשר לשייך לסרטונים ב-YouTube.

סרטונים

מקור מידע video מייצג סרטון ב-YouTube.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
insert POST /videos העלאת סרטון ל-YouTube והגדרת המטא-נתונים של הסרטון (אופציונלי).
list GET /videos הפונקציה מחזירה רשימה של סרטונים שתואמים לפרמטרים של בקשת ה-API.
delete DELETE /videos מחיקת סרטון ב-YouTube.
update PUT /videos עדכון המטא-נתונים של סרטון.
rate POST /videos/rate להוסיף דירוג של לייק או דיסלייק לסרטון או להסיר דירוג מסרטון.
getRating GET /videos/getRating מאחזר את הדירוגים שהמשתמש המורשה נתן לרשימה של סרטונים ספציפיים.
reportAbuse POST /videos/reportAbuse דיווח על סרטון שמכיל תוכן פוגע.

סימני מים

משאב watermark מזהה תמונה שמוצגת במהלך הפעלת סרטונים של ערוץ מסוים. אפשר גם לציין ערוץ יעד שאליו התמונה תקושר, ופרטים לגבי התזמון שיקבעו מתי סימן המים יופיע במהלך הפעלת הסרטונים וכמה זמן הוא יהיה גלוי.

מידע נוסף על המשאב הזה זמין בייצוג המשאב וברשימת המאפיינים שלו.

שיטה בקשת HTTP תיאור
מזהי URI יחסיים ל-https://www.googleapis.com/youtube/v3
set POST /watermarks/set מעלה תמונה של סימן מים ל-YouTube ומגדיר אותה לערוץ.
unset POST /watermarks/unset מחיקת תמונה של סימן מים בערוץ.