レポートタスクの基礎

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

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

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

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

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

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

報告エンティティを選択する

Data API v1 のすべてのメソッドでは、Google アナリティクス プロパティ IDを 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"
  }
}