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

מבוא

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

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

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

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

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

    1. נכנסים אל API Console ובוחרים את הפרויקט שרשמתם.
    2. נכנסים אל הדף Enabled APIs. ברשימת ממשקי ה-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 מזהה משאב, כמו סרטון, שכלול בפלייליסט. בנוסף, המשאב 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 Console אפשר לראות את השימוש במכסה.

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

חישוב ניצול המכסה

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

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

בטבלה Quota costs for API requests מוצגת עלות המכסה של כל שיטת 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 מוחזר משאב מסוג video שכולל שני חלקים אבל לא כולל את המאפיינים 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.

  • הגנה מפני החלפה לא מכוונת של שינויים – תגי ETag עוזרים לוודא שכמה לקוחות 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, צריך לבצע שני דברים:

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

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

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