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 一致。该值为只读，可通过 get/list 请求访问。
createEmail

string

仅供输出。创建此用户列表的用户的电子邮件地址。
listSize

string (int64 format)

仅供输出。用户名单中的用户数量。名单规模更新可能会延迟。
populateTime

string (Timestamp format)

仅供输出。上次填充列表的时间。

时间戳采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式，分辨率为纳秒级，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
state

enum (State)

仅供输出。用户名单的状态（有效/已删除）。该值为只读，可通过 get/list 请求访问。

联合字段 user_list。根据用户列表的类型进行进一步配置。

只能设置其中一个。user_list 只能是下列其中一项：
frequencyList

object (FrequencyBasedListInfo)

频次上限的用户列表。
remarketingList

object (RemarketingListInfo)

再营销名单。

用户名单类型

用户名单种类。在定位时用户名单的构建和使用取决于此枚举。列表在创建后不能切换类型。

枚举
USER_LIST_TYPE_UNSPECIFIED 默认值：不应使用。
REMARKETING 使用广告数据中心的 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)

哪些事件影响到频率。创建基于频次的用户名单时，系统会优先使用 eventMatchers 来指定影响展示频次的事件。如果 eventMatchers 为空，系统会使用 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'。为相应 MatchType 使用此值的事件将被纳入到频次计数中。

MatchType

频次计数支持的约束类型。未来可能会向此枚举中添加更多类型，以支持更多限制条件。您可以在 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)

不可变。将计入阈值事件数量的事件类型。目前，我们并未明确表示比较约束条件，假设所有约束条件均为 GREATER_OR_EQUAL。
thresholdEventCount

string (int64 format)

必需。每个用户都应至少出现在 K 个事件中。

事件类型

可用于统计频次的事件类型。

枚举
EVENT_TYPE_UNSPECIFIED 默认值：不应使用。
IMPRESSIONS 统计所有展示次数。

再营销名单信息

再营销名单的元数据。

JSON 表示法 
{
  "userListQuery": string,
  "populatingUserListQueries": [
    string
  ]
}
字段
userListQuery

string

不可变。广告数据中心用户列表查询资源，用于指定将用户添加到此受众群体的方式。格式为：customer/[customerId]/userListQuery/[query_resource_id]
populatingUserListQueries[]

string

仅供输出。广告数据中心用户名单查询资源已填充此受众群体。这是一个旧版字段，用于支持在 1:1 用户名单:查询限制生效之前由多个查询填充的用户名单。格式为：customer/[customerId]/userListQuery/[query_resource_id]

状态

用户名单的状态。

枚举
STATE_UNSPECIFIED 默认值 / 未设置值。
STATE_ACTIVE 用户名单仍然有效并处于有效状态。
STATE_DELETED 用户名单已标记为已删除，不得再用于定位

方法

addEventMatchers

 将事件匹配器添加到基于频率的用户列表中。

addRecipients

 将实体添加到广告数据中心管理的用户名单收件人中。

create

 创建由广告数据中心管理的用户名单。

delete

 删除请求的广告数据中心管理的用户列表。

generateFrequencyListMemberships

 为 UserList 生成成员资格。

get

 检索请求的广告数据中心管理的用户列表。

list

 列出由指定广告数据中心客户管理的用户名单。

patch

 更新所请求的由广告数据中心管理的用户名单。

removeRecipients

 从广告数据中心管理的用户名单收件人中移除实体。