מבוא
המסמך הזה מיועד למפתחים שרוצים לכתוב אפליקציות שיוצרות אינטראקציה עם YouTube. המדריך כולל הסברים על העקרונות הבסיסיים של YouTube ועל ממשק ה-API עצמו. כמו כן, מוצגת סקירה כללית של הפונקציות השונות שבהן ה-API תומך.
לפני שמתחילים
-
יש צורך בחשבון Google כדי לגשת למסוף Google API, לבקש מפתח API ולרשום את האפליקציה.
-
יוצרים פרויקט ב-Google Developers Console ומשיגים פרטי כניסה להרשאה כדי שהאפליקציה תוכל לשלוח בקשות API.
-
לאחר יצירת הפרויקט, ודאו ש-YouTube Data API הוא אחד השירותים שבהם האפליקציה רשומה:
- עוברים אל API Console ובוחרים את הפרויקט שרשמתם כרגע.
- נכנסים לדף ממשקי API מופעלים. ברשימת ממשקי ה-API, מוודאים שהסטטוס של YouTube Data API v3 הוא מופעל.
-
אם באפליקציה ייעשה שימוש בשיטות API שמחייבות הרשאת משתמש, כדאי לקרוא את המדריך לאימות כדי ללמוד איך להטמיע הרשאה באמצעות OAuth 2.0.
-
כדי לפשט את הטמעת ה-API, צריך לבחור ספריית לקוח.
-
ללמוד את המושגים הבסיסיים של פורמט הנתונים 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 מחזירה משאב וידאו שכולל ארבעה חלקים וגם את המאפיינים
kind
ו-etag
. - דוגמה 2 מחזירה משאב וידאו שכולל שני חלקים וגם את הנכסים
kind
ו-etag
. - דוגמה 3 מחזירה משאב וידאו שכולל שני חלקים, אבל לא כולל את הנכסים
kind
ו-etag
. - דוגמה 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 avideo
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 thepart
parameter value so that thecontentDetails
andstatus
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 thefields
parameter to remove allkind
andetag
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 thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
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)