Multi-ChannelFunnel Reporting API - 參考指南

本文件提供 Multi-ChannelFunnel Reporting API 查詢和回應的完整參考資料。

簡介

您可以透過「Multi-ChannelFunnel Reporting API」要求 Google Analytics (分析) 多管道漏斗報表資料。每份報表都包含統計資料，衍生自追蹤程式碼傳回至 Analytics (分析) 的資料，並以維度和指標分類。自行選擇維度和指標的組合，您就能使用 Reporting API 按照自己的規格建立自訂報表。

API 包含單一要求報表資料的方法：report.get。使用這個方法時，您必須提供要擷取資料的資料檢視 (設定檔) 對應的資料表 ID。此外，您還指定下列內容：

• 維度和指標的組合。
• 日期範圍。
• 一組選項參數，用於控制要傳回哪些資料

API 於 REST 端點提供 report.get 方法： https://www.googleapis.com/analytics/v3/data/mcf。以下章節將顯示請求範例，並說明每個參數。

要求

API 提供單一要求資料的方法：

analytics.data.mcf.get()

此 API 也可做為 REST 端點進行查詢：

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/mcf
  ?ids=ga:12345
  &metrics=mcf:totalConversions,mcf:totalConversionValue
  &start-date=2011-10-01
  &end-date=2011-10-31

每個網址查詢參數都指定一個必須進行網址編碼的 API 查詢參數。

所有傳送至 Multi-ChannelFunnel Reporting API 的要求都必須透過 OAuth 2.0 授權。

查詢參數摘要

下表摘要列出 Multi-ChannelFunnel Reporting API 接受的所有查詢參數，按一下各參數名稱即可查看詳細說明。

查詢參數詳細資料

ids

返回開頭

開始日期

  &start-date=7daysAgo
  &end-date=yesterday

返回開頭

結束日期

  &start-date=9daysAgo
  &end-date=today

返回開頭

尺寸

返回開頭

metrics

返回開頭

排序

sort=mcf:source,mcf:medium

sort=mcf:medium,mcf:source

返回開頭

篩選器

https://www.googleapis.com/analytics/v3/data/mcf
?ids=mcf:12134
&dimensions=mcf:source
&metrics=mcf:totalConversions
&filters=mcf:medium%3D%3Dreferral
&start-date=2011-10-01
&end-date=2011-10-31

返回開頭

samplingLevel

返回開頭

max-results

返回開頭

回應

如果成功，這項要求就會傳回如下定義的 JSON 結構的回應主體。

注意事項：「結果」一詞是指符合查詢的整組資料列，而「回應」則是指目前結果頁面上傳回的一組資料列。如果結果總數大於目前回應的頁面大小，則結果可能會有所不同，詳情請參閱 itemsPerPage 頁面。

回應格式

{
  "kind": "analytics#mcfData",
  "id": string,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "sort": [
      string
    ],
    "filters": string,
    "samplingLevel": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "selfLink": string,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "containsSampledData": boolean,
  "sampleSize": string,
  "sampleSpace": string,
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
  "rows": [
    [
      McfData.Rows
    ]
  ],
}

返回開頭

回應欄位

回應主體結構的屬性定義如下：

{
  "primitiveValue": "2183"
}

{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

返回開頭

錯誤代碼

如果要求成功，Multi-ChannelFunnel Reporting API 會傳回 200 HTTP 狀態碼。如果處理查詢時發生錯誤，API 會傳回錯誤代碼和說明。每個使用 Analytics API 的應用程式都必須導入適當的錯誤處理邏輯。如要進一步瞭解錯誤代碼及其處理方式，請參閱 錯誤回應參考指南。

返回開頭

返回開頭

取樣

Google Analytics (分析) 會即時計算特定維度和指標的組合。為了在合理的時間內傳回資料，Google Analytics (分析) 可能只會處理資料樣本。

您可以設定 samplingLevel 參數，指定要求的取樣等級。

如果 MCF Reporting API 回應包含取樣資料，containsSampledData 回應欄位將會是 true。 此外，有 2 項屬性將提供查詢的取樣層級相關資訊：sampleSize 和 sampleSpace。您可以利用這 2 個值，計算用於查詢的工作階段百分比。舉例來說，如果 sampleSize 是 201,000 而 sampleSpace 是 220,000，則報表會以 (201,000 / 220,000) * 100 = 91.36% 的工作階段為依據。

如需取樣的一般說明及在 Google Analytics (分析) 中的使用方式，請參閱取樣一文。

返回開頭

處理大型資料結果

如果您預期查詢會傳回大型結果集，請參考下方指南協助您最佳化 API 查詢、避免錯誤，並將配額超額降到最低。請注意，為了設定效能基準，每個 API 要求最多可允許 7 個維度和 10 個指標。雖然某些指定大量指標和維度的查詢可能需要較長的處理時間，但限制要求的指標數量可能不足以改善查詢效能。建議您改用下列技巧，獲得最佳效能結果。

減少每次查詢的維度

API 可讓您在任何請求中指定最多 7 個維度。 很多時候，Google Analytics (分析) 必須即時計算這些複雜查詢結果。如果產生的資料列數量偏高，可能相當耗時。舉例來說，按城市 (按城市劃分) 查詢關鍵字，可能會符合數百萬列的資料。您可以限制查詢中的維度數量，減少 Google Analytics (分析) 需要處理的資料列數量，藉此提升效能。

按日期範圍拆分查詢

請考慮一次處理一週 (甚至是一天) 的個別查詢，而不是逐頁瀏覽某個較長的日期範圍 (以日期表示) 的結果。當然，對於大型資料集，即使要求的是一天資料，系統也可能傳回超過 max-results，這時無法避免分頁。但在任何情況下，如果查詢的相符資料列數高於 max-results，則分隔日期範圍可能會減少擷取結果的總時間。這個方法可以改善單一執行緒和平行查詢的效能。

Paging

逐頁瀏覽結果是將大型結果集分成多個可管理區塊的實用方法。totalResults 欄位會顯示相符的資料列數量，itemsPerPage 則提供結果中可獲得的資料列數量上限。如果 totalResults 到 itemsPerPage 的比例很高，則個別查詢的處理時間可能會超過必要。如果您只需要少量的資料列 (例如為了顯示用途)，透過 max-results 參數設定明確的回應大小限制會比較方便。不過，如果您的應用程式需要處理大量的大量結果，則要求允許的資料列數量上限可能更有效率。

使用 gzip

如果想要減少每個要求所需的頻寬，最簡單的方法就是啟用 gzip 壓縮。雖然此方法需要額外的 CPU 時間解壓縮結果，但相對可省下網路費用。如要接收以 gzip 編碼的回應，您必須執行下列兩項操作：設定 Accept-Encoding 標頭，並修改使用者代理程式來加入 gzip 字串。以下是啟用 gzip 壓縮的正確 HTTP 標頭格式範例：

Accept-Encoding: gzip
User-Agent: my program (gzip)