週期性目標對象名單

本文說明週期性目標對象名單，這是 Google Analytics Data API 第 1 版的進階功能。如要瞭解目標對象名單匯出功能，請參閱目標對象匯出基本指南。

系統會每天產生週期性目標對象名單，確保您使用的是最新資料。

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

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

處理一天的目標對象資料並更新會員資格，所需時間不一。無法確保目標對象名單資料會在 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 v1 中使用 Webhook，請參閱Async audience lists with webhooks指南。

在目標對象匯出作業中擷取使用者

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