REST Resource: customers.userLists

資源：UserList

定義廣告資料中心管理的使用者名單。

JSON 表示法 
{
  "name": string,
  "userListId": string,
  "adsDataCustomerId": string,
  "title": string,
  "description": string,
  "type": enum (UserListType),
  "createEmail": string,
  "listSize": string,
  "populateTime": string,
  "recipientAdsDataLinks": [
    string
  ],
  "state": enum (State),

  // Union field user_list can be only one of the following:
  "frequencyList": {
    object (FrequencyBasedListInfo)
  },
  "remarketingList": {
    object (RemarketingListInfo)
  }
  // End of list of possible types for union field user_list.
}
欄位
name

string

僅供輸出。可明確識別廣告資料中心使用者名單的名稱。格式為 customer/[customerId]/userLists/[userListId]
userListId

string (int64 format)

僅供輸出。使用者名單 ID。這個欄位是由服務產生，並用於填入 UserList。
adsDataCustomerId

string (int64 format)

不可變動。與這份使用者名單連結的已連結廣告資料中心客戶 ID。使用這個使用者名單執行 UserListQuery 工作時，這個 ID 必須指定為 adsDataCustomerId。如未設定，則會使用上層客戶。清單建立後即無法變更這項設定。
title

string

必要，使用者清單標題，指定的 adsDataCustomerId 不得重複。
description

string

必要，使用者名單說明。
type

enum (UserListType)

僅供輸出。UserList 類型值應與 userList 一致。這個值為唯讀，可供您在取得/清單請求中存取。
createEmail

string

僅供輸出。建立這份使用者名單的使用者電子郵件地址。
listSize

string (int64 format)

僅供輸出。使用者名單的使用者人數。清單大小更新作業可能會延遲。
populateTime

string (Timestamp format)

僅供輸出。清單上次填入的時間。

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
state

enum (State)

僅供輸出。使用者名單狀態 (有效/已刪除)。這個值為唯讀，可供您在取得/清單請求中存取。

聯集欄位 user_list。根據使用者名單類型進一步設定。

只能設定其中一個。user_list 只能是下列其中一個值：
frequencyList

object (FrequencyBasedListInfo)

展示頻率上限的使用者名單。
remarketingList

object (RemarketingListInfo)

再行銷名單

使用者名單類型

使用者清單種類。指定時間點的使用者名單建構和使用方式，取決於這個列舉。清單建立後就無法切換類型。

列舉
USER_LIST_TYPE_UNSPECIFIED 預設值：請勿使用。
REMARKETING 透過 ADH 建立 SQL 查詢建立的再行銷目標對象。再行銷名單可用於指定肯定和排除。
FREQUENCY_BASED 頻率受限的目標對象：這類目標對像只能使用排除指定目標。

依據頻率清單資訊

以頻率為準的使用者名單中繼資料。

JSON 表示法 
{
  "dv360LineitemIds": [
    string
  ],
  "cmCampaignIds": [
    string
  ],
  "googleAdsCampaignIds": [
    string
  ],
  "eventMatchers": [
    {
      object (EventMatcher)
    }
  ],
  "frequencyConstraint": {
    object (FrequencyConstraint)
  },
  "slidingWindowDays": integer
}
欄位
dv360LineitemIds[]
(deprecated)

string (int64 format)

影響展示頻率的 DV360 委刊項 ID。
cmCampaignIds[]
(deprecated)

string (int64 format)

促成展示頻率的 CM 廣告活動 ID。
googleAdsCampaignIds[]
(deprecated)

string (int64 format)

促成展示頻率的 Google Ads 廣告活動 ID。
eventMatchers[]

object (EventMatcher)

特定事件影響到頻率。建立以頻率為準的使用者名單時，建議您使用 eventMatcher 來指定對頻率有貢獻的事件。如果 eventMatcher 空白，則會使用 dv360LineitemIds、cmCampaignIds 和 googleAdsCampaignIds。
frequencyConstraint

object (FrequencyConstraint)

說明將使用者新增至名單的時間。
slidingWindowDays

integer

必要，用於計算每個事件頻率的時段大小。以天為單位

事件比對器

影響頻率的一般事件。

JSON 表示法 
{
  "matchType": enum (MatchType),
  "value": string
}
欄位
matchType

enum (MatchType)

要包含在頻率計數中的限制類型。
value

string

限制的值。舉例來說，指定 Google Ads 廣告活動的 ID = 1234 時，matchType 應為 GOOGLE_ADS_CAMPAIGN_ID，值會是 '1234'。具有每個相符比對類型值的事件會納入展示頻率中。

比對類型

頻率規定的支援類型。日後我們可能會在更多列舉中新增更多類型，以支援其他限制。您可以在 ExplainValidfrequencyLimitingEventMatchersRequest 中，在 MatchType 中指定篩選條件，將結果中傳回的事件比對器限制為 API 支援的事件。舉例來說，將篩選器設為 "eventMatcher.match_type= CM_CAMPAIGN_ID OR eventMatcher.match_type=GOOGLE_ADS_CAMPAIGN_ID" 就只會傳回這兩個類型的 EventMatcher。

列舉
MATCH_TYPE_UNSPECIFIED 預設值。未使用這個值。
CM_CAMPAIGN_ID 代表 Campaign Manager 廣告活動 ID 的限制。
DV360_INSERTION_ORDER_ID 代表 DV360 廣告訂單 ID 的限制類型。
DV360_LINE_ITEM_ID 代表 DV360 委刊項 ID 的限制類型。
GOOGLE_ADS_CAMPAIGN_ID 代表 Google Ads 廣告活動 ID 的限制類型。

頻率限制

指定上限的事件數量。

JSON 表示法 
{
  "eventType": enum (EventType),
  "thresholdEventCount": string
}
欄位
eventType

enum (EventType)

不可變動。根據 countEventCount 計算的事件類型。目前我們通常不會假設比較限制為 GREATER_OR_EQUAL。
thresholdEventCount

string (int64 format)

必要，每位使用者至少應有 K 個事件。

EventType

可用於計算頻率的事件類型。

列舉
EVENT_TYPE_UNSPECIFIED 預設值：請勿使用。
IMPRESSIONS 計算所有曝光。

再行銷名單資訊

再行銷名單的中繼資料。

JSON 表示法 
{
  "userListQuery": string,
  "populatingUserListQueries": [
    string
  ]
}
欄位
userListQuery

string

不可變動。廣告資料中心使用者查詢資源，指定將使用者新增至這個目標對象的方式。格式如下：customer/[customerId]/userListQuery/[query_resource_id]
populatingUserListQueries[]

string

僅供輸出。廣告資料中心使用者名單查詢資源已填入這個目標對象。如果 1:1 userlist:query 限制生效前，這個欄位就可用來支援由多項查詢填入的使用者名單。格式如下：customer/[customerId]/userListQuery/[query_resource_id]

狀態

使用者名單狀態。

列舉
STATE_UNSPECIFIED 預設 / 未設定的值。
STATE_ACTIVE 使用者仍處於開啟狀態並處於有效狀態。
STATE_DELETED 使用者清單已標示為已刪除，不應再用於指定目標

方法

addEventMatchers

 將事件比對器新增至以頻率為準的使用者名單。

addRecipients

 將實體加進廣告資料中心管理的使用者名單收件者。

create

 建立由廣告資料中心管理的使用者名單。

delete

 刪除所要求廣告資料中心管理的使用者名單。

generateFrequencyListMemberships

 為 UserList 產生會員資格。

get

 擷取所要求廣告資料中心管理的使用者名單。

list

 列出由指定廣告資料中心客戶管理的使用者名單。

patch

 更新所請求的廣告資料中心管理的使用者名單。

removeRecipients

 從廣告資料中心管理的使用者收件者中移除實體。