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

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

Data API を使用して、オーディエンス（ユーザーのスナップショットを含む）をエクスポートできます。

オーディエンス エクスポートに表示されるデータに関する重要な情報については、オーディエンス エクスポートのデータに関する注意事項をご覧ください。

概要

次の Data API リクエストを行って、オーディエンス エクスポートを作成してクエリします。

  1. audienceExports.create メソッドを呼び出して、オーディエンスのエクスポートを作成します。
  2. audienceExports.query メソッドは、オーディエンス内のユーザーを取得するために使用されます。

詳しくは、audienceExports.get を呼び出して特定のオーディエンス エクスポートに関する構成メタデータを取得するか、audienceExports.list を呼び出して特定のプロパティのすべてのオーディエンス エクスポートを一覧表示してください。

報告エンティティを選択する

すべての Data API メソッドでは、Google アナリティクス プロパティ IDを URL リクエスト パス内に properties/GA_PROPERTY_ID の形式で指定する必要があります。次の例をご覧ください。

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

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

Data API クライアント ライブラリのいずれかを使用している場合は、リクエスト URL パスを変更する必要はありません。ほとんどの API クライアントでは、文字列が properties/GA_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"
  }
}

name を使用して、オーディエンス エクスポートからユーザーをクエリできます。

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

audienceExports.create 呼び出し後、オーディエンスのエクスポートが生成されるまでに数分かかることがあります。

audienceExports.get メソッドを呼び出すことで、オーディエンス エクスポートの準備完了状態を確認できます。

audienceExports.create レスポンスのオーディエンス エクスポート名を使用して、リクエストでオーディエンス エクスポートを指定します。

リクエストの例を次に示します。

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.query メソッドを呼び出し、リクエストでオーディエンスのエクスポートの name を指定します。

リクエストの例を次に示します。

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
}