レポートタスクの基礎

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

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

カスタマイズされたレポートは、準備が完了してから 72 時間利用できます。この期間を過ぎると、対応するレポートタスク リソースとそのコンテンツは自動的に削除されます。

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

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

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

レポート エンティティを選択する

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

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