報表工作基本概念

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

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

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

建立報表工作

Google Analytics Data API v1 採用非同步方式建立報表工作。首先，必須向 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 事件資料產生。

如果您使用其中一個 Google 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"
  }
}