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

מבוא

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

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

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

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

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

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

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

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

ניצול המכסה

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

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

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

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

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

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

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