חשוב: בקשות API לשיטה הזו מחייבות עכשיו גישה להיקף https://www.googleapis.com/auth/youtube.readonly
.
השיטה הזו מאפשרת לאחזר הרבה דוחות שונים של Analytics. כל בקשה משתמשת בפרמטרים של שאילתה כדי לציין מזהה ערוץ או בעל תוכן, תאריך התחלה, תאריך סיום ומדד אחד לפחות. אפשר גם לספק פרמטרים נוספים של שאילתה, כמו מאפיינים, מסננים והוראות מיון.
- מדדים הם מדידות ספציפיות של פעילות המשתמשים, כמו צפיות בסרטונים או דירוגים (לייקים ודיסלייקים).
- מאפיינים הם קריטריונים נפוצים שמשמשים לצבירת נתונים, כמו התאריך שבו התרחשה פעילות המשתמש או המדינה שבה נמצאים המשתמשים. בדוח, לכל שורת נתונים יש שילוב ייחודי של ערכי מאפיינים.
- מסננים הם ערכי מאפיינים שמציינים את הנתונים שיאוחזרו. לדוגמה, אפשר לאחזר נתונים של מדינה מסוימת, סרטון מסוים או קבוצה של סרטונים.
הערה: רק שותפי תוכן של YouTube שמשתתפים בתוכנית השותפים של YouTube יכולים לגשת לדוחות של בעלי התוכן.
תרחישים נפוצים לדוגמה
בקשה
בקשת HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
כל הבקשות ל-YouTube Analytics API צריכות להיות מאושרות. במדריך ההרשאות מוסבר איך להשתמש בפרוטוקול OAuth 2.0 כדי לאחזר אסימוני הרשאה.
בקשות ל-YouTube Analytics API משתמשות בהיקפי ההרשאות הבאים:
טווחים | |
---|---|
https://www.googleapis.com/auth/yt-analytics.readonly | עיון בדוחות YouTube Analytics עבור התוכן שלכם ב-YouTube. ההיקף הזה מספק גישה למדדים של פעילות המשתמשים, כמו מספר הצפיות ומספר הדירוגים. |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | עיון בדוחות כספיים של YouTube Analytics לגבי התוכן שלכם ב-YouTube. ההיקף הזה מספק גישה למדדי פעילות המשתמשים ולמדדי ביצועי המודעות וההכנסות המשוערות. |
https://www.googleapis.com/auth/youtube | ניהול חשבון YouTube. ב-YouTube Analytics API, בעלי ערוצים משתמשים בהיקף הזה כדי לנהל קבוצות של YouTube Analytics ופריטים בקבוצות. |
https://www.googleapis.com/auth/youtubepartner | הצגה וניהול של נכסים ב-YouTube ותוכן שמשויך אליהם ב-YouTube. ב-API של YouTube Analytics, בעלי תוכן משתמשים בהיקף הזה כדי לנהל קבוצות של YouTube Analytics ופריטים בקבוצות. |
פרמטרים
בטבלאות הבאות מפורטים פרמטרים נדרשים ואופציונליים של שאילתות API לאחזור דוחות של שאילתות. פרמטרים סטנדרטיים של שאילתות שמופיעים בטבלה הם גם אופציונליים, והם נתמכים על ידי הרבה ממשקי API של Google.
פרמטרים | ||
---|---|---|
פרמטרים נדרשים | ||
endDate |
string תאריך הסיום של שליפת נתוני YouTube Analytics. הערך צריך להיות בפורמט YYYY-MM-DD .תשובת ה-API מכילה נתונים עד היום האחרון שבו כל המדדים בשילתא זמינים בזמן השילתא. לדוגמה, אם בבקשה מצוין תאריך סיום של 5 ביולי 2017, והערכים של כל המדדים המבוקשים זמינים רק עד 3 ביולי 2017, זה יהיה התאריך האחרון שלגביו הנתונים ייכללו בתגובה. (זה נכון גם אם נתונים לגבי חלק מהמדדים המבוקשים זמינים ל-4 ביולי 2017). הערה: בגרסה 1 של ה-API, הפרמטר הזה נקרא end-date |
|
ids |
string מזהה את הערוץ ב-YouTube או את בעלי התוכן שעבורם מאחזרים נתוני YouTube Analytics.
|
|
metrics |
string רשימה של YouTube Analytics מדדים, כמו views או likes,dislikes , שמופרדים באמצעות פסיקים. במסמכי התיעוד בנושא דוחות על ערוצים או דוחות על בעלי תוכן מפורטת רשימה של הדוחות שאפשר לאחזר ושל המדדים שזמינים בכל דוח. (במסמך מדדים מופיעות הגדרות של כל המדדים).
|
|
startDate |
string תאריך ההתחלה לאחזור נתוני YouTube Analytics. הערך צריך להיות בפורמט YYYY-MM-DD .הערה: בגרסה 1 של ה-API, הפרמטר הזה נקרא
start-date |
|
פרמטרים אופציונליים | ||
currency |
string המטבע שבו ה-API ישתמש כדי לציין את מדדי ההכנסה המשוערת הבאים: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. הערכים שה-API מחזיר עבור המדדים האלה הם אומדנים שמחושבים לפי שערי חליפין שמשתנים מדי יום. אם לא מתבקש אף אחד מהמדדים האלה, המערכת מתעלמת מהפרמטר. ערך הפרמטר הוא קוד מטבע בן שלוש אותיות לפי תקן ISO 4217 מתוך רשימת המטבעות שבהמשך. ה-API מחזיר שגיאה אם מציינים מטבע שלא נתמך. ערך ברירת המחדל הוא USD . |
|
dimensions |
string רשימה של מאפיינים מ-YouTube Analytics, מופרדים בפסיקים, כמו video או ageGroup,gender . במסמכי התיעוד בנושא דוחות על ערוצים או דוחות על בעלי תוכן מפורטת רשימה של הדוחות שאפשר לאחזר ושל המאפיינים שמשמשים בדוחות האלה. (במסמך מאפיינים מופיעות הגדרות לכל המאפיינים).
|
|
filters |
string רשימת מסננים שצריך להחיל כשמאחזרים נתוני YouTube Analytics. במסמכים בנושא דוחות ערוצים ודוחות בעלי תוכן מפורטים המאפיינים שאפשר להשתמש בהם כדי לסנן כל דוח, ובמסמך מאפיינים מוגדרים המאפיינים האלה. אם בקשה משתמשת בכמה מסננים, צריך לצרף אותם באמצעות נקודה ופסיק ( ; ), וטבלת התוצאות שמוחזרת תעמוד בשני המסננים. לדוגמה, ערך הפרמטר filters של video==dMH0bHeiRNg;country==IT מגביל את קבוצת התוצאות כך שתכלול נתונים של הסרטון שצוין באיטליה.ציון של כמה ערכים למסנן ה-API תומך באפשרות לציין כמה ערכים למסננים video , playlist ו-channel . כדי לעשות זאת, מציינים רשימה מופרדת של מזהי הסרטונים, הפלייליסטים או הערוצים שלגביהם צריך לסנן את תגובת ה-API. לדוגמה, ערך הפרמטר filters של video==pd1FJh59zxQ,Zhawgd0REhA;country==IT מגביל את קבוצת התוצאות כך שתכלול נתונים של הסרטונים שצוינו באיטליה. ערך הפרמטר יכול לציין עד 500 מזהים.כשמציינים כמה ערכים לאותו מסנן, אפשר גם להוסיף את המסנן הזה לרשימת המאפיינים שמציינים בבקשה. זה נכון גם אם המסנן לא מופיע כמאפיין נתמך בדוח מסוים. אם מוסיפים את המסנן לרשימת המאפיינים, ה-API משתמש גם בערכי המסנן כדי לקבץ את התוצאות. לדוגמה, נניח שאתם מאחזרים דוח מקורות תנועה של ערוץ מסוים, שבו מוצגים נתונים סטטיסטיים מצטברים של צפיות על סמך האופן שבו הצופים הגיעו לתוכן הווידאו של הערוץ. נניח גם שבקשת הפרמטר filters מזהה רשימה של 10 סרטונים שעבורם צריך להחזיר נתונים.
|
|
includeHistoricalChannelData |
boolean הערה: הפרמטר הזה רלוונטי רק לדוחות של בעלי תוכן. הפרמטר מציין אם תגובת ה-API צריכה לכלול נתונים של זמן צפייה וצפיות בערוצים מהתקופה שלפני שהערוצים קושרו לבעלי התוכן. ערך ברירת המחדל של הפרמטר הוא false , כלומר תגובת ה-API כוללת רק נתונים של זמן צפייה וצפיות מהתאריכים שבהם הערוצים קושרו לבעלי התוכן.חשוב לזכור שערוצים שונים עשויים להיות מקושרים לבעלי תוכן בתאריכים שונים. אם בקשת ה-API מאחזרת נתונים עבור כמה ערוצים וערך הפרמטר הוא false , התגובה מה-API מכילה נתונים שמבוססים על תאריך הקישור של כל ערוץ. אם ערך הפרמטר הוא true , תגובת ה-API מכילה נתונים שתואמים לתאריכים שצוינו בבקשת ה-API.הערה: בגרסה 1 של ה-API, הפרמטר הזה נקרא include-historical-channel-data |
|
maxResults |
integer המספר המקסימלי של שורות שייכללו בתשובה. הערה: בגרסה 1 של ה-API, הפרמטר הזה נקרא max-results |
|
sort |
string רשימה מופרדת בפסיקים של מאפיינים או מדדים שקובעים את סדר המיון של הנתונים ב-YouTube Analytics. כברירת מחדל, סדר המיון הוא עולה. הקידומת - גורמת למיון בסדר יורד.
|
|
startIndex |
integer האינדקס מבוסס-1 של הישות הראשונה לאחזור. (ערך ברירת המחדל הוא 1 ). משתמשים בפרמטר הזה כמנגנון חלוקה לדפים יחד עם הפרמטר max-results .הערה: בגרסה 1 של ה-API, הפרמטר הזה נקרא start-index |
|
פרמטרים רגילים | ||
access_token |
אסימון OAuth 2.0 של המשתמש הנוכחי.
|
|
alt |
הפרמטר הזה לא נתמך בגרסה 2 של ה-API, שתומכת רק בתגובות JSON. פורמט הנתונים של תגובת ה-API.
|
|
callback |
פונקציית קריאה חוזרת.
|
|
prettyPrint |
מחזירה תשובה עם הזחות ומעברי שורה.
|
|
quotaUser |
הפרמטר הזה נתמך בגרסה 1 של ה-API, שהוצאה משימוש. הפרמטר הזה לא נתמך בגרסה 2 של ה-API. | |
userIp |
הפרמטר הזה נתמך בגרסה 1 של ה-API, שהוצאה משימוש. הפרמטר הזה לא נתמך בגרסה 2 של ה-API. |
גוף הבקשה
כשקוראים לשיטה הזו, לא שולחים גוף בקשה.
תשובה
כמו שצוין בהגדרה של הפרמטר alt
, ה-API יכול להחזיר תגובות בפורמט JSON או CSV. בהמשך מוצג מידע על גוף התגובה לכל סוג:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
מאפיינים | |
---|---|
kind |
string הערך הזה מציין את סוג הנתונים שכלולים בתגובת ה-API. בשיטה query , ערך המאפיין kind יהיה youtubeAnalytics#resultTable . עם זאת, אם ה-API יוסיף תמיכה בשיטות אחרות, יכול להיות שבתגובות ה-API לשיטות האלה יופיעו ערכים אחרים של המאפיין kind . |
columnHeaders[] |
list הערך הזה מציין מידע על הנתונים שמוחזרים בשדות rows . כל פריט ברשימה columnHeaders מזהה שדה שמוחזר בערך rows , שמכיל רשימה של נתונים מופרדים באמצעות פסיקים.הרשימה columnHeaders מתחילה במאפיינים שצוינו בבקשת ה-API, ואחריהם המדדים שצוינו בבקשת ה-API. הסדר של המאפיינים והמדדים תואם לסדר בבקשת ה-API.לדוגמה, אם בקשת ה-API מכילה את הפרמטרים dimensions=ageGroup,gender&metrics=viewerPercentage , תגובת ה-API מחזירה עמודות בסדר הזה: ageGroup ,gender ,viewerPercentage . |
columnHeaders[].name |
string שם המאפיין או המדד. |
columnHeaders[].columnType |
string סוג העמודה ( DIMENSION או METRIC ). |
columnHeaders[].dataType |
string סוג הנתונים בעמודה ( STRING , INTEGER , FLOAT וכו'). |
rows[] |
list הרשימה מכילה את כל השורות בטבלת התוצאות. כל פריט ברשימה הוא מערך שמכיל נתונים מופרדים בפסיקים שמתאימים לשורה אחת של נתונים. הסדר של שדות הנתונים המופרדים באמצעות פסיקים יהיה זהה לסדר של העמודות שמופיעות בשדה columnHeaders .אם אין נתונים זמינים לשאילתה מסוימת, הרכיב rows לא יופיע בתגובה.התגובה לשאילתה עם המאפיין day לא תכיל שורות של הימים האחרונים. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
דוגמאות
הערה: יכול להיות שדוגמאות הקוד הבאות לא מייצגות את כל שפות התכנות הנתמכות. כאן אפשר לעיין ברשימת השפות הנתמכות.
JavaScript
בדוגמה הזו מתבצעת קריאה ל-YouTube Analytics API כדי לאחזר נתונים של צפיות יומיות ומדדים אחרים בערוץ של המשתמש המורשה לשנת 2017. בדוגמה הזו נעשה שימוש בספריית הלקוח של Google APIs JavaScript.לפני שמריצים את הדוגמה הזו באופן מקומי בפעם הראשונה, צריך להגדיר הרשאות לפרויקט:
- יוצרים פרויקט ב-Google API Console או בוחרים פרויקט קיים.
- מפעילים את YouTube Analytics API בפרויקט.
- בחלק העליון של הדף פרטי כניסה, בוחרים בכרטיסייה מסך בקשת הסכמה ל-OAuth. בוחרים כתובת אימייל, מזינים שם מוצר אם הוא עדיין לא מוגדר ולוחצים על כפתור השמירה.
- בדף Credentials (פרטי כניסה), לוחצים על הלחצן Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות Oauth client ID (מזהה לקוח OAuth).
- בוחרים את סוג האפליקציה Web application.
- בשדה 'מקורות JavaScript מורשים', מזינים את כתובת ה-URL שממנה יוגש קוד לדוגמה. לדוגמה, אפשר להשתמש ב-
http://localhost:8000
או ב-http://yourserver.example.com
. אפשר להשאיר את השדה Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית) ריק. - לוחצים על הלחצן יצירה כדי לסיים את יצירת פרטי הכניסה.
- לפני שסוגרים את תיבת הדו-שיח, מעתיקים את מזהה הלקוח, שצריך להוסיף לדוגמת הקוד.
לאחר מכן, שומרים את הדוגמה בקובץ מקומי. בדוגמה, מחפשים את השורה הבאה ומחליפים את YOUR_CLIENT_ID במזהה הלקוח שקיבלתם כשקבעתם את פרטי ההרשאה.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
עכשיו אפשר לבדוק את הדוגמה בפועל:
- פותחים את הקובץ המקומי מדפדפן אינטרנט ופותחים את מסוף הניפוי באגים בדפדפן. יופיע דף עם שני לחצנים.
- לוחצים על הלחצן authorize and load (אישור וטעינה) כדי להפעיל את תהליך אישור המשתמש. אם תאשרו לאפליקציה לאחזר את נתוני הערוץ, השורות הבאות יודפסו במסוף בדפדפן:
Sign-in successful GAPI client loaded for API
- אם מוצגת הודעת שגיאה במקום השורות שלמעלה, צריך לוודא שאתם טוענים את הסקריפט מכתובת ה-URI המורשית להפניה אוטומטית שהגדרתם לפרויקט, וששמתם את מזהה הלקוח בקוד כמו שמתואר למעלה.
- לוחצים על הלחצן execute כדי לשלוח קריאה ל-API. אובייקט
response
אמור להופיע במסוף בדפדפן. באובייקט הזה, המאפייןresult
ממופה לאובייקט שמכיל את נתוני ה-API.
<script src="https://apis.google.com/js/api.js"></script> <script> function authenticate() { return gapi.auth2.getAuthInstance() .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"}) .then(function() { console.log("Sign-in successful"); }, function(err) { console.error("Error signing in", err); }); } function loadClient() { return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2") .then(function() { console.log("GAPI client loaded for API"); }, function(err) { console.error("Error loading GAPI client for API", err); }); } // Make sure the client is loaded and sign-in is complete before calling this method. function execute() { return gapi.client.youtubeAnalytics.reports.query({ "ids": "channel==MINE", "startDate": "2017-01-01", "endDate": "2017-12-31", "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "dimensions": "day", "sort": "day" }) .then(function(response) { // Handle the results here (response.result has the parsed body). console.log("Response", response); }, function(err) { console.error("Execute error", err); }); } gapi.load("client:auth2", function() { gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'}); }); </script> <button onclick="authenticate().then(loadClient)">authorize and load</button> <button onclick="execute()">execute</button>
Python
בדוגמה הזו מתבצעת קריאה ל-YouTube Analytics API כדי לאחזר נתונים של צפיות יומיות ומדדים אחרים בערוץ של המשתמש המורשה לשנת 2017. בדוגמה נעשה שימוש בספריית הלקוח של Google APIs Python.לפני שמריצים את הדוגמה הזו באופן מקומי בפעם הראשונה, צריך להגדיר הרשאות לפרויקט:
- יוצרים פרויקט ב-Google API Console או בוחרים פרויקט קיים.
- מפעילים את YouTube Analytics API בפרויקט.
- בחלק העליון של הדף פרטי כניסה, בוחרים בכרטיסייה מסך בקשת הסכמה ל-OAuth. בוחרים כתובת אימייל, מזינים שם מוצר אם הוא עדיין לא מוגדר ולוחצים על כפתור השמירה.
- בדף Credentials (פרטי כניסה), לוחצים על הלחצן Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות Oauth client ID (מזהה לקוח OAuth).
- בוחרים בסוג האפליקציה Other (אחר), מזינים את השם YouTube Analytics API Quickstart (הפעלה מהירה של YouTube Analytics API) ולוחצים על הלחצן Create (יצירה).
- לוחצים על אישור כדי לסגור את תיבת הדו-שיח שמופיעה.
- לוחצים על הלחצן (הורדת JSON) משמאל למזהה הלקוח.
- מעבירים את הקובץ שהורדתם לספריית העבודה.
צריך גם להתקין את ספריית הלקוח של Google APIs ל-Python ועוד כמה ספריות:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
עכשיו אפשר לבדוק את הדוגמה בפועל:
- מעתיקים את דוגמת הקוד שבהמשך לספריית העבודה.
- בדוגמה, מעדכנים את הערך של המשתנה
CLIENT_SECRETS_FILE
כך שיתאים למיקום של הקובץ שהורדתם אחרי שהגדרתם את פרטי ההרשאה. - מריצים את הקוד לדוגמה בחלון הטרמינל:
python yt_analytics_v2.py
- מבצעים את תהליך ההרשאה. יכול להיות שתהליך האימות ייטען אוטומטית בדפדפן, או שתצטרכו להעתיק את כתובת ה-URL של האימות לחלון דפדפן. בסוף תהליך ההרשאה, אם צריך, מדביקים את קוד ההרשאה שמוצג בדפדפן בחלון המסוף ולוחצים על [return].
- שאילתת ה-API מופעלת והתגובה בפורמט JSON מוצגת בחלון הטרמינל.
# -*- coding: utf-8 -*- import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly'] API_SERVICE_NAME = 'youtubeAnalytics' API_VERSION = 'v2' CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json' def get_service(): flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES) credentials = flow.run_console() return build(API_SERVICE_NAME, API_VERSION, credentials = credentials) def execute_api_request(client_library_function, **kwargs): response = client_library_function( **kwargs ).execute() print(response) if __name__ == '__main__': # Disable OAuthlib's HTTPs verification when running locally. # *DO NOT* leave this option enabled when running in production. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' youtubeAnalytics = get_service() execute_api_request( youtubeAnalytics.reports().query, ids='channel==MINE', startDate='2017-01-01', endDate='2017-12-31', metrics='estimatedMinutesWatched,views,likes,subscribersGained' dimensions='day', sort='day' )
רוצה לנסות?
משתמשים ב-APIs Explorer כדי להפעיל את ה-API הזה ולראות את הבקשה והתגובה של ה-API.