Reports: Query

חשוב: בקשות 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 כדי לאחזר אסימוני הרשאה.

בקשות API של YouTube Analytics משתמשות בהיקפי ההרשאה הבאים:

רמות
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. ב-YouTube Analytics API, בעלי תוכן משתמשים בהיקף הזה כדי לנהל קבוצות ופריטים ב-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.

  • כדי לבקש נתונים עבור ערוץ YouTube, צריך להגדיר את ערך הפרמטר ids ל-channel==MINE או ל-channel==CHANNEL_ID, כאשר CHANNEL_ID מזהה את ערוץ YouTube של המשתמש המאומת הנוכחי.
  • כדי לבקש נתונים מבעלי תוכן ב-YouTube, צריך להגדיר את ערך הפרמטר ids ל-contentOwner==OWNER_NAME, כאשר OWNER_NAME הוא content owner ID עבור המשתמש.

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

אם בבקשה יש כמה מסננים, צריך לאחד אותם באמצעות נקודה ופסיק (;). טבלת התוצאות שהוחזרה תעמוד בשני המסננים. לדוגמה, ערך הפרמטר video==dMH0bHeiRNg;country==IT של filters מגביל את תוצאת הבדיקה כך שתכלול נתונים עבור הסרטון הנתון באיטליה.

ציון ערכים מרובים למסנן

ה-API תומך באפשרות לציין ערכים מרובים למסננים video, playlist ו-channel. כדי לעשות זאת, צריך לציין רשימה מופרדת של מזהי הסרטון, הפלייליסט או הערוצים שעבורם יש לסנן את תגובת ה-API. לדוגמה, ערך הפרמטר video==pd1FJh59zxQ,Zhawgd0REhA;country==IT של filters מגביל את תוצאת הבדיקה כך שתכלול נתונים עבור הסרטונים הנתון באיטליה. ערך הפרמטר יכול לציין עד 500 מזהים.

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

לדוגמה, נניח שאתם מאחזרים את הדוח'מקורות תנועה' של ערוץ, שצובר סטטיסטיקות צפייה לפי האופן שבו הצופים הגיעו לתוכן הווידאו של הערוץ. בנוסף, נניח שבקשת הפרמטר filters של הבקשה מזהה רשימה של 10 סרטונים שעבורם יש להחזיר נתונים.
  • אם מוסיפים video לערך הפרמטר dimensions, תגובת ה-API תספק נתונים סטטיסטיים נפרדים של מקור התנועה לכל אחד מ-10 הסרטונים.
  • אם לא מוסיפים את video לערך הפרמטר dimensions, תגובת ה-API תאסוף את הנתונים הסטטיסטיים של מקור התנועה מכל 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.
  • הערכים התקפים: json, csv
  • ערך ברירת המחדל: json
callback פונקציית קריאה חוזרת.
  • השם של פונקציית הקריאה החוזרת (callback) של JavaScript שמטפלת בתגובה.
  • משמש בבקשות JSON-P ב-JavaScript.
prettyPrint

מחזירה תגובה עם כניסות פסקה ומעברי שורה.

  • מחזירה את התשובה בפורמט קריא לאנשים אם true.
  • ערך ברירת המחדל: true.
  • שימוש בערך false עשוי להקטין את המטען הייעודי (payload) של התגובה, וכך לשפר את הביצועים בסביבות מסוימות.
quotaUser הפרמטר הזה נתמך בגרסה 1 של ה-API, שהוצאה משימוש. הפרמטר הזה לא נתמך בגרסה 2 של ה-API.
userIp הפרמטר הזה נתמך בגרסה 1 של ה-API, שהוצאה משימוש. הפרמטר הזה לא נתמך בגרסה 2 של ה-API.

גוף הבקשה

אין לשלוח גוף הבקשה בקריאה לשיטה הזו.

תשובה

כפי שצוין בהגדרת הפרמטר alt, ה-API יכול להחזיר תגובות בפורמט JSON או CSV. בהמשך מופיע מידע על גוף התגובה לכל סוג:

JSON
{
  "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 לא תכלול שורות מהימים האחרונים.

CSV
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. הדוגמה משתמשת בספריית הלקוח של JavaScript ב-Google APIs.

לפני שמריצים את הדוגמה הזו באופן מקומי בפעם הראשונה, צריך להגדיר פרטי כניסה להרשאות בפרויקט:
  1. יוצרים או בוחרים פרויקט במסוף Google API.
  2. מפעילים את YouTube Analytics API לפרויקט.
  3. בחלק העליון של הדף פרטי כניסה, בוחרים בכרטיסייה מסך ההסכמה של OAuth. בוחרים כתובת אימייל, מזינים שם מוצר אם הוא לא מוגדר עדיין ולוחצים על הלחצן 'שמירה'.
  4. בדף Credentials, לוחצים על הלחצן Create credentials ובוחרים באפשרות Oauth client ID.
  5. בוחרים את סוג האפליקציה 'אפליקציית אינטרנט'.
  6. בשדה 'מקורות JavaScript מורשים', מזינים את כתובת ה-URL שממנה תשלחו את דוגמת הקוד. לדוגמה, אפשר להשתמש בשם כמו http://localhost:8000 או http://yourserver.example.com. אפשר להשאיר את השדה 'מזהי URI מורשים להפניה אוטומטית' ריק.
  7. לוחצים על הלחצן יצירה כדי לסיים את יצירת פרטי הכניסה.
  8. לפני סגירת תיבת הדו-שיח, העתק את מזהה הלקוח שיהיה עליך להזין בדוגמת הקוד.

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

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

עכשיו אתם מוכנים לבדוק את הדוגמה:

  1. פותחים את הקובץ המקומי מדפדפן אינטרנט ופותחים את מסוף ניפוי הבאגים בדפדפן. אמור להופיע דף שמציג שני לחצנים.
  2. לוחצים על הלחצן אישור וטעינה כדי להפעיל את תהליך הרשאת המשתמש. אם נותנים לאפליקציה הרשאה לאחזר את נתוני הערוץ, השורות הבאות אמורות להופיע במסוף בדפדפן: 
    Sign-in successful
GAPI client loaded for API
  3. אם מופיעה הודעת שגיאה במקום השורות שלמעלה, ודאו שאתם טוענים את הסקריפט מה-URI המורשה להפניה אוטומטית שהגדרתם בפרויקט, ושאתם מזינים את מזהה הלקוח בקוד כמתואר למעלה.
  4. לוחצים על הלחצן 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>

yt_analytics_v2.html

Python

הדוגמה הזו מפעילה את YouTube Analytics API כדי לאחזר את הצפיות היומיות ומדדים אחרים של הערוץ של המשתמש שנתן הרשאה בשנה הקלנדרית של 2017. הדוגמה משתמשת בספריית הלקוח של Python ב-Google APIs.

לפני שמריצים את הדוגמה הזו באופן מקומי בפעם הראשונה, צריך להגדיר פרטי כניסה להרשאות בפרויקט:
  1. יוצרים או בוחרים פרויקט במסוף Google API.
  2. מפעילים את YouTube Analytics API לפרויקט.
  3. בחלק העליון של הדף פרטי כניסה, בוחרים בכרטיסייה מסך ההסכמה של OAuth. בוחרים כתובת אימייל, מזינים שם מוצר אם הוא לא מוגדר עדיין ולוחצים על הלחצן 'שמירה'.
  4. בדף Credentials, לוחצים על הלחצן Create credentials ובוחרים באפשרות Oauth client ID.
  5. בוחרים את סוג האפליקציה אחר, מזינים את השם 'YouTube Analytics API למתחילים' ולוחצים על הלחצן 'יצירה'.
  6. לוחצים על אישור כדי לסגור את תיבת הדו-שיח שמופיעה.
  7. לוחצים על הלחצן (הורדת JSON) מימין למזהה הלקוח.
  8. מעבירים את הקובץ שהורדתם לספריית העבודה.

בנוסף, צריך להתקין את ספריית הלקוח של Google APIs ל-Python ולספריות נוספות:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

עכשיו אתם מוכנים לבדוק את הדוגמה:

  1. צריך להעתיק את דוגמת הקוד הבאה לספריית העבודה שלך.
  2. בדוגמה, מעדכנים את הערך של המשתנה CLIENT_SECRETS_FILE כך שיתאים למיקום הקובץ שהורדתם אחרי שהגדרתם את פרטי הכניסה להרשאה.
  3. מריצים את הקוד לדוגמה בחלון הטרמינל: 
    python yt_analytics_v2.py
  4. משלימים את תהליך ההרשאה. יכול להיות שתהליך האימות ייטען באופן אוטומטי בדפדפן, או שיהיה צורך להעתיק את כתובת ה-URL לאימות לחלון של דפדפן. אם צריך, בסיום תהליך ההרשאה, מדביקים את קוד ההרשאה שמוצג בדפדפן בחלון הטרמינל ולוחצים על [חזרה].
  5. שאילתת ה-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'
  )

yt_analytics_v2.py

רוצה לנסות?

משתמשים ב-APIs Explorer כדי לקרוא ל-API הזה ולראות את הבקשה והתגובה של ה-API.