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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • audience フィールドの有効なオーディエンス名（properties/{propertyId}/audiences/{audienceId} 形式）。この値は、Google Analytics 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 を使用すると、プロパティのすべての定期的なオーディエンス リストを一覧表示できます。

Webhook を使用して、新しいオーディエンス リストに関する非同期通知を受信する

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

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

Google アナリティクス 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
}