報表工作基礎知識

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

凡是擁有 Google Analytics (分析) 資源讀取權限的使用者，都能透過此要求產生的報表工作資源存取自訂報表。

自訂報表建立完畢後的 72 小時內可供查看。這段期間過後，相對應的報表工作資源及其內容會自動刪除。

建立報表工作

Google Analytics (分析) Data API v1 採用非同步方式建立報表工作。首先，您必須對 reportTasks.create 方法發出要求，才能建立報表工作。接著，reportTasks.query 方法會用於擷取產生的自訂報表。

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

選取檢舉實體

所有 Data API v1 方法都需要 Google Analytics (分析) 4 資源 ID，在網址要求路徑內指定，格式為 properties/GA4_PROPERTY_ID，例如：

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

報表是根據指定 Google Analytics (分析) 4 資源中收集到的 Google Analytics (分析) 事件資料產生。

如果您使用其中一個 Data API 用戶端程式庫，則不需要手動操控要求網址路徑。多數 API 用戶端提供的 property 參數預期字串格式為 properties/GA4_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"
  }
}