Multi-Channel Reporting API – מדריך למפתחים

מסמך זה מסביר כיצד להשתמש ב-Reporting API של משפכים מרובי-ערוצים כדי לגשת לנתוני משפכים מרובי-ערוצים.

מבוא

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

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

הערה: ב-Multi-Channel Reporting API נעשה שימוש בחלון מבט לאחור של 30 יום שלא ניתן לשנות.

לפני שתתחיל

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

כדי ליצור את אובייקט השירות של Analytics:

1. רשום את האפליקציה שלך ב מסוף Google API.
2. הרשאת גישה לנתוני Google Analytics.
3. כותבים קוד כדי ליצור את אובייקט השירות של Analytics.

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

לדוגמה, הקוד הבא יוצר אובייקט מורשה של שירות Analytics:

Java

Analytics analytics = initializeAnalytics();

משתמשים באובייקט השירות של Analytics analytics כדי לקרוא ל-Multi-Channel Reporting API.

סקירה

כדי להשתמש ב-Multi-Channel Reporting API לאחזור נתונים, צריך לכתוב אפליקציה אל:

1. הרצת שאילתות ב-Multi-Channel Reporting API.
2. עבודה עם התוצאות שהוחזרו מה-API.

שליחת שאילתה ל-Multi-Channel Reporting API

כדי לבקש נתונים מ-Multi-Channel Reporting API:

1. בניית אובייקט שאילתה של ממשק API לדיווח על משפכים מרובי-ערוצים.
2. יש להשתמש באובייקט השאילתה כדי לבקש את הנתונים משרתי המשפכים מרובי-הערוצים.

יצירת שאילתה ב-Multi-Channel Reporting API

כדי ליצור אובייקט שאילתה ב-Multi-Channel Reporting API, צריך לקרוא לשיטה הבאה:

analytics.data.mcf.get()    // analytics is the Analytics service object

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

Java

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

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

שליחת בקשת נתונים ל-Multi-Channel Reporting API

לאחר יצירת אובייקט השאילתה, קרא לשיטה execute באובייקט כדי לבקש נתונים משרתי משפכים מרובי-ערוצים. למשל:

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

אם אתם מעדיפים לגשת במקום זאת לתגובת ה-API הגולמית, צריך לקרוא לשיטה executeUnparsed() באובייקט השאילתה:

HttpResponse response = apiQuery.executeUnparsed();

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

עבודה עם תוצאות ה-API

אם השאילתה ב-Multi-Channel Reporting API מצליחה, הוא מחזיר את נתוני הדיווח ומידע על הנתונים.

נתוני דיווח של משפכים מרובי-ערוצים

השאילתה מחזירה את נתוני הדיווח הבאים בטבלה:

• נתונים של כותרות עמודה
• נתוני שורה

נתונים של כותרות עמודה

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

Java

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

נתוני שורה

הנתונים העיקריים שמוחזרים מה-API מוחזרים כ-List דו-ממדי של McfData.Rows. כל McfData.Rows מייצג תא יחיד שהוא ערך ראשוני מסוג String או ערך של נתיב המרות מסוג McfData.Rows.ConversionPathValue. סדר התאים בשורה זהה לסדר השדות באובייקט כותרת העמודה שמתואר למעלה.

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

לדוגמה, השיטה הבאה מדפיסה את הכותרות והשורות של הטבלה:

Java

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

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

Java

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

פרטי הדוח

בנוסף לנתוני הדיווח, השאילתה מחזירה מידע על הנתונים (למשל, מזהה הדוח). לדוגמה, בשיטה הבאה אפשר להדפיס את פרטי הדוח:

Java

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

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

הצגה של פרטי (פרופיל)

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

Java

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

פרטי השאילתה

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

Java

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics());       // List of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

שיטות אחרות מלבד query.getMetrics(), query.getDimensions() ו-query.getSort() מחזירות String. לדוגמה, query.getStartDate() מחזירה את תאריך ההתחלה (String) של הדוח.

פרטי העימוד

כל בקשה של ממשק ה-API לדיווח של משפכים מרובי-ערוצים עשויה להתאים למאות אלפי שורות של נתונים של משפכים מרובי-ערוצים. ה-Multi-Channel Reporting API יחזיר רק קבוצת משנה, שנקראת דף יחיד של הנתונים, בכל זמן נתון. כדי לאחזר את כל דפי הנתונים, אפשר להשתמש בשדה העימוד. השיטה הבאה מדפיסה את פרטי העימוד:

Java

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

הקריאה ל-method mcfData.getTotalResults() מחזירה את המספר הכולל של השורות בשאילתה, שיכול להיות גדול יותר ממספר השורות הכולל שהשאילתה מחזירה. והקריאה ל-method mcfData.getItemsPerPage() מחזירה את מספר השורות המקסימלי שתגובת השאילתה יכולה להכיל.

הקריאה ל-method mcfData.getPreviousLink() מחזירה את הקישור לדף הקודם ו-mcfData.getNextLink() מחזירה את הקישור לדף הבא.

סיכומים עבור כל התוצאות

על מנת לקבל את הערכים הכוללים של המדדים המבוקשים בכל התוצאות, ולא רק את התוצאות שהוחזרו בתגובה לשאילתה, צריך לקרוא ל-method getTotalsForAllResults() בתגובת השאילתה, אובייקט McfData. משתמשים בערכים הכוללים כדי לחשב את הממוצעים.

Java

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

דוגמה פעילה

Java

ספריית לקוח Java ב-Google API דוגמה לממשק API של משפכים מרובי-ערוצים