גישה אוטומטית לנתוני Google Analytics ב-Google Sheets

ניק מיכאילובסקי, צוות Google Analytics API – אוגוסט 2012

במדריך זה נסביר איך לגשת לממשקי ה-API לניהול ולדיווח ליבה ב-Google Sheets באמצעות Apps Script.

מבוא

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

במדריך זה נסביר איך להשתמש בקוד של Google Analytics כדי להשתמש בסקריפט של Google Apps כדי לגשת לנתוני Google Analytics.

סקירה כללית

במדריך הזה נסביר איך לרשום ולהגדיר את סביבת Apps Script לשימוש ב-Google Analytics API. בסיום ההגדרה, המדריך יסביר לך איך לאחזר מזהה תצוגה (פרופיל) עבור המשתמש המורשה באמצעות ממשק ה-API לניהול. לאחר מכן, תוכלו להשתמש במזהה התצוגה המפורטת (הפרופיל) כדי לשלוח שאילתה ל- Core Reporting API כדי לאחזר את 250 מילות המפתח המובילות לחיפוש לנייד מ-Google. התוצאות יתווספו לגיליון אלקטרוני של Google. אחרי שיהיו לכם נתונים, המדריך יסביר גם איך לאחזר נתונים באופן אוטומטי.

כשיוצרים אפליקציה באמצעות Google Analytics API ו-Apps Script, בדרך כלל צריך לבצע את השלבים הבאים:

• הפעלת ממשקי ה-API של Google Analytics ב-Google Sheets
• עבודה עם ממשקי ה-API של Google Analytics

בואו נעבור על כל שלב בפירוט.

הפעלת Google Analytics API ב-Apps Script

כדי להפעיל גישה לנתוני Google Analytics מתוך Google Sheets, בצעו את השלבים הבאים:

1. יוצרים קובץ ב-Google Sheets. תנו שם מגניב.
2. יצירת סקריפט חדש של Apps.
   1. בתפריט, עוברים אל תוספים > Apps Script.
   2. אם מופיע תפריט קופץ, לוחצים על פרויקט ריק.
   3. נותנים שם לפרויקט. מוודאים שיש לו שם מגניב.

אחרי שיהיה לכם סקריפט חדש, תצטרכו להפעיל את שירות Google Analytics.

1. בעורך הסקריפטים, בוחרים באפשרות Resources > Advanced Google services...
2. בתיבת הדו-שיח שתוצג, לוחצים על המתג הפעלה/השבתה לצד ממשק ה-API של Google Analytics.
3. בחלק התחתון של תיבת הדו-שיח יש ללחוץ על הקישור של Google Developers Console.
4. במסוף החדש, שוב יש ללחוץ על המתג הפעלה/כיבוי לצד Google Analytics API. (כשהאפשרות מופעלת, היא תדלג לחלק העליון של הדף).
5. חוזרים אל עורך הסקריפטים ולוחצים על OK בתיבת הדו-שיח.

תיפתח תיבת דו-שיח צהובה קטנה עם הכיתוב שהוספת בהצלחה שירות Google APIs חדש לסקריפט. עכשיו אפשר להתחיל לכתוב את הסקריפט הראשון.

עבודה עם Google Analytics API

הסקריפט הזה במדריך הזה ישלח שאילתות לגבי Google Analytics API עבור 250 מילות המפתח המובילות בחיפוש Google לנייד, ולאחר מכן פלט את התוצאות אל Google Sheets. כדי לעשות זאת, הסקריפט יעבור את השלבים הבאים:

• אחזור התצוגה הראשונה (פרופיל) של המשתמש המורשה.
• הרצת שאילתה ב-Core Reporting API לגבי נתונים.
• הוספת נתונים לגיליון אלקטרוני.

צריך להוסיף את הפונקציה הבאה לפרויקט הריק.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

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

אחזור התצוגה הראשונה של המשתמש המורשה

ב-Google Analytics, כל דוח שייך לתצוגה מפורטת (פרופיל) ומזוהה באמצעות מזהה תצוגה (פרופיל). לכן, כשמציינים שאילתה עם נתוני דוח, צריך לציין גם את מזהה התצוגה המפורטת (הפרופיל) של התצוגה המפורטת (הפרופיל) שממנה רוצים לאחזר את הנתונים.

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

הערה: מידע נוסף על הקשר בין הישויות האלה לבין המסמך סקירה כללית של ממשק ה-API לניהול.

הפונקציה השנייה שנכתוב יעברו דרך ההיררכיה של ממשק ה-API לניהול, ותחזיר את התצוגה המפורטת (פרופיל) של המשתמש. צריך להעתיק ולהדביק את הקוד הבא בפרויקט Apps Script:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

בפונקציה הזו, מתבצע איסוף שאילתה דרך האוסף 'חשבונות', בשיטה Analytics.Management.Accounts.list. אם למשתמש המורשה יש חשבונות Google Analytics, המזהה של החשבון הראשון מאוחזר. לאחר מכן, האוסף של נכסי האינטרנט נשלח אליו שאילתה באמצעות קריאה לשיטה Analytics.Management.Webproperties.list והעברה של השיטה שאוחזרה על ידי מספר החשבון בשלב הקודם. אם קיימים נכסי אינטרנט, האוסף 'תצוגה (פרופיל)' נשלח בסופו של דבר שאילתה באמצעות השיטה Analytics.Management.Profiles.list. גם מזהה החשבון וגם מזהי נכסי האינטרנט מועברים כפרמטרים לשיטה הזו. אם קיימות צפיות (פרופילים) מוחזרת התצוגה הראשונה (פרופיל).

הערה: צריך להפעיל את שירות Google Analytics API כדי שכל השיטות Analytics.* יפעלו כמו שצריך.

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

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

הרצת שאילתה ב-Core Reporting API לגבי נתונים.

אחרי שמקבלים מזהה תצוגה מפורטת (פרופיל), צריך להשתמש ב-Core Reporting API כדי לשלוח שאילתות לגבי נתוני הדוח של Google Analytics. בקטע הזה תלמדו איך לשלוח שאילתה ל-API הזה באמצעות Apps Script.

מוסיפים את הקוד הבא לפרויקט Apps Script:

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

החלק הראשון של הקוד יוצר שאילתה ב-Core Reporting API בשיטה Analytics.Data.Ga.get. השיטה מקבלת מספר פרמטרים שמציינים את סוג הדוח שיש לאחזר. כל שאילתה ב-Core Reporting API מורכבת מקבוצת פרמטרים נדרשים ואופציונליים. הפרמטרים הנדרשים מועברים לשיטה כפרמטרים והפרמטרים האופציונליים מועברים כאובייקט.

הפרמטר table ID נדרש והוא נוצר על ידי שילוב הקידומת ga: למזהה התצוגה המפורטת (פרופיל). הקוד יוצר את מזהה הטבלה באמצעות מזהה התצוגה המפורטת (הפרופיל) שאוחזר בשלב הקודם. כמו כן, נדרשים תאריך התחלה וסיום וציון טווח התאריכים של הנתונים לאחזור. שניהם מחושבים על סמך תאריך היום באמצעות הפונקציה getLastNdays. לבסוף, כל הפרמטרים האופציונליים מועברים לפונקציה באמצעות האובייקט optArgs.

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

כשהשיטה Analytics.Data.Ga.get פועלת, מתבצעת בקשה ל-Core Reporting API. אם מתרחשת שגיאה, היא מופיעה בבלוק try...catch שהוגדר בשיטה החיצונית runDemo. אם הבקשה אושרה, התוצאות יוחזרו.

הוספת נתונים לגיליון אלקטרוני

השלב האחרון בסקריפט שלנו הוא פלט של התוצאות מ-Core Reporting API ל-Google Sheets. השיטה outputToSpreadsheet עובדת. צריך להוסיף את הקוד הבא לפרויקט:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

פונקציה זו קודם מוסיפה גיליון חדש לגיליון האלקטרוני הפעיל. פעולה זו מוסיפה את נתוני הכותרת והדיווח לגיליון. טיפים נוספים להוספת נתונים ל-Google Sheets זמינים במאמר כתיבת נתונים מאובייקטים של JavaScript לגיליון אלקטרוני במדריך אחסון נתונים בגיליונות אלקטרוניים.

הרצת הסקריפט

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

• בסרגל הכלים של עורך הסקריפטים, בוחרים באפשרות runDemo בתפריט הנפתח של הפונקציה.
• בשלב הבא, לוחצים על הלחצן play.

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

לוחצים על 'מתן הרשאה'.

אחרי הלחיצה, ייפתח דף חדש שמתארח ב-google.com ויבקש ממך לתת לסקריפט הזה גישה לנתונים שלך. אחרי הלחיצה על 'אישור', תועברו לדף אישור. בשלב זה, הסקריפט יוכל עכשיו לגשת לנתוני Google Analytics שלך והוא יוכל להמשיך לפעול.

הערה: צריך להעניק לסקריפט גישה לנתוני Google Analytics רק בפעם הראשונה שבה הסקריפט מופעל.

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

אוטומציה של הסקריפט

בשלב הזה, צריך להיות סקריפט שמפעיל שאילתה ב-Google Analytics API. עכשיו מומלץ להפוך את הסקריפט הזה לאוטומטי כדי לאחזר נתונים חדשים מדי לילה. Apps Script מאפשר להפעיל אוטומציה בקלות באמצעות התכונה triggers.

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

• בסרגל הכלים של עורך הסקריפטים, לוחצים על Resources -> All your triggers...
• יש ללחוץ על Add a new trigger. תופיע תיבת הדו-שיח של הטריגר.
• מגדירים את הטריגר לבצע את השיטה runDemo בכל לילה
  • התפריט הנפתח Run צריך להיות מוגדר ל: runDemo
  • התפריט הנפתח Events צריך להיות מוגדר ל: Time-driven, Day timer ו-Midnight to 1am.
  
  

  

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

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

סיכום

רשמת בהצלחה הרשאת גישה לסקריפט שלך והיא אושרה על ידך. שלחתם שאילתה ל-Management API כמה פעמים כדי לאחזר את המזהה של הפרופיל (הפרופיל). לאחר מכן, השתמשת במזהה התצוגה המפורטת (הפרופיל) כדי לשלוח שאילתה ל-Core Reporting API כדי לאחזר נתונים ופלט אותם אל Google Sheets.

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

הנה כמה מדריכים מגניבים נוספים שעשויים לעזור לך להפיק את המרב מ-Google Analytics API ומ-Google Apps Script:

• קריאת נתונים מגיליונות אלקטרוניים – ניתן לציין את שאילתות ה-API בגיליון אלקטרוני במקום ב-JavaScript.
• הוספת תרשימים מגיליונות אלקטרוניים לאתר Google – כך תוכלו ליצור מרכזי בקרה ב-Google Sites עם נתוני Analytics.
• תפריטים מותאמים אישית – כדי לאפשר למשתמשים אחרים בחברה להשתמש בסקריפטים שאתם כותבים,