レポートタスクを使用すると、長時間実行される非同期リクエストを開始して、Google アナリティクスのイベントデータのカスタマイズされたレポートを作成できます。
このリクエストから生成されたレポートタスク リソースを使用すると、Google アナリティクスのプロパティへの読み取り権限を持つすべてのユーザーがカスタマイズ レポートにアクセスできます。
カスタマイズしたレポートは、準備が整ってから 72 時間以内に利用できます。この期間が過ぎると、対応するレポートタスク リソースとその内容は自動的に削除されます。
レポートタスクを作成する
Google アナリティクス Data API v1 は、非同期アプローチを使用してレポートタスクを作成します。まず、レポートタスクを作成するには reportTasks.create
メソッドへのリクエストが必要です。次に、reportTasks.query
メソッドを使用して、生成されたカスタマイズされたレポートを取得します。
また、reportTasks.get
を使用して特定のレポートタスクに関する構成メタデータを取得し、reportTasks.list
を使用してプロパティのすべてのレポートタスクを一覧表示することもできます。
レポート対象エンティティを選択する
Data API v1 のすべてのメソッドでは、Google アナリティクス プロパティ ID を URL リクエスト パス内に properties/GA_PROPERTY_ID
の形式で指定する必要があります。次に例を示します。
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
このレポートは、指定した Google アナリティクス プロパティで収集された Google アナリティクスのイベントデータに基づいて生成されます。
Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA_PROPERTY_ID
の形式の property
パラメータが提供されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。
レポート タスクの作成をリクエストする
レポートタスクを作成するには、リクエストの ReportTask
オブジェクトを使用して reportTasks.create
メソッドを呼び出します。次のパラメータを指定します。
- カスタマイズされたレポートの定義を記述する
reportDefinition
フィールド。このパラメータの構造は、Core Reporting メソッドで使用されるレポート定義に似ています。
レポートタスクの作成リクエストの例:
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"
}
}