レポートタスクの基本

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

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

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

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

Google Analytics 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 メソッドを呼び出します。次のパラメータを指定します。

レポートタスク作成リクエストの例:

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

次のステップ