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

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

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

סקירה כללית

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

• תקציר
• contentDetails
• שחקן
• סטטיסטיקה
• status

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

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

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

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

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