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

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

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

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

概要

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

  1. audienceExports.create メソッドを呼び出して、オーディエンスのエクスポートを作成します。
  2. audienceExports.query メソッドを呼び出して、オーディエンスのユーザーを取得します。

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

レポートのエンティティを選択する

すべての Data API メソッドでは、Google アナリティクスのプロパティ 識別子を 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 メソッドを使用します。 Audience.name フィールドに audiences.list レスポンスのオーディエンス名が含まれています。
  • 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
}