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

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

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

סקירה כללית

לשם הבהרה, הדוגמאות בדף הזה מציגות את הרכיבים הייחודיים של כל בקשה ומקצרות את כתובת ה-URL הבסיסית של המארח שמעבד בקשות API של 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 הרשאה לבצע בקשות API של YouTube Data API בשמם. (פרטים על אישור גישה לנתונים של ערוצים פרטיים זמינים במאמר הטמעה של אימות OAuth 2.0). אחרי הקישור ל-APIs Explorer, לוחצים על הלחצן Authorize requests using OAuth 2.0. בשלב הזה, אתם נותנים ל-APIs Explorer הרשאה לשלוח בקשות בשם הבעלים. בנוסף, בוחרים את היקף ההרשאה, שמציין את סוגי הבקשות שאפשר לבצע באמצעות הכלי APIs Explorer.

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

• snippet
• contentDetails
• שחקן
• סטטיסטיקה
• status

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

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

הבקשה הזו משתמשת ב-method‏ 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" של כל פריט שמוחזר הוא המזהה של playlistItem. מזהה הסרטון של הפריט בפלייליסט הוא videoId בחלק contentDetails.

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

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

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

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

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

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

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

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

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

מנויים לערוץ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

יצירת מינוי

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

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