גישה אוטומטית לנתוני 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 Sheets באמצעות Google Apps Script.

סקירה

במדריך הזה נסביר איך לרשום ולהגדיר את סביבת Apps Script לשימוש ב-Google Analytics API. לאחר ההגדרה, המדריך מסביר איך לאחזר מזהה תצוגה מפורטת (פרופיל) של המשתמש המורשה באמצעות Management API. לאחר מכן כיצד להשתמש במזהה התצוגה המפורטת (פרופיל) כדי לבצע שאילתות על ממשק ה-API המרכזי לדיווח על מנת לאחזר מ-Google את 250 מילות המפתח המובילות לחיפוש בנייד. לבסוף, התוצאות יוכנסו לגיליון אלקטרוני של 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 Script חדש.
   1. בתפריט, נכנסים אל תוספים > Apps Script.
   2. אם מופיע תפריט, פשוט לוחצים על פרויקט ריק.
   3. נותנים שם לפרויקט. ודאו שיש לו שם מגניב.

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

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

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

עבודה עם ממשק ה-API של Google Analytics

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

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

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

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

אם מתרחשת שגיאת 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.

הערה: רשימה מלאה של כל הפרמטרים וההגדרות שלהם מופיעה במסמך חומר עזר של Core Reporting API. בנוסף, אפשר למצוא רשימה מלאה של כל המאפיינים והמדדים האפשריים בחומר העזר בנושא מאפיינים ומדדים.

כשה-method 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, או תיבת הודעות עם הודעת שגיאה.

הפיכת הסקריפט לאוטומטי

בשלב זה אמור להיות לך סקריפט שמבצע שאילתה על ה-API של Google Analytics. ייתכן שתרצו עכשיו להפוך סקריפט זה לאוטומטי כדי לאחזר נתונים חדשים מדי לילה. ב-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 Sites – כך תוכל ליצור מרכזי בקרה ב-Google Sites עם נתוני Analytics שלך.
• תפריטים מותאמים אישית – כדי להקל על משתמשים אחרים בחברה להשתמש בסקריפטים שאתם כותבים.