オーディエンスのエクスポートの基礎

Google アナリティクス 4 のオーディエンスを使用すると、ビジネスの目的に合わせてユーザーをセグメント化できます。オーディエンスを使用すると、共通の属性に基づいてサイトまたはアプリのユーザーをグループ化できます。

Google Analytics Data API v1 を使って、オーディエンスに含まれるユーザーのスナップショットを含むオーディエンスのエクスポートを生成できます。

オーディエンスのエクスポートを作成する

Google Analytics Data API v1 は、非同期のアプローチでオーディエンスのエクスポートを作成します。まず、ユーザーのオーディエンス エクスポートを作成するには、audienceExports.create メソッドへのリクエストが必要です。次に、audienceExports.query メソッドを使用して、オーディエンスに含まれるユーザーを取得します。

また、audienceExports.get を使用して特定のオーディエンスのエクスポートに関する設定メタデータを取得し、audienceExports.list を使用してプロパティのすべてのオーディエンスのエクスポートを一覧表示できます。

報告エンティティを選択

Data API v1 のすべてのメソッドで、URL リクエストパス内に properties/GA4_PROPERTY_ID の形式で Google アナリティクス 4 プロパティ識別子を指定する必要があります。次に例を示します。

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

レポートは、指定した Google アナリティクス 4 プロパティで収集された Google アナリティクス イベントデータに基づいて生成されます。

Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを手動で操作する必要はありません。ほとんどの API クライアントには、properties/GA4_PROPERTY_ID 形式の文字列を必要とする property パラメータが用意されています。クライアント ライブラリの使用例については、クイック スタートガイドをご覧ください。

オーディエンスのエクスポートの作成をリクエストする

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

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

オーディエンスのエクスポート作成リクエストの例:

HTTP リクエスト

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

audienceExports.create メソッドのレスポンスでは、name フィールドにオーディエンス エクスポート名（properties/1234567/audienceExports/123 など）が含まれます。この名前を後続のクエリで使用して、オーディエンス エクスポートからユーザーを取得できます。

HTTP レスポンス

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

オーディエンスのエクスポートの準備状況を照会する

audienceExports.create の呼び出し後、オーディエンスのエクスポートが生成されるまでに数分かかることがあります。オーディエンスのエクスポートの準備状況を取得するには、audienceExports.get メソッドを呼び出します。

audienceExports.create レスポンスで受け取ったオーディエンス エクスポート名（properties/1234567/audienceExports/123 など）を使用して、オーディエンス エクスポートを指定します。

例:

HTTP リクエスト

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

オーディエンスのエクスポートの準備状況は、レスポンスの state フィールドに返されます。オーディエンスのエクスポートの生成が完了すると、状態は CREATING から ACTIVE に変わります。

HTTP レスポンス

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

すべてのオーディエンスのエクスポートの状態を取得するには、audienceExports.list メソッドを呼び出します。

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

audienceExports.create メソッドを使用して作成されたオーディエンス エクスポートが生成されたら、audienceExports.query メソッドを呼び出して、オーディエンス エクスポートの名前（properties/1234567/audienceExports/123 など）を指定します。

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
}

オーディエンスのエクスポート データに関する想定

次のセクションでは、オーディエンスのエクスポートでのユーザー メンバーシップについて想定されるデータについて説明します。

データの更新速度

オーディエンス エクスポート データの更新頻度とは、Google アナリティクスがイベントを収集してイベントを処理し、オーディエンスのユーザー メンバーシップを更新するのにかかる時間のことです。このプロセス全体に 24 時間かかる場合、オーディエンス エクスポート データの更新頻度は 24 時間となります。詳細については、データの更新頻度をご覧ください。

たとえば、ユーザーが最初の購入を完了し、その 7 時間後に「購入者」オーディエンスのオーディエンス エクスポートを作成した場合、そのユーザーはまだ「購入者」オーディエンスのエクスポートに含まれないことはほぼ間違いありません。そのユーザーは、最初の購入から 14 ～ 38 時間後に新しいオーディエンスのエクスポートを開始します。

オーディエンスのエクスポートはスナップショット

オーディエンスのエクスポートは、特定の時点でのオーディエンスに含まれるユーザーのリストです。Google 広告リマーケティングの場合、Google アナリティクスは、オーディエンス内のユーザーを自動的かつ継続的に Google 広告にエクスポートします。一方、Data API v1 を使用して作成されたオーディエンスのエクスポートでは、そのオーディエンスの最新のユーザーを表示するには、新しいオーディエンスのエクスポートを作成する必要があります。

オーディエンスのエクスポートは、利用可能な最新のユーザー メンバーシップに基づいて作成されます。ただし、オーディエンスのエクスポートでは、データの更新頻度がたとえば 20 時間になる場合があります。つまり、オーディエンスのエクスポートは、現時点での 20 時間前のすべてのイベントに基づいて行われます。

最新のメンバーシップ データは 1 日に 1 回更新されます（通常はプロパティのタイムゾーンの昼間）。つまり、午前 9 時と午前 11 時の同じオーディエンスのオーディエンスのエクスポートでは同じデータが返される可能性がありますが、たとえば午後 3 時のオーディエンスのエクスポートでは、追加日のデータを含めると異なる場合があります。

オーディエンスのエクスポートの有効期限

オーディエンスのエクスポートは 72 時間後に期限切れとなります。毎日、新規ユーザーがオーディエンスに参加したり、そこから離脱したりする可能性があります。最新のユーザー スナップショットを取得するには、毎日新しいオーディエンスのエクスポートを作成する必要があります。

オーディエンスのエクスポートのユーザー数の上限

オーディエンスまたはプロパティのサイズがユーザーの上限を超えると、オーディエンスのエクスポートではオーディエンスの代表サンプルが返されます。これらの制限はプロパティ タイプ（標準プロパティまたは 360 プロパティ）によって異なり、各オーディエンスのエクスポートで個別に適用されます。リピーターとは、リクエストされたオーディエンスに含まれるユーザーを指します。ユーザーは、オーディエンスのメンバーになる場合もあれば、そうでない場合もあります。

制限のタイプ 標準プロパティの上限 アナリティクス 360 プロパティに関する制限事項
最大リピーター数 200 万回 2 億
最大検討ユーザー数 1,000 万 10 億

レポート用識別子の整合性

レポート用識別子は、レポートでユーザーの重複をどのように除去するかを決定します。オーディエンスのエクスポートは、レポート用識別子の設定に基づいて変更されません。 オーディエンスのエクスポートでは、常に User-ID、デバイス ID の順にユーザーを識別します。

つまり、オーディエンスのレポートには、オーディエンスのエクスポートで得られた数よりも多くのユーザーが表示される可能性があります。たとえば、レポート ID が「デバイスベース」でユーザー ID が収集されている場合、レポートではユーザー ID に基づいてユーザーの重複が除去されませんが、オーディエンスのエクスポートではユーザー ID に基づいて重複が除去されます。

バックフィルの整合性

Google アナリティクスでオーディエンスを作成して Google 広告のリマーケティングを有効にすると、Google アナリティクスでは、最近追加されたメンバーに基づいて Google 広告の該当オーディエンスがバックフィルされます。ただし、Google アナリティクスのレポートとオーディエンスのエクスポートには、バックフィルされたオーディエンスのメンバーは含まれません。オーディエンスの作成後にユーザーがイベントをロギングすると、レポートとオーディエンスのエクスポートでそのオーディエンスにユーザーが表示されます。

たとえば、ユーザーが 6 月 20 日に購入イベントを記録し、お客様が 6 月 21 日に「購入者」オーディエンスを作成した場合、新しいオーディエンスのエクスポートでそのユーザーが表示されるようになるには、6 月 22 日まで待つ必要があります。ただし、このユーザーがオーディエンス エクスポートの対象になるのは、6 月 21 日にユーザーがなんらかのイベントを記録している場合のみです。