建立目標對象匯出作業

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

您可以使用 Data API 匯出目標對象，包括使用者的快照。

如要進一步瞭解目標對象匯出資料的預期內容，請參閱目標對象匯出資料預期內容指南。

總覽

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

  1. 呼叫 audienceExports.create 方法，建立目標對象匯出作業。
  2. 呼叫 audienceExports.query 方法，用於擷取目標對象中的使用者。

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

選取報表實體

所有 Data API 方法都需要在網址要求路徑中指定 Google Analytics 資源 ID，格式為 properties/GA_PROPERTY_ID。範例如下：

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

報表會根據指定 Google Analytics 資源中收集到的 Google Analytics 事件資料產生。

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

建立目標對象匯出作業

如要建立目標對象匯出作業，請使用要求中的 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
}