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

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
}