שלום Analytics Reporting API v4; מדריך למתחילים של Java לחשבונות שירות

במדריך הזה מפורטים השלבים לגישה אל Analytics Reporting API v4.

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

1. הפעלת ה-API

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

יצירת פרטי כניסה

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

1. פותחים את הדף חשבון שירות. אם מתבקשים, בוחרים פרויקט.
2. לוחצים על Create Service Account ומזינים את השם ואת התיאור של חשבון השירות. אפשר להשתמש במספר של חשבון השירות שמוגדר כברירת מחדל, או לבחור מספר אחר וייחודי. בסיום, לוחצים על יצירה.
3. הקטע הרשאות לחשבון שירות (אופציונלי) לא נדרש. לוחצים על Continue.
4. במסך Grant users access to this service account גוללים למטה לקטע Create key. לוחצים על Create key.
5. בחלונית הצדדית שמופיעה, בוחרים את הפורמט של המפתח: מומלץ JSON.
6. לוחצים על יצירה. זוג המפתחות הציבורי/הפרטי החדש נוצר והורדה למחשב שלך. הוא משמש כעותק היחיד של המפתח הזה. למידע נוסף על אחסון מאובטח, קראו את המאמר ניהול מפתחות של חשבונות שירות.
7. לוחצים על Close בתיבת הדו-שיח Private key saved to your במחשב, ולאחר מכן לוחצים על Done כדי לחזור לטבלה של חשבונות השירות.

הוספת חשבון שירות לחשבון Google Analytics

לחשבון השירות החדש תהיה כתובת אימייל שנראית כך:

[e-mail]

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

2. התקנת ספריית הלקוח

כדי להתקין את לקוח Java של Google Analytics API, עליך להוריד קובץ ZIP שמכיל את כל ה-מאגרים שצריך לחלץ ולהעתיק לנתיב המחלקה של Java.

1. מורידים את ספריית הלקוח של Java ב-Analytics Reporting API v4. היא מקובצת כקובץ ZIP עם כל יחסי התלות הנדרשים.
2. מחלצים את קובץ ה-ZIP.
3. מוסיפים את כל מזהי ה-JAR ששמורים בספרייה libs לנתיב הכיתה.
4. מוסיפים את הצנצנת google-api-services-analyticsreporting-v4-[version].jar לנתיב הכיתה.

פרטי סביבת Java

ליקוי חמה

עבור Eclipse, יש לעיין בשאלה הזו של StackOverflow כדי לקבל הוראות להוספת JAR לנתיב הכיתה של הפרויקט.

NetBeans

עבור NetBeans, אפשר לעיין בשאלה הזו של StackOverflow כדי לקבל הוראות להוספת JAR לנתיב הכיתה של הפרויקט.

IDEA של IntelliJ

ל-IntelliJ IDEA, ניתן לעיין בשאלה הזו בנושא StackOverflow כדי לקבל הוראות להוספת JAR לנתיב המחלקה של הפרויקט.

שורת הפקודה

אם מפתחים דרך שורת הפקודה, יש להוסיף את הקוד הבא להפעלה של הפקודה javac ו-java:

-classpath /path/to/directory/with/unzipped/jars

הערה: בהתאם לסביבת זמן הריצה של Java, יכול להיות שתצטרכו גם להוריד ולהוסיף את javax.servlet.jar לנתיב המחלקה של הפרויקט.

3. הגדרת הדוגמה

תצטרכו ליצור קובץ יחיד בשם HelloAnalyticsReporting.java שיכיל את הקוד לדוגמה הנתון.

• העתק או הורד את קוד המקור הבא אל HelloAnalyticsReporting.java.

• מעבירים את client_secrets.json שכבר הורדתם לאותה ספרייה שבה נמצא הקוד לדוגמה.
• החלף את הערכים של KEY_FILE_LOCATION בערכים המתאימים מ-Developer Console.

• מחליפים את הערך של VIEW_ID במזהה של התצוגה המפורטת שאליה רוצים לגשת.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import com.google.api.services.analyticsreporting.v4.AnalyticsReportingScopes;
import com.google.api.services.analyticsreporting.v4.AnalyticsReporting;

import com.google.api.services.analyticsreporting.v4.model.ColumnHeader;
import com.google.api.services.analyticsreporting.v4.model.DateRange;
import com.google.api.services.analyticsreporting.v4.model.DateRangeValues;
import com.google.api.services.analyticsreporting.v4.model.GetReportsRequest;
import com.google.api.services.analyticsreporting.v4.model.GetReportsResponse;
import com.google.api.services.analyticsreporting.v4.model.Metric;
import com.google.api.services.analyticsreporting.v4.model.Dimension;
import com.google.api.services.analyticsreporting.v4.model.MetricHeaderEntry;
import com.google.api.services.analyticsreporting.v4.model.Report;
import com.google.api.services.analyticsreporting.v4.model.ReportRequest;
import com.google.api.services.analyticsreporting.v4.model.ReportRow;

public class HelloAnalyticsReporting {
  private static final String APPLICATION_NAME = "Hello Analytics Reporting";
  private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
  private static final String KEY_FILE_LOCATION = "<REPLACE_WITH_JSON_FILE>";
  private static final String VIEW_ID = "<REPLACE_WITH_VIEW_ID>";
  public static void main(String[] args) {
    try {
      AnalyticsReporting service = initializeAnalyticsReporting();

      GetReportsResponse response = getReport(service);
      printResponse(response);
    } catch (Exception e) {
      e.printStackTrace();
    }
  }

  /**
   * Initializes an Analytics Reporting API V4 service object.
   *
   * @return An authorized Analytics Reporting API V4 service object.
   * @throws IOException
   * @throws GeneralSecurityException
   */
  private static AnalyticsReporting initializeAnalyticsReporting() throws GeneralSecurityException, IOException {

    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
    GoogleCredential credential = GoogleCredential
        .fromStream(new FileInputStream(KEY_FILE_LOCATION))
        .createScoped(AnalyticsReportingScopes.all());

    // Construct the Analytics Reporting service object.
    return new AnalyticsReporting.Builder(httpTransport, JSON_FACTORY, credential)
        .setApplicationName(APPLICATION_NAME).build();
  }

  /**
   * Queries the Analytics Reporting API V4.
   *
   * @param service An authorized Analytics Reporting API V4 service object.
   * @return GetReportResponse The Analytics Reporting API V4 response.
   * @throws IOException
   */
  private static GetReportsResponse getReport(AnalyticsReporting service) throws IOException {
    // Create the DateRange object.
    DateRange dateRange = new DateRange();
    dateRange.setStartDate("7DaysAgo");
    dateRange.setEndDate("today");

    // Create the Metrics object.
    Metric sessions = new Metric()
        .setExpression("ga:sessions")
        .setAlias("sessions");

    Dimension pageTitle = new Dimension().setName("ga:pageTitle");

    // Create the ReportRequest object.
    ReportRequest request = new ReportRequest()
        .setViewId(VIEW_ID)
        .setDateRanges(Arrays.asList(dateRange))
        .setMetrics(Arrays.asList(sessions))
        .setDimensions(Arrays.asList(pageTitle));

    ArrayList<ReportRequest> requests = new ArrayList<ReportRequest>();
    requests.add(request);

    // Create the GetReportsRequest object.
    GetReportsRequest getReport = new GetReportsRequest()
        .setReportRequests(requests);

    // Call the batchGet method.
    GetReportsResponse response = service.reports().batchGet(getReport).execute();

    // Return the response.
    return response;
  }

  /**
   * Parses and prints the Analytics Reporting API V4 response.
   *
   * @param response An Analytics Reporting API V4 response.
   */
  private static void printResponse(GetReportsResponse response) {

    for (Report report: response.getReports()) {
      ColumnHeader header = report.getColumnHeader();
      List<String> dimensionHeaders = header.getDimensions();
      List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
      List<ReportRow> rows = report.getData().getRows();

      if (rows == null) {
         System.out.println("No data found for " + VIEW_ID);
         return;
      }

      for (ReportRow row: rows) {
        List<String> dimensions = row.getDimensions();
        List<DateRangeValues> metrics = row.getMetrics();

        for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
          System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
       	}

        for (int j = 0; j < metrics.size(); j++) {
          System.out.print("Date Range (" + j + "): ");
          DateRangeValues values = metrics.get(j);
          for (int k = 0; k < values.getValues().size() && k < metricHeaders.size(); k++) {
            System.out.println(metricHeaders.get(k).getName() + ": " + values.getValues().get(k));
          }
        }
      }
    }
  }
}

4. הרצת הדוגמה

אם משתמשים בסביבת פיתוח משולבת (IDE), חשוב לוודא שיעד הריצה שמוגדר כברירת מחדל הוא המחלקה HelloAnalytics. אחרת, אפשר להדר ולהריץ את האפליקציה משורת הפקודה:

• ערכו את המדגם באמצעות:

  javac -classpath '/path/to/analyticsreporting/*:/path/to/analyticsreporting/libs/*' HelloAnalyticsReporting.java
  

• מריצים את הדוגמה באמצעות:

  java -classpath '.:/path/to/analyticsreporting/*:/path/to/analyticsreporting/libs/*' HelloAnalyticsReporting
  

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

הערה: כדי להריץ את הדוגמה הזו בהצלחה, צריך להיות לכם לפחות נכס אחד ותצוגה מפורטת אחת ב-Google Analytics.