再营销列表记录 - 批量

项目
11/13/2024

定义可在批量文件中下载和上传的再营销列表。

注意

如果你是试点参与者，Microsoft广告将自动为再营销列表生成类似的受众。不能为再营销列表创建或编辑类似的受众。话虽如此，可以添加和删除类似的再营销列表关联和排除项。如果删除源再营销列表，也会删除类似的受众。如果类似的受众与市场活动或广告组相关联，则无法删除源再营销列表。有关更多详细信息，请参阅类似的再营销列表。

提示

有关访问群体的概述和详细信息，请参阅受众 API 技术指南。

通过在 DownloadCampaignsByAccountIds 或 DownloadCampaignsByCampaignIds 服务请求中包含 RemarketingLists 的 DownloadEntity 值，可以下载帐户中的所有再营销列表记录。此外，下载请求必须包括 EntityData 范围。有关批量服务的更多详细信息（包括最佳做法），请参阅批量下载和上传。

以下批量 CSV 示例将添加新的再营销列表。

Type,Status,Id,Parent Id,Client Id,Modified Time,Name,Description,Membership Duration,Scope,UET Tag Id,Audience,Remarketing Rule
Format Version,,,,,,6.0,,,,,,
Remarketing List,Active,-10,ParentIdHere,ClientIdGoesHere,,,New list with CustomEventsRule,30,Account,TagIdHere,Remarketing List with CustomEventsRule,CustomEvents(Action Equals play) and (Category Equals video) and (Label Equals trailer) and (Value Equals 5.00)

如果使用用于 .NET、Java 或 Python 的必应广告 SDK ，则可以使用 BulkServiceManager 来节省时间来上传和下载 BulkRemarketingList 对象，而无需直接调用服务操作和编写自定义代码来分析批量文件中的每个字段。

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkRemarketingList
var bulkRemarketingList = new BulkRemarketingList
{
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",

    // Map properties in the Bulk file to the 
    // RemarketingList object of the Campaign Management service.
    RemarketingList = new RemarketingList
    {
        // 'Audience Network Size' column header in the Bulk file
        AudienceNetworkSize = null,
        // 'Description' column header in the Bulk file
        Description = "New list with CustomEventsRule",
        // 'Id' column header in the Bulk file
        Id = remarketingListIdKey,
        // 'Membership Duration' column header in the Bulk file
        MembershipDuration = 30,
        // 'Audience' column header in the Bulk file
        Name = "Remarketing List with CustomEventsRule " + DateTime.UtcNow,
        // 'Parent Id' column header in the Bulk file
        ParentId = accountIdKey,
        // 'Remarketing Rule' column header in the Bulk file
        Rule = new CustomEventsRule
        {
            // The rule definition is translated to the following logical expression: 
            // CustomEvents(Category Equals video) and (Action Equals play) and (Label Equals trailer) 
            // and (Value Equals 5)
            Action = "play",
            ActionOperator = StringOperator.Equals,
            Category = "video",
            CategoryOperator = StringOperator.Equals,
            Label = "trailer",
            LabelOperator = StringOperator.Equals,
            Value = 5.00m,
            ValueOperator = NumberOperator.Equals,
        },
        // 'Scope' column header in the Bulk file
        Scope = EntityScope.Account,
        // 'Audience Search Size' column header in the Bulk file
        SearchSize = null,
        // 'Supported Campaign Types' column header in the Bulk file
        SupportedCampaignTypes = null,
        // 'UET Tag Id' column header in the Bulk file
        TagId = tagIdKey
    },
                
    // 'Status' column header in the Bulk file
    Status = Status.Active
};

uploadEntities.Add(bulkRemarketingList);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();

对于 再营销列表 记录，批量文件架构中提供了以下属性字段。

受众
受众网络大小
访问群体搜索大小
客户端 ID
说明
Id
成员资格持续时间
修改时间
父 ID
再营销规则
Scope
状态
支持的市场活动类型
UET 标记 ID

受众

再营销列表的名称。

该名称最多可包含 128 个字符。

加：必填
更新： 自选。如果未为更新设置任何值，则不会更改此设置。
删除： 只读

受众网络大小

在受众网络中是此受众的活跃成员的总数。这让你了解可以面向多少受众网络用户。

受众至少需要有 300 人，Microsoft广告将使用它进行优化。

加：只读
更新： 只读
删除： 只读

访问群体搜索大小

搜索网络中此受众的活动成员的总数。这样就可以了解可以面向多少搜索用户。

受众至少需要有 300 人，Microsoft广告将使用它进行优化。

在构建受众时，此属性最多为空 24 小时，例如，如果添加或更新再营销列表成员资格持续时间、规则或标记标识符。

如果与再营销列表关联的 UET 标记的状态为“未验证”或“非活动”，则此属性将为空，因为再营销列表无法从您的网站接收生成列表所需的客户信息。

加：只读
更新： 只读
删除： 只读

客户端 ID

用于将批量上传文件中的记录与结果文件中的记录相关联。服务器不使用或存储此字段的值;它只是从上传的记录复制到相应的结果记录。它可以是长度最大为 100 的任何有效字符串。

加：自选
更新： 自选
删除： 只读

说明

再营销列表的说明。使用说明来帮助你记住此再营销列表的目标受众。

说明最多可以包含 1,024 个字符。

加：自选
更新： 自选。如果未为更新设置任何值，则不会更改此设置。如果将此字段设置为 delete_value 字符串，则会删除以前的设置。
删除： 只读

Id

再营销列表的系统生成的标识符。

加：只读
更新： 只读和必需
删除： 只读和必需

成员资格持续时间

创建再营销列表时，可以指定广告Microsoft应查找与再营销列表定义匹配的操作，以便将人员添加到列表中。

最短持续时间为 1 天，允许的最大持续时间为 180 天。

加：自选
更新： 自选。如果未为更新设置任何值，则不会更改此设置。
删除： 只读

修改时间

上次更新实体的日期和时间。该值以协调世界时 (UTC) 表示。

注意

日期和时间值反映服务器的日期和时间，而不是客户端。有关日期和时间格式的信息，请参阅基元 XML 数据类型中的 dateTime 条目。

加：只读
更新： 只读
删除： 只读

父 ID

帐户或客户的系统生成的标识符。如果 “作用域 ”设置为 “帐户”，则这是帐户 ID，否则为客户 ID。

加：自选
更新： 只读。不能更改父 ID。
删除： 只读

再营销规则

规则模板包含用于确定要添加到再营销列表的人员的条件。

可以选择以下四种类型的规则之一来面向不同的访问群体： CustomEventsRule、 PageVisitorsRule、 PageVisitorsWhoDidNotVisitAnotherPageRule 和 PageVisitorsWhoVisitedAnotherPageRule。有关批量文件中每个规则的格式的详细信息，请参阅下面的 CustomEvents、PageVisitorsWhoDidNotVisitAnotherPage 和 PageVisitorsWhoVisitedAnotherPage 规则模板备注部分。

加：必填
更新： 自选。如果未为更新设置任何值，则不会更改此设置。如果要保留任何以前的规则项，则必须在更新期间再次显式设置它们。可以选择在更新期间更改规则的类型。
删除： 只读

CustomEvents 规则模板

对于 CustomEvents 规则，必须包含以下一个或多个条件事件运算符对： (ActionOperator 和 Action) 、 (CategoryOperator 和 Category) 、 (LabelOperator 和 Label) 、 (ValueOperator 和 Value) 。如果指定了多个条件，则使用逻辑 AND 运算符联接这些条件。换句话说，只有在满足所有指定的规则条件时，才会将访问者添加到再营销列表。

例如，假设以下自定义事件在大容量文件中设置为逻辑表达式：

CustomEvents (Category Equals video) and (Action Equals play) 和 (Label Equals 预告片) 和 (Value 等于 5)

计算逻辑表达式确定将添加到再营销列表的人员。

PageVisitors 规则模板

对于 PageVisitors 规则，必须包含一个或多个规则项组。

重要

在 2021 日历年，我们添加了对 CNF) (连接正常形式的支持。以前Microsoft广告仅支持 (DNF) 的消除正常形式。新页面访问者规则的默认普通形式仍为 DNF。但是，必须确保应用程序可以适当地读取和区分 CNF 和 DNF。应用程序不应再假定该规则具有分离性。

如果普通窗体是 conjunctive (CNF) ，则首先使用逻辑 OR 运算符联接同一页的规则项条件。然后，使用逻辑 AND 运算符联接规则项组列表中的每个结果。换句话说，如果满足所有规则项组中的任何指定规则项条件，则将用户添加到再营销列表。

规则 1 和规则 2
(规则 1 或规则 2) 和规则 3
(规则 1 或规则 2) and (规则 3 或规则 4)

如果普通窗体 (DNF) 分离，则首先使用逻辑 AND 运算符联接同一页的规则项条件。然后，使用逻辑 OR 运算符联接规则项组列表中的每个结果。换句话说，如果满足任何一个规则项组中的所有指定规则项条件，则将用户添加到再营销列表。

规则 1 或规则 2
(规则 1 和规则 2) 或规则 3
(规则 1 和规则 2) 或 (规则 3 和规则 4)

对于 DNF 计算的示例，假设以下规则项组在批量文件中设置为逻辑表达式：

PageVisitors ( (Url 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) )

对逻辑表达式的求值确定将向再营销列表添加以下示例用户中的哪一个。

用户	已访问的 URL	引用网站 URL	已添加到列表
用户 1	A	X	是。逻辑表达式的计算结果为 True。 ( (Url 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) (False 和 True) 或 (True) 或 (False) False 或 True 或 False True
用户 2	B	Y	不正确。逻辑表达式的计算结果为 False。 ( (Url 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) (False 和 True) 或 (False) 或 (False) False 或 False 或 False False
用户 3	C	Z	是。逻辑表达式的计算结果为 True。 ( (Url 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) (False 和 False) 或 (True) 或 (True) False 或 True 或 True True

PageVisitorsWhoDidNotVisitAnotherPage 规则模板

再营销规则是用于确定要添加到再营销列表的人员的条件。对于 PageVisitorsWhoDidNotVisitAnotherPage 规则，必须包含一个或多个已访问页面的规则项组 (IncludeRuleItemGroups) ，并且还必须包括一个或多个未访问的页面的规则项组 (ExcludeRuleItemGroups) 。

对于 IncludeRuleItemGroups 中的每个规则项组，将使用逻辑 AND 运算符联接同一页的规则项条件。然后，使用逻辑 OR 运算符联接规则项组列表中的每个结果。

同样，对于 ExcludeRuleItemGroups 中的每个规则项组，将使用逻辑 AND 运算符联接同一页的规则项条件。然后，使用逻辑 OR 运算符联接规则项组列表中的每个结果。最后，逻辑 NOT 运算符将应用于排除规则项组的聚合结果。

换句话说，如果满足任何包含规则项组条件，并且不满足排除规则项组条件，访问者将被添加到再营销列表。

例如，假设以下规则项组在大容量文件中设置为逻辑表达式：

( ( (URL 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (引用erUrl 等于 Z) ) ) ，而不是 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) )

对逻辑表达式的求值确定将向再营销列表添加以下示例用户中的哪一个。

用户	已访问的 URL	引用网站 URL	已添加到列表
用户 1	A	X	是。逻辑表达式的计算结果为 True。 ( ( (URL 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (引用erUrl 等于 Z) ) ) ，而不是 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 True) 或 (True) 或 (False) ) ，而不是 ( (True 和 False) 或 (False) ) (False 或 True 或 False) ，而不是 (False 或 False) True 和 not False True
用户 2	B	Y	是。逻辑表达式的计算结果为 True。 ( ( (URL 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (引用erUrl 等于 Z) ) ) ，而不是 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 True) 或 (True) 或 (False) ) ，而不是 ( (False 和 False) 或 (False) ) (False 或 True 或 False) ，而不是 (False 或 False) True 和 not False True
用户 3	C	Z	不正确。逻辑表达式的计算结果为 False。 ( ( (URL 包含 X) 和 (ReferrerUrl DoesNotContain Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (引用erUrl 等于 Z) ) ) ，而不是 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 False) 或 (True) 或 (True) ) ，而不是 ( (False) 或 (True) ) (False 或 True 或 True) ，而不 (False 或 True) True 和 not True False

PageVisitorsWhoVisitedAnotherPage 规则模板

再营销规则是用于确定要添加到再营销列表的人员的条件。对于 PageVisitorsWhoVisitedAnotherPage 规则，必须包含一个或多个规则项组，用于访问的页 (RuleItemGroups) ，并且还必须包含一个或多个规则项组，用于必须已访问的另一个页面 (AnotherRuleItemGroups) 。

对于 RuleItemGroups 中的每个规则项组，将使用逻辑 AND 运算符联接同一页的规则项条件。然后，使用逻辑 OR 运算符联接规则项组列表中的每个结果。

同样，对于 AnotherRuleItemGroups 中的每个规则项组，将使用逻辑 AND 运算符联接同一页的规则项条件。然后，使用逻辑 OR 运算符联接规则项组列表中的每个结果。

换句话说，如果满足任何规则项组条件，并且满足其他任何规则项组条件，访问者将被添加到再营销列表。

例如，假设以下规则项组在大容量文件中设置为逻辑表达式：

( ( (Url 包含 X) 和 (ReferrerUrl NotEquals Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) ) 和 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) )

对逻辑表达式的求值确定将向再营销列表添加以下示例用户中的哪一个。

用户	已访问的 URL	引用网站 URL	已添加到列表
用户 1	A	X	不正确。逻辑表达式的计算结果为 False。 ( ( (Url 包含 X) 和 (ReferrerUrl NotEquals Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) ) 和 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 True) 或 (True) 或 (False) ) 和 ( (true 和 False) 或 (False) ) ) (False 或 True 或 False， (False 或 False) True 和 False False
用户 2	B	Y	不正确。逻辑表达式的计算结果为 False。 ( ( (Url 包含 X) 和 (ReferrerUrl NotEquals Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) ) 和 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 True) 或 (True) 或 (False) ) 和 ( (False) 或 (False) ) ) (False 或 True 或 False， (False 或 False) True 和 False False
用户 3	C	Z	是。逻辑表达式的计算结果为 True。 ( ( (Url 包含 X) 和 (ReferrerUrl NotEquals Z) ) 或 ( (Url DoesNotBeginWith Y) ) 或 ( (ReferrerUrl 等于 Z) ) ) 和 ( ( (Url BeginsWith A) 和 (ReferrerUrl BeginsWith B) ) 或 ( (Url 包含 C) ) ) ( (False 和 True) 或 (True) 或 (True) ) ， ( (False 和 False) 或 (True) ) (False 或 True 或 True) ， (False 或 True) True 和 True True

范围

范围定义哪些帐户可以使用此再营销列表。如果范围设置为 “帐户”，则再营销列表只能与一个指定帐户中的市场活动和广告组相关联， (父 ID) 。如果范围设置为 “客户”，则再营销列表可以与所有客户帐户中的任何市场活动和广告组相关联。

加：必填
更新： 只读。不能更改范围。
删除： 只读

状态

再营销列表状态。

可能的值为 Active 或 Deleted。

加：自选。默认值为 Active。
更新： 只读
删除： 必填。 “状态”必须设置为 “已删除”。

支持的市场活动类型

支持此再营销列表的市场活动类型的分号分隔列表。

支持的值为 Audience、DynamicSearchAds、Search 和 Shopping。将来可能会添加新的市场活动类型，因此不应依赖于一组固定值。

加：只读
更新： 只读
删除： 只读

UET 标记 ID

与再营销列表一起使用的通用事件跟踪 (UET) 标记的Microsoft广告标识符。

加：必填
更新： 自选。如果未为更新设置任何值，则不会更改此设置。
删除： 只读

通过

再营销列表记录 - 批量

受众

受众网络大小

访问群体搜索大小

客户端 ID

说明

Id

成员资格持续时间

修改时间

父 ID

再营销规则

CustomEvents 规则模板

PageVisitors 规则模板

PageVisitorsWhoDidNotVisitAnotherPage 规则模板

PageVisitorsWhoVisitedAnotherPage 规则模板

范围

状态

支持的市场活动类型

UET 标记 ID

反馈

其他资源