本文說明如何使用「多管道漏斗報表 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 範例