報表工作基礎知識

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

透過此要求產生的「報表工作」資源可用於存取 為所有具備 Google Analytics 讀取權限的使用者自訂報表 資源。

自訂報表在製作完成後 72 小時內可供下載。之後 期間，相應的報表工作資源及其內容 自動刪除。

建立報表工作

Google Analytics Data API v1 使用非同步方法 建立「報表工作」。首先，向 reportTasks.create敬上 方法為建立「報表工作」。接著， reportTasks.query敬上 方法用於擷取產生的自訂報表。

另外，您可以使用 reportTasks.get敬上 擷取特定「報表工作」和「報表工作」的相關設定中繼資料 reportTasks.list。 列出資源的所有報表工作。

選取報表實體

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

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

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

如果您使用的是其中一個 Data API 用戶端程式庫， 您無須手動操作要求網址路徑。 大多數的 API 用戶端都會提供需要用到的 property 參數 字串，格式為 properties/GA_PROPERTY_ID。 如需範例，請參閱快速入門指南 用戶端程式庫

要求建立報表工作

如要建立「報表工作」，請呼叫 reportTasks.create敬上 方法，使用 ReportTask。 物件中一樣。以下是必要參數：

報表工作建立要求範例：

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敬上 方法。

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

範例：

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