UserList

使用者清單。這是客戶可能鎖定的使用者清單。

JSON 表示法 
{
  "resourceName": string,
  "membershipStatus": enum (UserListMembershipStatus),
  "sizeRangeForDisplay": enum (UserListSizeRange),
  "sizeRangeForSearch": enum (UserListSizeRange),
  "type": enum (UserListType),
  "closingReason": enum (UserListClosingReason),
  "accessReason": enum (AccessReason),
  "accountUserListStatus": enum (UserListAccessStatus),
  "id": string,
  "readOnly": boolean,
  "name": string,
  "description": string,
  "integrationCode": string,
  "membershipLifeSpan": string,
  "sizeForDisplay": string,
  "sizeForSearch": string,
  "eligibleForSearch": boolean,
  "eligibleForDisplay": boolean,
  "matchRatePercentage": integer,

  // Union field user_list can be only one of the following:
  "crmBasedUserList": {
    object (CrmBasedUserListInfo)
  },
  "similarUserList": {
    object (SimilarUserListInfo)
  },
  "ruleBasedUserList": {
    object (RuleBasedUserListInfo)
  },
  "logicalUserList": {
    object (LogicalUserListInfo)
  },
  "basicUserList": {
    object (BasicUserListInfo)
  },
  "lookalikeUserList": {
    object (LookalikeUserListInfo)
  }
  // End of list of possible types for union field user_list.
}
欄位
resourceName

string

不可變動。使用者清單的資源名稱。使用者名單資源名稱的格式如下：

customers/{customerId}/userLists/{userListId}
membershipStatus

enum (UserListMembershipStatus)

這個使用者名單的成員資格狀態。指出使用者名單是否開放或有效。只有公開使用者名單可以累積更多使用者，並且可指定目標對象。
sizeRangeForDisplay

enum (UserListSizeRange)

僅供輸出。在 Google 多媒體廣告聯播網中，UserList 的使用者人數範圍。

這是唯讀欄位。
type

enum (UserListType)

僅供輸出。清單的類型。

這是唯讀欄位。
closingReason

enum (UserListClosingReason)

指出使用者名單成員資格狀態為「已關閉」的原因。這項屬性只會填入因閒置而自動關閉的名單，且在名單會員資格狀態變為開放時會清除。
accessReason

enum (AccessReason)

僅供輸出。指出授予此帳戶名單存取權的原因。原因可以是「SHARED」、「OWNED」、「LICENSED」或「SUBSCRIBED」。

這是唯讀欄位。
accountUserListStatus

enum (UserListAccessStatus)

指出是否仍啟用這項分享。當 UserList 與使用者共用時，這個欄位會設為 ENABLED。之後，使用者清單擁有者可以決定撤銷共用權限，並將其設為「停用」。這個欄位的預設值設為 ENABLED。
id

string (int64 format)

僅供輸出。使用者名單 ID。
readOnly

boolean

僅供輸出。這個選項可指出使用者是否可以編輯清單。取決於清單擁有權和清單類型。舉例來說，您無法編輯外部再行銷使用者名單。

這是唯讀欄位。
name

string

這個使用者清單的名稱。視 accessReason 而定，使用者清單名稱可能不是唯一的 (例如，如果 accessReason=SHARED)
description

string

這個使用者清單的說明。
integrationCode

string

外部系統的 ID。使用者名單賣家會使用這個 ID 在系統中建立 ID 關聯。
membershipLifeSpan

string (int64 format)

自使用者 Cookie 最近加入名單起算，保留在名單中的天數。這個欄位必須介於 0 到 540 之間 (含首尾)。不過，如果是基於客戶關係管理系統的使用者名單，則可以將這個欄位設為 10000，表示沒有到期日。自 2025 年 4 月 7 日起，系統將不再支援使用值 10000 表示沒有到期日。

如果是 logicalUserList 和 ruleBasedUserList 類型，系統會忽略這個欄位。這類清單的會員資格取決於清單定義的規則。
sizeForDisplay

string (int64 format)

僅供輸出。這個使用者名單在 Google 多媒體聯播網的預估使用者人數。如果使用者人數尚未確定，這個值會為空值。

這是唯讀欄位。
eligibleForDisplay

boolean

僅供輸出。表示這個使用者名單符合 Google 多媒體廣告聯播網的資格。

這是唯讀欄位。
matchRatePercentage

integer

僅供輸出。表示目標顧客比對名單的媒合率。這個欄位的範圍為 [0-100]。對於其他清單類型或無法計算比對率的情況，這個值會為空值。

這是唯讀欄位。

聯集欄位 user_list。使用者清單。

必須明確設定一個。user_list 只能是下列其中一項：
crmBasedUserList

object (CrmBasedUserListInfo)

廣告主提供的客戶關係管理使用者名單。
similarUserList

object (SimilarUserListInfo)

僅供輸出。與其他 UserList 使用者相似的使用者名單。這些清單為唯讀，由 Google 自動建立。
ruleBasedUserList

object (RuleBasedUserListInfo)

規則產生的使用者清單。
logicalUserList

object (LogicalUserListInfo)

使用者清單，是使用者清單和使用者興趣的自訂組合。
basicUserList

object (BasicUserListInfo)

使用者名單指定目標，做為轉換或再行銷動作的集合。
lookalikeUserList

object (LookalikeUserListInfo)

不可變動。類似使用者名單。

UserListMembershipStatus

包含可能的使用者名單成員資格狀態的列舉。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
OPEN 開放狀態：名單會累積成員，且可指定目標對象。
CLOSED 關閉狀態：無法新增成員。無法用於指定目標。

UserListSizeRange

包含可能的使用者名單大小範圍的列舉。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
LESS_THAN_FIVE_HUNDRED 使用者名單中的使用者人數少於 500 位。
LESS_THAN_ONE_THOUSAND 使用者清單中的使用者人數介於 500 到 1000 之間。
ONE_THOUSAND_TO_TEN_THOUSAND 使用者清單中的使用者人數介於 1000 到 10000 之間。
TEN_THOUSAND_TO_FIFTY_THOUSAND 使用者清單中的使用者人數介於 10000 到 50000 之間。
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND 使用者名單中的使用者人數介於 50000 到 100000 之間。
ONE_HUNDRED_THOUSAND_TO_THREE_HUNDRED_THOUSAND 使用者清單中的使用者人數介於 100000 到 300000 之間。
THREE_HUNDRED_THOUSAND_TO_FIVE_HUNDRED_THOUSAND 使用者清單的使用者人數介於 300000 到 500000 之間。
FIVE_HUNDRED_THOUSAND_TO_ONE_MILLION 使用者清單中的使用者人數介於 500000 到 1000000 之間。
ONE_MILLION_TO_TWO_MILLION 使用者清單中的使用者數量介於 100 萬到 200 萬之間。
TWO_MILLION_TO_THREE_MILLION 使用者清單中的使用者數量介於 200 萬至 300 萬之間。
THREE_MILLION_TO_FIVE_MILLION 使用者清單中的使用者數量介於 300 萬至 500 萬之間。
FIVE_MILLION_TO_TEN_MILLION 使用者清單的使用者人數介於 500 萬到 1,000 萬之間。
TEN_MILLION_TO_TWENTY_MILLION 使用者清單的使用者人數介於 1,000 萬至 2,000 萬之間。
TWENTY_MILLION_TO_THIRTY_MILLION 使用者清單的使用者人數介於 2,000 萬至 3,000 萬之間。
THIRTY_MILLION_TO_FIFTY_MILLION 使用者清單內的使用者人數介於 3,000 萬至 5,000 萬之間。
OVER_FIFTY_MILLION 使用者清單中有超過 5,000 萬名使用者。

UserListClosingReason

列舉說明使用者名單關閉原因的選項。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
UNUSED 使用者名單已關閉，因為該名單已超過一年未使用。

AccessReason

列舉說明可能的存取原因。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
OWNED 資源由使用者擁有。
SHARED 資源會共用給使用者。
LICENSED 使用者已獲得資源授權。
SUBSCRIBED 使用者訂閱了資源。
AFFILIATED 使用者可以存取資源。

UserListAccessStatus

列舉包含可能的使用者名單存取狀態。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
ENABLED 已啟用存取權。
DISABLED 存取權已停用。

CrmBasedUserListInfo

廣告主提供的客戶關係管理使用者 UserList。

JSON 表示法 
{
  "uploadKeyType": enum (CustomerMatchUploadKeyType),
  "dataSourceType": enum (UserListCrmDataSourceType),
  "appId": string
}
欄位
uploadKeyType

enum (CustomerMatchUploadKeyType)

清單的配對鍵類型。同一清單中不得混用資料類型。這是新增操作的必填欄位。
dataSourceType

enum (UserListCrmDataSourceType)

清單的資料來源。預設值為 FIRST_PARTY。只有許可清單上的客戶可以建立第三方來源的 CRM 名單。
appId

string

用來唯一識別資料收集來源的行動應用程式字串。以 iOS 來說，ID 字串為 App Store 網址結尾顯示的 9 個數字，例如「Flood-It!2"，其 App Store 連結為 http://itunes.apple.com/us/app/flood-it!-2/id476943146)。以 Android 來說，ID 字串則為應用程式的套件名稱 (例如，如果 Google Play 連結為 https://play.google.com/store/apps/details?id=com.labpixies.colordrips)，則「Color Drips」的 ID 字串為「com.labpixies.colordrips」)。如要上傳行動廣告 ID，請建立 CrmBasedUserList。

CustomerMatchUploadKeyType

列舉項目，說明可能的目標顧客比對上傳金鑰類型。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
CONTACT_INFO 系統會根據客戶資訊 (例如電子郵件地址、電話號碼或實際地址) 比對會員。
CRM_ID 系統會根據廣告主產生及指派的使用者 ID 比對會員。
MOBILE_ADVERTISING_ID 系統會根據行動廣告 ID 比對會員。

UserListCrmDataSourceType

列舉，說明可能的使用者清單 CRM 資料來源類型。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
FIRST_PARTY 上傳的資料屬於第一方資料。
THIRD_PARTY_CREDIT_BUREAU 上傳的資料來自第三方徵信機構。
THIRD_PARTY_VOTER_FILE 上傳的資料來自第三方選民檔案。

SimilarUserListInfo

SimilarUserList 是與其他 UserList 使用者相似的使用者清單。這些名單為唯讀，由 Google 自動建立。

JSON 表示法 
{
  "seedUserList": string
}
欄位
seedUserList

string

這個清單的種子 UserList。

RuleBasedUserListInfo

由規則產生的使用者清單表示法。

JSON 表示法 
{
  "prepopulationStatus": enum (UserListPrepopulationStatus),
  "flexibleRuleUserList": {
    object (FlexibleRuleUserListInfo)
  }
}
欄位
prepopulationStatus

enum (UserListPrepopulationStatus)

預先填入的狀態。如果未設定，這個欄位預設為 NONE，表示系統不會考慮先前的使用者。如果設為「已要求」，系統就會將符合名單定義的過去網站訪客或應用程式使用者納入名單 (僅適用於多媒體聯播網)。這項操作只會加入過去 30 天內的使用者，具體取決於名單的會員資格時間長度，以及加入再行銷代碼的日期。要求處理完畢後，狀態會更新為「FINISHED」，如果要求失敗，則會更新為「FAILED」。
flexibleRuleUserList

object (FlexibleRuleUserListInfo)

以一或多項動作表示訪客的彈性規則。彈性使用者名單由兩個運算元的清單定義：inclusiveOperands 和 exclusiveOperands；每個運算元代表一組使用者，根據他們在特定時間範圍內採取的動作。這些運算元的清單會與 AND_NOT 運算子結合，因此由包含性運算子代表的使用者會納入使用者清單，並扣除由排除性運算子代表的使用者。

UserListPrepopulationStatus

列舉說明使用者名單預先填入狀態。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
REQUESTED 正在要求預先填充。
FINISHED 預先填入資料已完成。
FAILED 預先填入資料失敗。

FlexibleRuleUserListInfo

以一或多項動作表示訪客的彈性規則。彈性使用者名單由兩個運算元的清單定義：inclusiveOperands 和 exclusiveOperands；每個運算元代表一組使用者，根據他們在特定時間範圍內採取的動作。這些運算元的清單會與 AND_NOT 運算子結合，因此由包含性運算子代表的使用者會納入使用者清單，並扣除由排除性運算子代表的使用者。

JSON 表示法 
{
  "inclusiveRuleOperator": enum (UserListFlexibleRuleOperator),
  "inclusiveOperands": [
    {
      object (FlexibleRuleOperandInfo)
    }
  ],
  "exclusiveOperands": [
    {
      object (FlexibleRuleOperandInfo)
    }
  ]
}
欄位
inclusiveRuleOperator

enum (UserListFlexibleRuleOperator)

定義包含運算元的合併方式。
inclusiveOperands[]

object (FlexibleRuleOperandInfo)

代表應納入使用者名單的使用者規則。這些運算式位於 AND_NOT 運算子的左側，並由 inclusiveRuleOperator 指定的 AND/OR 運算子連接在一起。
exclusiveOperands[]

object (FlexibleRuleOperandInfo)

代表應從使用者名單中排除的使用者規則。這些條件位於 AND_NOT 運算子的右側，並以 OR 運算子連接在一起。

UserListFlexibleRuleOperator

列舉說明可能的使用者清單組合規則運算子。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
AND A 和 B。
OR A 或 B。

FlexibleRuleOperandInfo

包裝常用規則和回溯期，可靈活調整的規則。

JSON 表示法 
{
  "rule": {
    object (UserListRuleInfo)
  },
  "lookbackWindowDays": string
}
欄位
rule

object (UserListRuleInfo)

定義此規則的規則項目群組清單。規則項目群組會分組。
lookbackWindowDays

string (int64 format)

此規則的回溯期 (以天為單位)。從現在到 X 天前。

UserListRuleInfo

客戶定義的規則，根據網站傳送或廣告主上傳的自訂參數。

JSON 表示法 
{
  "ruleType": enum (UserListRuleType),
  "ruleItemGroups": [
    {
      object (UserListRuleItemGroupInfo)
    }
  ]
}
欄位
ruleType

enum (UserListRuleType)

規則類型用於決定分組規則項目的方式。

預設為 AND 的 OR 邏輯運算 (析取正規形式)。也就是說，規則項目會在規則項目群組內以 AND 運算結合，而群組本身則會以 OR 運算結合。

只有 AND 的 OR 為 FlexibleRuleUserList 支援的唯一類型。
ruleItemGroups[]

object (UserListRuleItemGroupInfo)

定義此規則的規則項目群組清單。規則項目群組會根據 ruleType 分組。

UserListRuleType

列舉說明可能的使用者名單規則類型。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
AND_OF_ORS 聯合標準型。
OR_OF_ANDS 析取正規形式。

UserListRuleItemGroupInfo

一組規則項目。

JSON 表示法 
{
  "ruleItems": [
    {
      object (UserListRuleItemInfo)
    }
  ]
}
欄位
ruleItems[]

object (UserListRuleItemInfo)

根據 ruleType 分組的規則項目。

UserListRuleItemInfo

原子規則項目。

JSON 表示法 
{
  "name": string,

  // Union field rule_item can be only one of the following:
  "numberRuleItem": {
    object (UserListNumberRuleItemInfo)
  },
  "stringRuleItem": {
    object (UserListStringRuleItemInfo)
  },
  "dateRuleItem": {
    object (UserListDateRuleItemInfo)
  }
  // End of list of possible types for union field rule_item.
}
欄位
name

string

規則變數名稱。此值應與像素觸發的相應鍵名稱相符。名稱開頭必須是 US-ascii 字母、底線或 UTF8 代碼 (大於 127)，且包含 US-ascii 字母、數字、底線或 UTF8 代碼 (大於 127)。針對網站，有兩個內建變數網址 (name = 'url__') 和參照網址 (name = 'ref_url__')。建立新的規則項目時，必須填入這個欄位。
聯集欄位 rule_item。原子規則項目。rule_item 只能是下列其中一項：
numberRuleItem

object (UserListNumberRuleItemInfo)

由數字運算所組成的原子規則項目。
stringRuleItem

object (UserListStringRuleItemInfo)

由字串運算所組成的原子規則項目。
dateRuleItem

object (UserListDateRuleItemInfo)

由日期運算式組成的原子規則項目。

UserListNumberRuleItemInfo

由數字運算所組成的規則項目。

JSON 表示法 
{
  "operator": enum (UserListNumberRuleItemOperator),
  "value": number
}
欄位
operator

enum (UserListNumberRuleItemOperator)

數字比較運算子。這個欄位為必填欄位，建立新的數字規則項目時必須填入。
value

number

要與變數比較的數值。這個欄位為必填欄位，建立新的數字規則項目時必須填入。

UserListNumberRuleItemOperator

列舉說明使用者清單數字規則項目運算子的可能值。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
GREATER_THAN 大於。
GREATER_THAN_OR_EQUAL 大於或等於。
EQUALS 相等。
NOT_EQUALS 不等於。
LESS_THAN 小於。
LESS_THAN_OR_EQUAL 小於或等於。

UserListStringRuleItemInfo

由字串運算所組成的規則項目。

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

enum (UserListStringRuleItemOperator)

字串比較運算子。這是必填欄位，建立新的字串規則項目時必須填入。
value

string

字串規則項目的右側。對於網址或參照網址，值不得包含無效的網址字元，例如換行符號、引號、定位字元或括號。這是必填欄位，建立新的字串規則項目時必須填入。

UserListStringRuleItemOperator

列舉項目，說明可能的使用者清單字串規則項目運算子。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
CONTAINS 包含。
EQUALS 等於。
STARTS_WITH 開頭為。
ENDS_WITH 結尾為。
NOT_EQUALS 不等於。
NOT_CONTAINS 不包含。
NOT_STARTS_WITH 開頭不是。
NOT_ENDS_WITH 結尾不是。

UserListDateRuleItemInfo

由日期運算式組成的規則項目。

JSON 表示法 
{
  "operator": enum (UserListDateRuleItemOperator),
  "value": string,
  "offsetInDays": string
}
欄位
operator

enum (UserListDateRuleItemOperator)

日期比較運算子。這是必填欄位，建立新的日期規則項目時必須填入。
value

string

字串，代表要與規則變數比較的日期值。支援的日期格式為 YYYY-MM-DD。時間會以客戶的時區為準。
offsetInDays

string (int64 format)

右側的相對日期值，以與目前時間相差的天數表示。如果兩者皆存在，值欄位會覆寫這個欄位。

UserListDateRuleItemOperator

列舉說明使用者清單日期規則項目運算子的可能值。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
EQUALS 相等。
NOT_EQUALS 不等於。
BEFORE 之前。
AFTER 後。

LogicalUserListInfo

代表使用者清單，是使用者清單的自訂組合。

JSON 表示法 
{
  "rules": [
    {
      object (UserListLogicalRuleInfo)
    }
  ]
}
欄位
rules[]

object (UserListLogicalRuleInfo)

定義此使用者名單的邏輯清單規則。規則的定義為邏輯運算子 (ALL/ANY/NONE) 和使用者清單。評估時，所有規則都會以 AND 連結。

建立邏輯使用者名單時必須使用。

UserListLogicalRuleInfo

使用者名單邏輯規則。規則包含邏輯運算子 (and/or/not) 和使用者名單清單做為運算元。

JSON 表示法 
{
  "operator": enum (UserListLogicalRuleOperator),
  "ruleOperands": [
    {
      object (LogicalUserListOperandInfo)
    }
  ]
}
欄位
operator

enum (UserListLogicalRuleOperator)

規則的邏輯運算子。
ruleOperands[]

object (LogicalUserListOperandInfo)

規則的運算元清單。

UserListLogicalRuleOperator

列舉說明可能的使用者清單邏輯規則運算子。

列舉
UNSPECIFIED 不指定。
UNKNOWN 僅用於傳回值。代表這個版本中未知的值。
ALL And - 所有運算元。
ANY Or - 至少一個運算元式。
NONE Not - 沒有任何運算元。

LogicalUserListOperandInfo

邏輯使用者名單的運算元，該名單包含使用者名單。

JSON 表示法 
{
  "userList": string
}
欄位
userList

string

使用者名單的資源名稱，做為運算元。

BasicUserListInfo

使用者名單指定目標，做為轉換或再行銷動作的集合。

JSON 表示法 
{
  "actions": [
    {
      object (UserListActionInfo)
    }
  ]
}
欄位
actions[]

object (UserListActionInfo)

與此使用者名單相關聯的動作。

UserListActionInfo

代表用於建構再行銷使用者名單的動作類型。

JSON 表示法 
{

  // Union field user_list_action can be only one of the following:
  "conversionAction": string,
  "remarketingAction": string
  // End of list of possible types for union field user_list_action.
}
欄位
聯集欄位 user_list_action。使用者名單動作的子類型。user_list_action 只能是下列其中一項：
conversionAction

string

非由再行銷產生的轉換動作。
remarketingAction

string

再行銷動作。

LookalikeUserListInfo

LookalikeUserlist，由可設定的種子 (一組 UserList) 中的相似使用者組成

JSON 表示法 
{
  "seedUserListIds": [
    string
  ],
  "expansionLevel": enum (LookalikeExpansionLevel),
  "countryCodes": [
    string
  ]
}
欄位
seedUserListIds[]

string (int64 format)

使用者提供的使用者種子名單 ID，系統會根據這個 ID 產生這個清單。
expansionLevel

enum (LookalikeExpansionLevel)

擴展層級，反映類似目標對象的規模
countryCodes[]

string

類似目標對象指定的國家/地區。根據 ISO-3166 定義的雙字母國家/地區代碼

LookalikeExpansionLevel

擴展層級，反映類似目標對象的規模

列舉
UNSPECIFIED 不指定。
UNKNOWN 擴展層級無效。
NARROW 擴展至與種子名單類似的一小群使用者
BALANCED 擴展至與種子名單類似的中等使用者組合。包含 EXPANSION_LEVEL_NARROW 的所有使用者，以及更多資訊。
BROAD 擴展至與種子名單相似的大量使用者。包含所有 EXPANSION_LEVEL_BALANCED 使用者等。