報表工作基礎知識

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

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

自訂報表完成後，您可以 72 小時內下載。超過這個期限後，系統會自動刪除對應的報表工作資源及其內容。

建立報表工作

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

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

選取報表實體

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

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

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

如果您使用的是 Data 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 方法，取得報表工作項的準備就緒狀態。

使用您從 reportTasks.create 回應收到的報表工作名稱 (例如 properties/1234567/reportTasks/123)，指定報表工作。

範例：

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"
  }
}