多管道程序報表 API - 開發人員指南

本文件說明如何使用 Multi-ChannelFunnel Reporting API 存取多管道程序資料。

引言

多管道程序報表 API 可讓您存取「多管道程序」標準和自訂報表中的表格資料。如要存取資料,您要建立的查詢會指定檢視表 (設定檔)、開始日期和結束日期,以及構成資料表中欄標題的維度和指標。這項查詢會傳送至 Multi-ChannelFunnel Reporting API,多頻道程序 Reporting API 則以表格形式傳回所有資料。

如果您是這個 API 的新手,請參閱多管道報表 API 總覽,瞭解多管道報表 API 的用途和提供的資料。

事前準備

本指南使用 Java 用戶端程式庫存取多管道報表 Reporting API。每個用戶端程式庫都提供單一 Analytics (分析) 服務物件,以便呼叫多管道報表 API 來取得資料。如果您不是使用用戶端程式庫存取 API,請參閱「多管道程序報表 API 指南」。

建立 Analytics (分析) 服務物件的步驟如下:

  1. Google API 控制台中註冊應用程式。
  2. 授予 Google Analytics (分析) 資料的存取權。
  3. 撰寫程式碼以建立 Analytics (分析) 服務物件。

若您尚未完成這些步驟,請停止閱讀並閱讀 Hello Analytics API 教學課程,這個教學課程會逐步引導您完成 Google Analytics API 應用程式的建構步驟。完成教學課程後,請繼續閱讀下列指南。

舉例來說,下列程式碼會建立已獲授權的 Analytics (分析) 服務物件

Java

Analytics analytics = initializeAnalytics();

使用 Analytics (分析) 服務物件 analytics 呼叫多管道報表 API。

總覽

如要使用 Multi-ChannelFunnel Reporting API 擷取資料,請寫入應用程式至:

  1. 查詢 Multi-ChannelFunnel Reporting API。
  2. 處理從 API 傳回的結果。

查詢多管道報表 API

如要透過 Multi-ChannelFunnel Reporting API 要求資料,請按照下列步驟操作:

  1. 建立 Multi-ChannelFunnel Reporting API 查詢物件。
  2. 使用查詢物件向多管道程序程序要求資料。

建立多管道報表 API 查詢

如要建立 Multi-ChannelFunnel Reporting API 查詢物件,請呼叫此方法:

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

提供給方法的第一個參數是不重複的資料表 ID,格式為 ga:XXXX,其中 XXXX 是包含要求資料的 Analytics (分析) 資料檢視 (設定檔) ID。使用查詢物件來指定查詢參數 (例如: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-ChannelFunnel 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-ChannelFunnel 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 傳回的主要資料會傳回 McfData.Rows 的 2 維 List。每個 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();
}

檢舉資訊

除了報表資料之外,查詢也會傳回資料的相關資訊 (例如報表 ID)。舉例來說,下列方法會列印報告資訊:

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) 傳回的取樣值與網頁介面上顯示的值不相符。詳情請參閱取樣

查看 (設定檔) 資訊

查詢回應包含網站資源 ID、資料檢視 (設定檔) 名稱和 ID,以及包含資料檢視的 Analytics (分析) 帳戶 ID (設定檔)。舉例來說,下列方法會將其列印至終端機 (標準輸出):

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 要求都可能與數十萬列的「多管道程序」資料相符。「多管道程序」報表 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

Google API Java 用戶端程式庫多管道程序 API 範例