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

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

מבוא

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

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

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

לפני שתתחיל

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

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

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

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

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

Java

Analytics analytics = initializeAnalytics();

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

סקירה כללית

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

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

שליחת שאילתה ל-Reporting API למשפכים מרובי-ערוצים

כדי לבקש נתונים מ-Reporting API למשפכים מרובי-ערוצים:

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

יצירת שאילתה ב-Reporting API למשפכים מרובי ערוצים

כדי לבנות אובייקט שאילתה של ממשק 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);

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

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

אחרי שיוצרים אובייקט שאילתה, צריך לקרוא למתודה 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

אם שאילתת ה-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 לדיווח על משפכים מרובי-ערוצים עשויה להתאים למאות אלפי שורות של נתונים של משפכים מרובי-ערוצים. בכל יום נתון, ה-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());
}

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

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

סה"כ לכל התוצאות

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

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