未取樣報表開發人員指南

Google Analytics Management API 可讓您透過程式輔助方式建立未取樣報表。

簡介

未取樣報表是指使用未取樣資料產生的 Google Analytics (分析) 報表。「未取樣報表」目前僅供 Google Analytics (分析) 360 使用者使用。

這個 API 的用途如下：

擷取所有現有未取樣報表的設定資訊。建立一次性的未取樣報表。
查看未取樣報表的處理狀態。
處理完畢後，取得未取樣報表的資料檔案連結。
刪除未取樣報表。

擷取未取樣報表的資料

當您建立未取樣報表時，可能需要等候一段時間才能下載報表。未取樣報表的 status 欄位會指出該報表的處理程序是否完成。狀態標示為 COMPLETED 後，您可以使用 downloadType 和對應的下載詳細資料欄位，擷取包含報表資料的檔案。例如：

如果 downloadType 值為 GOOGLE_DRIVE，請使用 driveDownloadDetails 欄位。
如果 downloadType 值為 GOOGLE_CLOUD_STORAGE，請使用 cloudStorageDownloadDetails 欄位。

請勿使用持續的高頻率輪詢來檢查這些報告的狀態，因為每日配額可能會很快用完。查看「未取樣報表」狀態時，請求需要經過一段時間才能順利完成。

使用 Google Drive / Google Cloud Storage API

視傳送目的地 (Google 雲端硬碟或 Google Cloud Storage) 而定，您可以取得該檔案的對應連結。你可以透過 Drive API 或 Cloud Storage API，透過這個連結下載檔案。如要進一步瞭解如何擷取檔案，請參閱 Google Drive API 或 Google Cloud Storage API 說明文件。

舉例來說，如果未取樣報表儲存在 Google 雲端硬碟中，您可以對檔案的資源網址提出經過授權的 HTTP GET 要求，並加入查詢參數 alt=media。

GET /drive/v2/files/XXXXXX?alt=media
Host: www.googleapis.com
Content-length: 0
Authorization: Bearer ya29.AHESVbXTUv5mHMo3RYfmS1YJonjzzdTOFZwvyOAUVhrs

其中「XXXXXX」是未取樣報表 driveDownloadDetails.documentId

驗證

如果您打算將未取樣報表搭配雲端硬碟或 Cloud Storage API 使用來下載檔案，則在要求 OAuth 2.0 權杖時，除了 Analytics (分析) API 驗證範圍外，您還必須加入該 API 的對應驗證範圍。如此一來，這兩個 API 就能使用相同的驗證權杖。

刪除未取樣報表

您可以刪除已排定或已完成的未取樣報表，但是在產生報表的短暫期間內呼叫 delete，就會發生錯誤。刪除未取樣報表只會移除 Google Analytics (分析) 資料檢視 (設定檔) 中的資源，但從 Google 雲端硬碟或 Google Cloud Storage 匯出的資料仍會保留。

限制

建立未取樣報表時有以下限制：

您最多只能指定 4 個維度。
不支援部分類型的報表資料，例如 Google Ads 資料。
不支援價格過高的查詢。
如果您建立太多未取樣報表，且達到限制，可以放心刪除未取樣報表資源，在 Google 雲端硬碟或 Google Cloud 中保留完整的報表資料。

如果判定要求費用過高，則建立作業會傳回錯誤並提供適當的訊息。如果發生這種情況，你可以：

要求較少維度。
將查詢分割成多個日期範圍較小的查詢，然後將產生的報表拼接在一起。

應用實例

未取樣報表和 Core Reporting API

如果您使用 Core Reporting API 擷取報表資料，且其中包含取樣資料，就可以針對這項查詢建立未取樣報表，方法如下：

提出 Core Reporting API 要求。
在回應中檢查 includeSampledData 屬性，確認資料是否已取樣。
如果這個屬性設為 true，您可以使用相同回應中的查詢和 profileInfo 欄位，建立未取樣報表的要求。

Core Reporting API 回應的查詢欄位範例：

"query": {
  "start-date": "2011-01-01",
  "end-date": "2011-01-31",
  "ids": "ga:1234",
  "dimensions": "ga:browser",
  "metrics": [
  "ga:visits"
  ],
  "filters": "ga:country==US",
  "start-index": 1,
  "max-results": 1000
}

Core Reporting API 回應中的 profileInfo 範例欄位：

"profileInfo": {
  "profileId": "1234",
  "accountId": "12345",
  "webPropertyId": "UA-12345-1",
  "internalWebPropertyId": "11254",
  "profileName": "Name of the profile",
  "tableId": "ga:1234"
}

以下範例說明如何透過 Core Reporting API 回應建立未取樣報表：

Java

// Make a Core Reporting API call.
GaData reportingApiData = v3.data().ga().get(...).execute();

// Check if the response is sampled.
if (reportingApiData.getContainsSampledData()) {

  // Use the “query” object to construct an unsampled report object.
  Query query = reportingApiData.getQuery();
  UnsampledReport report = new UnsampledReport()
      .setDimensions(query.getDimensions())
      .setMetrics(Joiner.on(',').join(query.getMetrics()))
      .setStartDate(startDate)
      .setEndDate(endDate)
      .setSegment(query.getSegment())
      .setFilters(query.getFilters())
      .setTitle(“My unsampled report”);

  // Use “profileInfo” to create an InsertRequest for creating an
  // unsampled report.
  ProfileInfo profileInfo = reportingApiData.getProfileInfo();
  Insert insertRequest = analytics.management().unsampledReports()
  .insert(profileInfo.getAccountId(),
          profileInfo.getWebPropertyId(),
          profileInfo.getProfileId(),
          report);
  UnsampledReport createdReport = insertRequest.execute();
}

拼接數天的未取樣資料

您可以合併或合併多天的報表，以取得特定日期範圍內的未取樣資料。當未取樣資料要求過大時，這項功能就能派上用場。在這種情況下，您可以將要求分割成多個要求，並縮短日期範圍，然後再合併結果。

配額政策

如需建立未取樣報表時適用的限制和配額完整清單，請參閱 Configuration and Reporting API 限制與配額。