בקשות API לדוגמה

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

מידע על העלאה של תוכן באמצעות ה-API של YouTube Data זמין במאמר העלאות שניתנות לחידוש.

סקירה כללית

לצורך הבהרה, המצגת בדף מציגה את הרכיבים הייחודיים של כל בקשה וקיצור כתובת ה-URL הבסיסית של המארח שמעבד בקשות ל-Data API (https://www.googleapis.com/youtube/v3). כדי להגיש את הבקשה מחוץ להקשר של הדוגמאות, יש לכלול את כתובת ה-URL המלאה.

לדוגמה, זוהי בקשה לדוגמה כפי שהיא מופיעה בדף זה:

GET {base-URL}/channels?part=contentDetails
                       &mine=true

כתובת ה-URL המלאה של הבקשה הזו היא:

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

חלק מהבקשות מאחזרות נתונים שנגישים רק לבעלים של ערוץ YouTube, למשל רשימת המנויים. בקשות אלה מחייבות את בעלי הערוץ להעניק ל-Google APIs Explorer זכות לבצע בקשות YouTube Data API בשמם. (למידע נוסף על מתן הרשאת גישה לנתונים פרטיים של הערוץ, אפשר לעיין במאמר הטמעה של אימות OAuth 2.0). לאחר הקישור ל-APIs Explorer, לוחצים על הלחצן אישור בקשות באמצעות OAuth 2.0. שלב זה מעניק הרשאה ל-APIs Explorer לשלוח בקשות בשם הבעלים. בנוסף, צריך לבחור את היקף ההרשאה שמציין את סוגי הבקשות שה-APIs Explorer יכול לבצע.

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

• תקציר
• פרטי תוכן
• שחקן
• סטטיסטיקה
• סטטוס

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

אחזור פרטי ערוץ

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

GET {base_URL}/channels?part=contentDetails
                       &mine=true

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

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

סרטונים שהועלו ופלייליסטים שנוצרו על ידי המערכת

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

לפני ביצוע הבקשה הבאה לדוגמה ב-Google APIs Explorer, יש להחליף את {UPLOADS_PLAYLIST_ID} במזהה הפלייליסט מהבקשה הקודמת.

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

לתשומת ליבכם, הערך "id" של כל פריט שמוחזר הוא מזהה הפריט של הפלייליסט. מזהה הסרטון של הפריט בפלייליסט הוא videoId בחלק contentDetails.

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

פלייליסטים שנוצרו על ידי משתמשים

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

GET {base_URL}/playlists?part=snippet
                        &mine=true

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

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

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

אחזור מינויים

משאב subscription מגדיר קשר גומלין בין משתמש YouTube (המנוי) לבין ערוץ. השיטה subscriptions.list מאחזרת את המנויים לערוץ מסוים או למינויים של משתמש מסוים, בהתאם לפרמטרים שאתם כוללים בבקשה.

מנויים לערוץ

הבקשה הזו מאחזרת רשימה של המנויים לערוץ המאומת.

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

מינויים של משתמשים

ניתן להשתמש באותה שיטה שבה רשומים מנויים (subscriptions.list) כדי לפרט את הערוצים שאליהם משתמש נרשם. הבקשה הזו משתמשת בפרמטר mine כדי לאחזר רשימה של ערוצי YouTube שהמשתמש המאומת נרשם אליהם.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

אחזור של פעילות משתמשים

משאב activity מכיל מידע על פעולה שערוץ או משתמש מסוימים ביצעו ב-YouTube: העלאת סרטון, הרשמה לערוץ וכו'. השיטה activities.list מאחזרת את הפעולות המשויכות לערוץ או למשתמש שתואמים לקריטריוני הבקשה. לדוגמה, תוכלו לאחזר פעולות המשויכות לערוץ מסוים, למינויים של המשתמש או לדף הבית המותאם אישית של המשתמש ב-YouTube.

פעילות במהלך תקופת זמן נתונה

בקשה זו מאחזרת את כל הפעולות שהמשתמש המאומת ביצע במהלך אפריל 2013.

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

פעילות בדף הבית

בקשה זו מאחזרת את פיד הפעילות המותאם אישית שמוצג בדף הבית של המשתמש המאומת ב-YouTube. 

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

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

חיפוש

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

כמו בקשות אחרות של YouTube Data API, השיטה search.list מחזירה את ייצוג ה-JSON של משאב ב-YouTube. עם זאת, בניגוד למשאבים אחרים של YouTube, תוצאת חיפוש היא לא אובייקט קבוע עם מזהה ייחודי.

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

הסרטונים הנצפים ביותר שלי

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

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

סרטונים מוטמעים באיכות HD שניתן להטמיע

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

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

סרטונים על נושא מסוים

הבקשה הזו מחפשת מילות מפתח לחיפוש סרטונים ב-YouTube Data API שכוללים כתוביות.

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

חיפוש מבוסס-נושאים

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

כדי לחפש באמצעות נושא של Freebase, תחילה עליך לאחזר את מזהה הנושא באמצעות ממשק ה-API של Freebase. הבקשה הזו מחזירה סרטונים המשויכים לנושא Freebase עבור Python, שמזהה הנושא שלו הוא /m/05z1_.

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

חיפוש פלייליסטים או ערוצים

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

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

אם אתם מעדיפים למצוא ערוצי כדורגל, שנו את הפרמטר type.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

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

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

יצירה ועדכון משאבים

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

שיטות POST כוללות Request body, שהוא ייצוג JSON של המשאב שנוצר או מעודכן. אפשר ליצור ייצוגים של JSON ב-Google APIs Explorer באמצעות כלי אינטראקטיבי.

יצירת מינוי

הבקשה הזו רושמת את המשתמש המאומת לערוץ Google Developers. במילים אחרות, הוא יוצר משאב מינוי.

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

יצירת פלייליסט

הבקשה הזו יוצרת פלייליסט ציבורי חדש.

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

הוספת סרטון לפלייליסט

עכשיו, לאחר שיצרנו פלייליסט, נוסיף אליו סרטון. בקשה זו מוסיפה סרטון לתחילת הפלייליסט ('position': 0).

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }