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

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
}