レポートタスクの基礎

レポートタスクを使用すると、長時間実行される非同期リクエストを開始し、Google アナリティクスのイベントデータのカスタム レポートを作成できます。

このリクエストによって生成された Report Task リソースを使用して、Google アナリティクス プロパティへの読み取りアクセス権を持つすべてのユーザーがカスタマイズしたレポートにアクセスできます。

カスタム レポートは、準備ができてから 72 時間有効です。この期間を過ぎると、対応するレポートタスク リソースとその内容は自動的に削除されます。

レポートタスクを作成する

Google Analytics Data API v1 は、非同期のアプローチでレポートタスクを作成します。まず、レポートタスクを作成するには、reportTasks.create メソッドへのリクエストが必要です。次に、reportTasks.query メソッドを使用して、生成されたカスタム レポートを取得します。

また、reportTasks.get を使用して特定のレポートタスクに関する構成メタデータを取得し、reportTasks.list を使用してプロパティのすべてのレポートタスクを一覧表示することもできます。

報告エンティティを選択

Data API v1 のすべてのメソッドで、URL リクエストパス内に properties/GA4_PROPERTY_ID の形式で Google アナリティクス 4 プロパティ識別子を指定する必要があります。次に例を示します。

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

レポートは、指定した Google アナリティクス 4 プロパティで収集された Google アナリティクス イベントデータに基づいて生成されます。

Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントには、properties/GA4_PROPERTY_ID 形式の文字列を必要とする property パラメータが用意されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。

レポートタスクの作成をリクエストする

レポートタスクを作成するには、リクエストで 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"
  }
}