本頁面由 Cloud Translation API 翻譯而成。

週期性目標對象名單

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

週期性目標對象名單會在目標對象成員變更時，每天產生目標對象名單，以確保使用最新的資料。

一般 (非週期性) 目標對象名單是名單產生時，目標對像中的靜態使用者名單。

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

處理一天的目標對象資料並更新成員資格需要不同的時間。無法確認目標對象名單資料在 24 小時內更新。

舉例來說，即使您每天在同一時間要求目標對象名單，某幾天的目標對象名單與前一天相同，在其他日期也會有所不同，而且包含第二天的成員資格異動。

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

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

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

週期性目標對象名單只有在另一天可用資料時，才會產生目標對象名單。您不必再憑空猜測新建目標對象名單的時機。相反地，您可以全日輪詢週期性目標對象名單，看看是否有其他資料。

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

建立週期性目標對象名單

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

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

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

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

請參閱 Async audience lists with webhooks 指南，進一步瞭解如何在 Google Analytics Data API v1 中使用 Webhook。

在目標對象匯出檔案中擷取使用者

如要擷取目標對象匯出項目中的使用者，請呼叫 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
}