週期性目標對象名單

本文件說明週期性目標對象名單，這是 Google Analytics Data API v1 的進階功能。如需目標對象名單匯出功能的簡介，請參閱目標對象匯出基礎知識指南。

週期性目標對象名單會在目標對象成員資格發生變化時，每天產生目標對象名單，以確保您處理的是最新資料。

一般 (非週期性) 目標對象名單是目標對象名單產生當下的靜態使用者清單。

每日建立新的目標對象名單

處理一天的目標對象資料並更新成員資格所需的時間並不固定。無法確保目標對象名單資料會在 24 小時內更新。

舉例來說，即使您每天都要求一份目標對象名單，有幾天的目標對象名單會與前一天相同，而在其他日子，這份目標對象名單會和之前的名單比起來，會另外包含一天的成員資格變更。

每天建立新的目標對象名單

目標對象名單是以最近一次成員變更前一天的事件資料為依據。如果您在每日成員更新前建立目標對象名單，系統會使用前兩天的資料。如果您在每日成員資格更新後建立目標對象名單，系統會使用昨天的資料。

定期輪詢週期性目標對象名單

週期性目標對象名單只會在還有一天的資料可用時，產生目標對象名單。如此一來，您就不必再憑空臆測何時該建立新的目標對象名單。您可以改為對週期性目標對象名單整天進行低廉的輪詢，查看是否有其他資料可用。

在當日定期輪詢週期性目標對象名單

建立週期性目標對象名單

如要建立週期性的目標對象名單，請使用要求中的 RecurringAudienceList 物件呼叫 recurringAudienceLists.create 方法。以下是必要參數：

audience 欄位中的有效目標對象名稱，格式為 properties/{propertyId}/audiences/{audienceId}。您可以使用 Google Analytics Admin API v1 的 audiences.list 方法取得這個值。audiences.list 回應的 Audience.name 欄位包含目標對象名稱。
dimensions 欄位中的有效維度清單。如需這個方法支援的維度清單，請參閱「目標對象匯出架構」說明文件。只有這個欄位中提及的維度資料會納入目標對象名單。

以下是建立週期性目標對象名單申請的範例：

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

recurringAudienceLists.create 方法的回應包含 name 欄位的名稱 (例如 properties/1234567/recurringAudienceLists/123)，可用於後續查詢，以擷取此週期性目標對象名單的設定中繼資料。此外，設定中繼資料還包含為這份週期性目標對象名單建立的目標對象名單執行個體資源名稱。

HTTP 回應

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

意見調查設定中繼資料

使用 recurringAudienceLists.get 方法擷取特定週期性目標對象名單的設定中繼資料。設定中繼資料包含針對這份週期性目標對象名單建立的目標對象名單執行個體資源名稱。

範例如下：

HTTP 要求

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

系統會傳回 RecurringAudienceList 的執行個體。其中包含設定中繼資料，包括針對這份週期性目標對象名單建立的目標對象名單執行個體資源名稱。

HTTP 回應

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

您可以使用 recurringAudienceLists.list 列出資源的所有週期性目標對象名單。

使用 Webhook 接收新目標對象名單的非同步通知

與其使用 recurringAudienceLists.get 方法，以非同步方式接收特定週期性目標對象名單的設定中繼資料，而是在目標對象名單可供使用時，以非同步方式接收 Webhook 通知。

如要設定 Webhook 通知，請在建立新的週期性目標對象名單時指定 webhookNotification 欄位。

如要進一步瞭解如何在 Google Analytics Data API 第 1 版中使用 Webhook，請參閱 WebhookNotification 說明文件。

在目標對象匯出內容中擷取使用者

如要在目標對象匯出作業中擷取使用者，請呼叫 audienceExports.query 方法，並指定從 recurringAudienceLists.get 或 recurringAudienceLists.list 提供的設定中繼資料擷取的目標對象匯出名稱。

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
}