繰り返しオーディエンス リスト

このドキュメントでは、Google Analytics Data API v1 の高度な機能である定期的なオーディエンス リストについて説明します。オーディエンス リストのエクスポート機能の概要については、オーディエンスのエクスポートの基本ガイドをご覧ください。

定期的なオーディエンス リストは、オーディエンス メンバーシップの変更に応じて毎日オーディエンス リストを生成し、最新のデータを使用できるようにします。

通常の（繰り返しなし）オーディエンス リストは、リストが生成された時点のオーディエンスのユーザーの静的リストです。

新しいオーディエンス リストを毎日作成する

1 日分のオーディエンス データを処理してメンバーシップを更新するのにかかる時間は、変動します。オーディエンス リストのデータが 24 時間以内に更新されることを保証する方法はありません。

たとえば、毎日同じ時間にオーディエンス リストをリクエストしても、前日と同じオーディエンス リストが返される日もあれば、異なるオーディエンス リストが返され、メンバーシップの変更が 1 日分追加されている日もあります。

毎日新しいオーディエンス リストを作成する

オーディエンス リストは、メンバーシップの最新の変更の 1 日前のイベントデータに基づいています。メンバーシップの毎日の更新が行われる前にオーディエンス リストを作成すると、2 日前のデータが使用されます。メンバーシップの毎日の更新後にオーディエンス リストを作成すると、前日のデータが使用されます。

定期的に定期的なオーディエンス リストをポーリングする

定期的なオーディエンス リストは、追加の日のデータが利用可能になった場合にのみオーディエンス リストを生成します。これにより、新しいオーディエンス リストを作成するタイミングを推測する必要がなくなります。代わりに、1 日を通して定期的なオーディエンス リストを安価にポーリングして、追加のデータが利用可能かどうかを確認できます。

1 日を通して定期的に繰り返しオーディエンス リストをポーリングする

定期的なオーディエンス リストを作成する

定期的なオーディエンス リストを作成するには、リクエスト内の RecurringAudienceList オブジェクトを使用して recurringAudienceLists.create メソッドを呼び出します。次のパラメータを指定します。

  • audience フィールドの有効なオーディエンス名（properties/{propertyId}/audiences/{audienceId} 形式）。この値を取得するには、Google アナリティクス Admin API v1 の audiences.list メソッドを使用します。audiences.list レスポンスの Audience.name フィールドには、オーディエンス名が含まれています。
  • dimensions フィールドの有効なディメンションのリスト。このメソッドでサポートされているディメンションのリストについては、オーディエンス エクスポート スキーマのドキュメントをご覧ください。このフィールドで指定されたディメンションのデータのみがオーディエンス リストに含まれます。

定期的なオーディエンス リストの作成リクエストの例を次に示します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

recurringAudienceLists.create メソッドのレスポンスには、name フィールド（properties/1234567/recurringAudienceLists/123 など）に名前が含まれています。この名前は、後続のクエリでこの定期的なユーザーリストの構成メタデータを取得するために使用できます。また、構成メタデータには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名が含まれています。

HTTP レスポンス

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

構成メタデータをポーリングする

recurringAudienceLists.get メソッドを使用して、特定の定期的なユーザーリストに関する構成メタデータを取得します。構成メタデータには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名が含まれています。

次の例をご覧ください。

HTTP リクエスト

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

レスポンスで RecurringAudienceList のインスタンスが返されます。これには、この定期的なオーディエンス リスト用に作成されたオーディエンス リスト インスタンスのリソース名を含む構成メタデータが含まれます。

HTTP レスポンス

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

recurringAudienceLists.list を使用すると、プロパティの定期的なオーディエンス リストをすべて一覧表示できます。

ウェブフックを使用して、新しいオーディエンス リストに関する非同期通知を受け取る

recurringAudienceLists.get メソッドを使用して特定の定期的なオーディエンス リストに関する構成メタデータを定期的にポーリングする代わりに、オーディエンス リストが使用可能になったときに Webhook 通知を非同期で受信できます。

Webhook 通知を構成するには、新しい定期的なオーディエンス リストの作成時に webhookNotification フィールドを指定します。

Google Analytics Data API v1 での Webhook の使用について詳しくは、Async audience lists with webhooks ガイドをご覧ください。

オーディエンスのエクスポートでユーザーを取得する

オーディエンス エクスポート内のユーザーを取得するには、audienceExports.query メソッドを呼び出し、recurringAudienceLists.get または recurringAudienceLists.list によって提供される構成メタデータから取得したオーディエンス エクスポート名を指定します。

HTTP リクエスト

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

オーディエンス エクスポートの準備が整うと、オーディエンス内のユーザーのリストを含むレスポンスが返されます。

HTTP レスポンス

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}