סקירה כללית על 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.

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

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

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

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

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

ניצול המכסה

ב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 של המשאב.

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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

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