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

מבוא

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

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

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

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

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

    1. עוברים אל API Console ובוחרים את הפרויקט שרשמתם כרגע.
    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 מזהה משאב, למשל סרטון, שהוא חלק מפלייליסט. המשאב 'ItemItem מכיל גם פרטים שמסבירים את השימוש במשאב הכלול בפלייליסט.
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 תומך בשיטות לרישום כל אחד מסוגי המשאבים הנתמכים, והוא תומך גם בפעולות כתיבה למשאבים רבים.

בטבלה הבאה מפורטות הפעולות שנתמכות בסוגים שונים של משאבים. פעולות שמוסיפות, מעדכנים או מוחקים משאבים תמיד מחייבות הרשאת משתמש. במקרים מסוימים, שיטות 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 Console.

הערה: אם הגעתם למכסה, תוכלו לבקש מכסה נוספת באמצעות טופס הבקשה לתוספי מכסה לשירותי 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))

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

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

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

    ספריות הלקוח של Google APIs שונות בתמיכה שלהן ב-ETags. לדוגמה, ספריית הלקוח של 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

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

כדי לקבל תגובה בקידוד gzip, עליך לבצע שתי פעולות:

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

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

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