週期性目標對象名單

本文將說明 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 欄位中的有效維度清單。如要查看這個方法支援的維度清單，請參閱 Audience Export 結構定義說明文件。目標對象名單中只會納入此欄位中提及的維度資料。

以下是定期目標對象名單建立要求的範例：

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
}