報表工作基礎知識

您可以使用報表工作，啟動長時間執行的非同步要求，建立 Google Analytics 事件資料的自訂報表。

所有具備 Google Analytics 資源讀取權限的使用者，都可以透過這項要求產生的報表工作資源，存取自訂報表。

自訂報表準備就緒後，效期為 72 小時。這段時間過後，系統會自動刪除對應的報表工作資源及其內容。

建立報表工作

Google Analytics Data API 第 1 版採用非同步方法建立報表工作。首先，您必須對 reportTasks.create 方法發出要求，才能建立報表工作。接著，系統會使用 reportTasks.query 方法擷取產生的自訂報表。

此外，您可以使用 reportTasks.get 擷取特定報表工作的設定中繼資料，並使用 reportTasks.list 列出資源的所有報表工作。

選取報表實體

所有 Data API v1 方法都必須在網址要求路徑中指定Google Analytics 資源 ID，格式為 properties/GA_PROPERTY_ID，例如：

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

這份報表是根據指定 Google Analytics 資源中收集到的 Google Analytics 事件資料產生。

如果您使用資料 API 用戶端程式庫，就不需要手動操控要求網址路徑。大多數 API 用戶端都會提供 property 參數，該參數預期會收到 properties/GA_PROPERTY_ID 形式的字串。如需使用用戶端程式庫的範例，請參閱快速入門指南。

要求建立報表工作

如要建立報表工作，請在要求中使用 ReportTask 物件，呼叫 reportTasks.create 方法。以下是必要參數：

建立報表工作要求的範例：

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

reportTasks.create 方法的回應會在 name 欄位中包含報表工作名稱 (例如 properties/1234567/reportTasks/123)，可用於後續查詢，以取得報表工作的狀態並擷取產生的報表。

HTTP 回應

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

取得報表工作就緒狀態

通話結束後，系統可能需要幾分鐘才能生成報告。reportTasks.create您可以呼叫 reportTasks.get 方法，取得 Report Task 的就緒狀態。

使用從 reportTasks.create 回應收到的「Report Task」名稱 (例如 properties/1234567/reportTasks/123)，指定「Report Task」。

範例：

HTTP 要求

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

回應的 state 欄位會傳回報表工作的就緒狀態。報表產生完成後，報表工作狀態會從 CREATING 變更為 ACTIVE。

reportMetadata 欄位包含所產生報表的高階資訊，例如列數和配額權杖的費用。

HTTP 回應

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

您可以呼叫 reportTasks.list 方法，取得所有報表工作狀態。

擷取生成的報表

使用 reportTasks.create 方法建立報表工作後，請呼叫 reportTasks.query 方法，並指定報表工作名稱 (例如 properties/1234567/reportTasks/123)。

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

如果報表工作已完成，系統會傳回包含所產生報表的回應：

HTTP 回應

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}