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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • audience フィールドの有効なオーディエンス名。形式は properties/{propertyId}/audiences/{audienceId} です。 この値を取得するには、Google Analytics Admin API v1 の audiences.list メソッドを使用します。 Audience.name フィールドに audiences.list レスポンスのオーディエンス名が含まれています。
  • 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 フィールドを指定します。

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

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

オーディエンスのエクスポートでユーザーを取得するには、 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
}