本文說明如何使用「多管道漏斗報表 API」存取「多管道漏斗資料」。
簡介
使用「多管道漏斗報表 API」時，您可以使用「多管道漏斗」標準和自訂報表中的表格資料。如要存取資料，您可以建立查詢指定下列項目：資料檢視 (設定檔)、開始與結束日期，以及構成資料表中欄標題的維度和指標。這項查詢會傳送至「多管道漏斗報表 API」，而「多管道漏斗報表 API」會以表格的形式傳回所有資料。
如果您是第一次使用 API，請參閱 Multi-ChannelFunnel Reporting API 總覽，瞭解 Multi-ChannelFunnel Reporting API 及其提供的資料。
事前準備
本指南使用 Java 用戶端程式庫存取 Multi-ChannelFunnel Reporting API。每個用戶端程式庫都會提供一個 Analytics (分析) 服務物件，用來呼叫 Multi-ChannelFunnel Reporting API 取得資料。如果您不透過用戶端程式庫存取 API，請參閱 Multi-ChannelFunnel Reporting API - 參考指南。
如要建立 Analytics (分析) 服務物件，請按照下列步驟操作：
- 在 Google API 控制台中註冊應用程式。
- 授權存取 Google Analytics (分析) 資料。
- 撰寫程式碼來建立 Analytics (分析) 服務物件。
如果您尚未完成這些步驟，請停止並參閱 Hello Analytics API 教學課程，其中將帶您瞭解建構 Google Analytics API 應用程式的初始步驟。完成教學課程後，請繼續閱讀下列指南。
舉例來說，下列程式碼會 建立已授權的 Analytics (分析) 服務物件：
Java
Analytics analytics = initializeAnalytics();
使用 Analytics (分析) 服務物件 analytics 呼叫 Multi-ChannelFunnel Reporting API。
總覽
如要使用「多管道漏斗報表 API」擷取資料，請將應用程式寫入以下位置：
- 查詢「多管道漏斗報表 API」。
- 處理從 API 傳回的結果。
查詢「多管道漏斗報表 API」
如要透過 Multi-ChannelFunnel Reporting API 要求資料，請按照下列步驟操作：
- 建立 Multi-ChannelFunnel Reporting API 查詢物件。
- 使用查詢物件向多管道漏斗伺服器要求資料。
建立 Multi-ChannelFunnel Reporting API 查詢
如要建立 Multi-ChannelFunnel Reporting API 查詢物件，請呼叫此方法：
analytics.data.mcf.get() // analytics is the Analytics service object
提供給方法的第一個參數是格式為 ga:XXXX 的不重複資料表 ID，其中 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 用戶端程式庫 Multi-ChannelFunnel Reporting API 範例