סקירה כללית על YouTube Data API

מבוא

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

לפני שמתחילים

  1. יש צורך בחשבון Google כדי לגשת ל-Google API Console, לבקש מפתח API ולרשום את האפליקציה.

  2. יוצרים פרויקט ב-Google Developers Console ומקבלים פרטי כניסה להרשאה כדי שהאפליקציה תוכל לשלוח בקשות API.

  3. אחרי יצירת הפרויקט, עליכם לוודא ש-YouTube Data API הוא אחד מהשירותים שהאפליקציה שלכם רשומה לשימוש בהם:

    1. עוברים אל מסוף API ובוחרים את הפרויקט שרשמתם עכשיו.
    2. נכנסים לדף ממשקי ה-API המופעלים. ברשימת ממשקי ה-API, מוודאים שהסטטוס של YouTube Data API v3 הוא מופעל.

  4. אם האפליקציה שלך תשתמש בשיטות API שמחייבות הרשאת משתמש, מומלץ לקרוא את מדריך האימות כדי ללמוד איך להטמיע הרשאת OAuth 2.0.

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

  6. להכיר את מושגי הליבה של פורמט הנתונים JSON (JavaScript Object Notation). JSON הוא פורמט נתונים נפוץ ובלתי תלוי בשפה, שבו מבני נתונים שרירותיים מיוצגים באמצעות טקסט פשוט. מידע נוסף זמין בכתובת json.org.

משאבים וסוגי משאבים

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

משאבים
activity מכיל מידע על פעולה שמשתמש מסוים ביצע באתר YouTube. פעולות משתמש המדווחות בפידים של פעילות כוללות, בין היתר, דירוג סרטון, שיתוף סרטון, סימון סרטון כמועדף ופרסום מבזק של ערוץ.
channel מכיל מידע על ערוץ YouTube יחיד.
channelBanner מזהה את כתובת ה-URL שתשמש להגדרת תמונה שהועלתה לאחרונה כתמונת הבאנר של ערוץ.
channelSection כוללים מידע על קבוצת סרטונים שהערוץ בחר להציג. לדוגמה: קטע יכול לכלול את ההעלאות האחרונות בערוץ, את ההעלאות הפופולריות ביותר או סרטונים מפלייליסט אחד או יותר.
guideCategory מזהה קטגוריה ש-YouTube משייך לערוצים על סמך התוכן שלהם או אינדיקטורים אחרים, כמו הפופולריות. המטרה של קטגוריות המדריך היא לארגן את הערוצים באופן שמקל על משתמשי YouTube למצוא את התוכן שהם מחפשים. אפשר לשייך ערוצים לקטגוריה אחת או יותר של מדריכים, אבל לא בטוח שהם ישויכו לאף אחת מקטגוריות המדריכים.
i18nLanguage מזהה שפה של אפליקציה שנתמכת באתר YouTube. אפשר לקרוא לשפת האפליקציה גם שפת ממשק משתמש.
i18nRegion מזהה אזור גיאוגרפי שמשתמש YouTube יכול לבחור כאזור התוכן המועדף. אפשר להתייחס לאזור התוכן גם כלוקאל של תוכן.
playlist מייצג פלייליסט אחד ב-YouTube. פלייליסט הוא אוסף של סרטונים שניתן לצפות בהם ברצף ולשתף עם משתמשים אחרים.
playlistItem מזהה משאב, כמו סרטון, שהוא חלק מפלייליסט. המשאב 'פריט פלייליסט' מכיל גם פרטים שמסבירים איך להשתמש במשאב שכלול בפלייליסט.
search result מכיל מידע על סרטון, ערוץ או פלייליסט ב-YouTube שתואם לפרמטרים של החיפוש שצוינו בבקשת API. תוצאת חיפוש מפנה אל משאב שניתן לזהות אותו באופן ייחודי, כמו סרטון, אבל אין לה נתונים קבועים משלה.
subscription מכיל מידע על המינוי של משתמש YouTube. מינוי מודיע למשתמש כאשר סרטונים חדשים מתווספים לערוץ, או כאשר משתמש אחר מבצע אחת מכמה פעולות ב-YouTube, כמו העלאת סרטון, דירוג סרטון או הוספת תגובה לסרטון.
thumbnail מזהה תמונות ממוזערות שמשויכות למשאב.
video מייצג סרטון אחד ב-YouTube.
videoCategory מזהה קטגוריה ששויכה או יכולה להיות משויכת לסרטונים שהועלו.
watermark מזהה תמונה שמוצגת במהלך הפעלת סרטונים בערוץ מסוים. בנוסף, הבעלים של הערוץ יכולים לציין ערוץ יעד שאליו התמונה מקשרת, וכן פרטי תזמון שיקבעו מתי סימן המים יופיע במהלך הפעלת סרטונים, ומתי הוא יהיה גלוי.

שימו לב: במקרים רבים משאב מכיל הפניות למשאבים אחרים. לדוגמה, המאפיין snippet.resourceId.videoId של משאב playlistItem מזהה משאב וידאו, שבתורו מכיל את כל המידע על הסרטון. דוגמה נוספת: תוצאת חיפוש מכילה נכס videoId, playlistId או channelId שמזהה משאב מסוים של סרטון, פלייליסט או ערוץ.

פעולות נתמכות

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

תפעול
list אחזור (GET) רשימה של אפס משאבים או יותר.
insert יוצר (POST) משאב חדש.
update שינוי (PUT) משאב קיים כדי לשקף נתונים בבקשה שלך.
delete מתבצעת הסרה (DELETE) של משאב ספציפי.

ה-API תומך כרגע ב-methods להצגת רשימה של כל סוגי המשאבים הנתמכים, והוא תומך גם בפעולות כתיבה במשאבים רבים.

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

פעולות נתמכות
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

ניצול המכסה

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

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

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

מתבצע חישוב של השימוש במכסות

Google מחשבת את השימוש במכסה על ידי הקצאת עלות לכל בקשה. סוגים שונים של לפעולות יש עלויות מכסות שונות. לדוגמה:

  • פעולת קריאה שמאחזרת רשימת משאבים (ערוצים, סרטונים, פלייליסטים) בדרך כלל עולה יחידה אחת.
  • פעולת כתיבה שיוצרת, מעדכנת או מוחקת משאב בדרך כלל כרוכה בעלויות 50 יחידות.
  • בקשת חיפוש עולה 100 יחידות.
  • עלות העלאת סרטון היא 1600 יחידות.

בטבלה Quota costs לבקשות API מוצג המכסה של כל שיטת API. תוך התחשבות בכללים האלה, תוכלו להעריך את מספר הבקשות שהאפליקציה שלכם יכולה לשלוח ביום מבלי לחרוג מהמכסה שלכם.

משאבים חלקיים

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

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

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

איך משתמשים בפרמטר part

הפרמטר part הוא פרמטר נדרש לכל בקשת API שמאחזרת או מחזירה משאב. הפרמטר מזהה מאפיין אחד או יותר של משאב ברמה העליונה (לא בתצוגת עץ) שצריך לכלול בתגובת ה-API. לדוגמה, משאב video כולל את החלקים הבאים:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

כל החלקים האלה הם אובייקטים שמכילים מאפיינים מקוננים, ואפשר להתייחס לאובייקטים האלה כקבוצות של שדות מטא-נתונים ששרת ה-API עשוי (או לא יכול) לאחזר. לכן, הפרמטר part מחייב אתכם לבחור את רכיבי המשאבים שהאפליקציה שלכם משתמשת בהם בפועל. לדרישה הזו יש שתי מטרות עיקריות:

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

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

איך משתמשים בפרמטר fields

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

הכללים הבאים מסבירים את התחביר הנתמך של ערך הפרמטר fields, שמבוסס באופן חלש על תחביר XPath:

  • צריך להשתמש ברשימה שמופרדת בפסיקים (fields=a,b) כדי לבחור כמה שדות.
  • אפשר להשתמש בכוכבית (fields=*) כתו כללי לחיפוש כדי לזהות את כל השדות.
  • משתמשים בסוגריים (fields=a(b,c)) כדי לציין קבוצה של מאפיינים מקוננים שייכלל בתגובת ה-API.
  • צריך להשתמש בקו נטוי לפנים (fields=a/b) כדי לזהות מאפיין מקונן.

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

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

הערה: בדומה לכל ערכי הפרמטרים של שאילתה, ערך הפרמטר fields חייב להיות מקודד בכתובת ה-URL. כדי לשפר את הקריאות, הדוגמאות במסמך הזה לא כוללות את הקידוד.

דוגמאות לבקשות חלקיות

הדוגמאות הבאות ממחישות איך אפשר להשתמש בפרמטרים part ו-fields כדי להבטיח שתגובות ה-API יכללו רק את הנתונים שהאפליקציה שלכם משתמשת בהם:

  1. דוגמה 1 מחזירה משאב וידאו שכולל ארבעה חלקים וכן מאפיינים kind ו-etag.
  2. דוגמה 2 מחזירה משאב וידאו שכולל שני חלקים וגם את המאפיינים kind ו-etag.
  3. דוגמה 3 מחזירה משאב וידאו שכולל שני חלקים, אבל לא כולל את הנכסים kind ו-etag.
  4. דוגמה 4 מחזירה משאב וידאו שכולל שני חלקים, אבל לא כולל את kind ואת etag, וכן חלק מהמאפיינים שהוצבו באובייקט snippet של המשאב.
דוגמה 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
דוגמה 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
דוגמה 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
דוגמה 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

מתבצעת אופטימיזציה של הביצועים

שימוש ב-ETags

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

  • שמירה במטמון ואחזור מותנה – האפליקציה יכולה לשמור במטמון משאבי API ואת ה-ETags שלהם. לאחר מכן, כשהאפליקציה מבקשת שוב משאב מאוחסן, היא מציינת את ה-ETag שמשויך למשאב הזה. אם המשאב השתנה, ה-API יחזיר את המשאב שהשתנה ואת ה-ETag שמשויך לגרסת המשאב הזו. אם המשאב לא השתנה, ה-API יחזיר תגובת HTTP 304 (Not Modified), שמציינת שהמשאב לא השתנה. האפליקציה יכולה להפחית את זמן האחזור ואת השימוש ברוחב הפס על ידי הצגת משאבים שנשמרו במטמון באופן הזה.

    התמיכה ב-ETags משתנה בין ספריות הלקוח ל-Google APIs. לדוגמה, ספריית הלקוח של JavaScript תומכת ב-ETags באמצעות רשימת היתרים של כותרות בקשות מורשות שכוללות את If-Match ואת If-None-Match. רשימת ההיתרים מאפשרת שמירה רגילה במטמון של הדפדפן, כך שאם ה-ETag של משאב לא השתנה, ניתן יהיה להציג את המשאב מהמטמון של הדפדפן. לעומת זאת, לקוח Obj-C לא תומך ב-ETags.

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

לשימוש ב-ETags באפליקציה יש מספר יתרונות:

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

Google APIs Client Library for JavaScript תומך בכותרות בקשת HTTP If-Match ו-If-None-Match, ובכך מאפשר ETags לעבוד בהקשר של שמירה רגילה במטמון הדפדפן.

שימוש ב-gzip

אפשר גם לצמצם את רוחב הפס הדרוש לכל תגובת API על ידי הפעלת דחיסת נתונים מסוג gzip. לאפליקציה שלכם נדרש זמן CPU (מעבד) נוסף כדי לבטל את הדחיסה של תגובות API, אבל היתרון של שימוש בפחות משאבי רשת בדרך כלל גדול יותר מהעלות הזו.

כדי לקבל תגובה המקודדת ב-gzip, עליכם לעשות שני דברים:

  • צריך להגדיר את הכותרת Accept-Encoding של בקשת ה-HTTP ל-gzip.
  • צריך לשנות את סוכן המשתמש כך שיכלול את המחרוזת gzip.

כותרות ה-HTTP לדוגמה שבהמשך מדגימות את הדרישות הבאות להפעלת דחיסת נתונים מסוג gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)