建立目標對象匯出作業

Google Analytics (分析) 4 目標對象可讓您根據自家業務的需求區隔使用者。目標對像功能可讓您根據共用屬性，將網站或應用程式的使用者分組。

您可以使用 Data API 匯出目標對象 (包括使用者數據匯報)。

如要瞭解目標對象匯出功能中的資料相關重要資訊，請參閱「目標對象匯出資料預期」指南。

總覽

提出下列 Data API 要求，以建立及查詢目標對象匯出作業：

  1. 呼叫 audienceExports.create 方法來建立目標對象匯出項目。
  2. 呼叫 audienceExports.query 方法可用來擷取目標對像中的使用者。

如需詳細資訊，您可以呼叫 audienceExports.get 來擷取特定目標對象匯出作業的設定中繼資料，並呼叫 audienceExports.list 列出特定資源的所有目標對象匯出作業。

選取報表實體

所有 Data API 方法都需要以 properties/GA4_PROPERTY_ID 格式在網址要求路徑中指定 Google Analytics (分析) 4 資源 ID。範例如下：

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

系統會根據指定 Google Analytics (分析) 4 資源中收集到的 Google Analytics (分析) 事件資料產生報表。

如果您使用其中一個 Data API 用戶端程式庫，就不必變更要求網址路徑。大多數的 API 用戶端都會提供 property 參數，該參數預期使用 properties/GA4_PROPERTY_ID 形式的字串。如需用戶端程式庫的使用範例，請參閱快速入門指南。

建立目標對象匯出作業

如要建立目標對象匯出作業，請使用要求中的 AudienceExport 物件呼叫 audienceExports.create 方法。以下是必要參數：

  • 在 audience 欄位中的有效目標對象名稱，格式為 properties/{propertyId}/audiences/{audienceId}。您可以使用 Google Analytics Admin API 第 1 版的 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
}