レポートタスクの基礎

レポートタスクを使用すると、長時間実行される非同期リクエストを開始して、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"
  }
}