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

בקשות ל-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.

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

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

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

ה-API תומך באפשרות לציין כמה ערכים למסננים video, playlist ו-channel. כדי לעשות זאת, מציינים רשימה מופרדת של מזהי הסרטונים, הפלייליסטים או הערוצים שלגביהם צריך לסנן את תגובת ה-API. לדוגמה, ערך הפרמטר filters של video==pd1FJh59zxQ,Zhawgd0REhA;country==IT מגביל את קבוצת התוצאות כך שתכלול נתונים של הסרטונים שצוינו באיטליה. ערך הפרמטר יכול לציין עד 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 פונקציית קריאה חוזרת.
  • השם של פונקציית הקריאה החוזרת ב-JavaScript שמטפלת בתגובה.
  • נעשה שימוש בבקשות JavaScript JSON-P.
prettyPrint

מחזירה תשובה עם הזחות ומעברי שורה.

  • מחזירה את התגובה בפורמט קריא אם true.
  • ערך ברירת המחדל: true.
  • אם האפשרות הזו false, יכול להיות שגודל מטען הנתונים של התגובה יקטן, מה שעשוי להוביל לביצועים טובים יותר בסביבות מסוימות.
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. בדוגמה הזו נעשה שימוש בספריית הלקוח של Google APIs JavaScript.

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

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

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

עכשיו אפשר לבדוק את הדוגמה בפועל:

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

Python

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

לפני שמריצים את הדוגמה הזו באופן מקומי בפעם הראשונה, צריך להגדיר הרשאות לפרויקט:
  1. יוצרים פרויקט ב-Google API Console או בוחרים פרויקט קיים.
  2. מפעילים את YouTube Analytics API בפרויקט.
  3. בחלק העליון של הדף פרטי כניסה, בוחרים בכרטיסייה מסך בקשת הסכמה ל-OAuth. בוחרים כתובת אימייל, מזינים שם מוצר אם הוא עדיין לא מוגדר ולוחצים על כפתור השמירה.
  4. בדף Credentials (פרטי כניסה), לוחצים על הלחצן Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות Oauth client ID (מזהה לקוח OAuth).
  5. בוחרים בסוג האפליקציה Other (אחר), מזינים את השם YouTube Analytics API Quickstart (הפעלה מהירה של YouTube Analytics API) ולוחצים על הלחצן Create (יצירה).
  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 של האימות לחלון דפדפן. בסוף תהליך ההרשאה, אם צריך, מדביקים את קוד ההרשאה שמוצג בדפדפן בחלון המסוף ולוחצים על [return].
  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'
  )

רוצה לנסות?

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