动态搜索广告记录 - 批量

项目
11/13/2024

定义可在批量文件中下载和上传的动态搜索广告。

使用动态搜索广告时，会根据要面向的网站域和语言自动生成标题和显示 URL。 Path1、Path2 和 Text 元素的组合使动态搜索广告是唯一的。（可选）可以使用页面源提供静态标题。

注意

此功能目前在以下国家/地区可用：阿尔巴尼亚 (AL) 、 (AD) 、阿根廷 (AR) 、阿鲁巴、澳大利亚 (非盟) 、奥地利 (AT) 、巴哈马 (BS) 、孟加拉国 (BD) 、比利时 (BE) 、玻利维亚 (BO) 、波斯尼亚和黑塞哥维那 (BA) 、巴西 (BR) ，文莱 (BN) 、保加利亚 (BG) 、加拿大 (CA) 、开曼群岛 (KY) ，智利 (CL) 、哥伦比亚 (CO) 、哥斯达黎加 (CR) 、克罗地亚 (HR) 、塞浦路斯 (CY) 、捷克共和国 (CZ) 、丹麦 (DK) 、多米尼加 (DM) 、多米尼加共和国 (DO) ，厄瓜多尔 (欧共体) 、萨尔瓦多 (SV) 、爱沙尼亚 (EE) 、斐济 (FJ) 、芬兰 (FI) 、法国 (FR) 、法属圭亚那 (GF) 、法属波利尼西亚 (PF) 、德国 (DE) 、希腊 (GR) 、关岛 (GU) 、危地马拉 (GT) 、圭亚那 (GY) 、海地 (HT) ，洪都拉斯 (HN) 、匈牙利 (HU) 、冰岛 (is) 、印度 (in) 、印度尼西亚 (ID) 、爱尔兰 (IE) 、意大利 (IT) 、拉脱维亚 (LV) 、列支敦斯登 (LI) 、立陶宛 (LT) 、卢森堡 (LU) 、马来西亚 (MY) 、马尔代夫 (MV) 、马耳他 (MT) ，马提尼克 (MQ) 、墨西哥 (MX) 、摩纳哥 (MC) 、蒙古 (MN) 、黑山 (ME) 、蒙特塞拉特 () ，尼泊尔 (NP) ，荷兰 (NL) ，新喀里多尼亚 (NC) ，新西兰 (新西兰) ，北马其顿共和国 (MK) ，挪威 (NO) ，巴拿马 (PA) ，巴拉圭 (PY) 、巴布亚新几内亚 (PG) 、秘鲁 (PE) 、菲律宾 (PH) ，波兰 (PO) 、葡萄牙 (PT) 、波多黎各、罗马尼亚 (RO) 、圣马力诺 (SM) 、塞尔维亚 (RS) 、新加坡 (SG) 、斯洛伐克 (SK) 、斯洛文尼亚 (SI) 、南非 (ZA) ，西班牙 (ES) 、西班牙 (ES) 、斯里兰卡 (LK) 、瑞典 (SE) 、瑞士 (CH) 、泰国 (TH) 、特立尼达和多巴哥 (TT) 、Türkiye (TR) 、梵蒂冈城 (VA) 、越南 (VN) 、英国 (英国) 、美国 (US) 、乌拉圭 (UY) ，和委内瑞拉 (VE) 。

动态搜索广告记录只能在具有有效动态搜索广告设置的搜索市场活动中创建， (由“域语言”、“已启用动态说明”、“页面源 ID”、“源”和“网站”字段组成) 。必须设置市场活动的试验 ID ，并且广告组类型必须设置为“SearchDynamic”。

注意

不能再添加、更新或检索仅支持动态搜索广告的市场活动。现有市场活动的市场活动类型已从“DynamicSearchAds”更新为“搜索”。广告组现在被视为“动态”广告组，但没有任何结构性更改，即它们包含与以前相同的自动目标和动态搜索广告。

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

如果提供了有效的父 ID 值，下面的批量 CSV 示例将添加新的动态搜索广告。

Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Title,Text,Display Url,Destination Url,Promotion,Device Preference,Name,App Platform,App Id,Final Url,Mobile Final Url,Tracking Template,Final Url Suffix,Custom Parameter,Title Part 1,Title Part 2,Path 1,Path 2
Format Version,,,,,,,,,,,,,,6.0,,,,,,,,,,,
Dynamic Search Ad,Active,,-1113,ParentCampaignNameGoesHere,AdGroupNameGoesHere,ClientIdGoesHere,,,Find New Customers & Increase Sales! Start Advertising on Contoso Today.,,,,,,,,,,,,{_promoCode}=PROMO1; {_season}=summer,,,seattle,shoe sale

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkDynamicSearchAd
var bulkDynamicSearchAd = new BulkDynamicSearchAd
{
    // 'Parent Id' column header in the Bulk file
    AdGroupId = adGroupIdKey,
    // 'Ad Group' column header in the Bulk file
    AdGroupName = "AdGroupNameGoesHere",
    // 'Campaign' column header in the Bulk file
    CampaignName = "ParentCampaignNameGoesHere",
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",

    // Map properties in the Bulk file to the 
    // DynamicSearchAd object of the Campaign Management service.
    DynamicSearchAd = new DynamicSearchAd
    {
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Path 1' column header in the Bulk file
        Path1 = "seattle",
        // 'Path 2' column header in the Bulk file
        Path2 = "shoe sale",
        // 'Status' column header in the Bulk file
        Status = AdStatus.Active,
        // 'Text' column header in the Bulk file
        Text = "Find New Customers & Increase Sales! Start Advertising on Contoso Today.",
        // 'Tracking Template' column header in the Bulk file
        TrackingUrlTemplate = null,
        // 'Custom Parameter' column header in the Bulk file
        UrlCustomParameters = new CustomParameters
        {
            // Each custom parameter is delimited by a semicolon (;) in the Bulk file
            Parameters = new[] {
                new CustomParameter(){
                    Key = "promoCode",
                    Value = "PROMO1"
                },
                new CustomParameter(){
                    Key = "season",
                    Value = "summer"
                },
            }
        },
    },
};

uploadEntities.Add(bulkDynamicSearchAd);

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

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

对于 动态搜索广告 记录，批量文件架构中提供了以下属性字段。路径 1、路径 2 和文本字段的组合使动态搜索广告是唯一的。

广告组
市场活动
客户端 ID
自定义参数
编辑上诉状态
编辑位置
编辑原因代码
编辑状态
编辑术语
最终 URL 后缀
Id
修改时间
父 ID
路径 1
路径 2
发布者国家/地区
状态
Text
跟踪模板

广告组

包含广告的广告组的名称。

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

注意

若要添加、更新和删除，必须指定 “父 ID ”或 “广告组” 字段。

Campaign

包含广告组和广告的市场活动的名称。

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

客户端 ID

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

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

自定义参数

用于 URL 跟踪的键和值参数的自定义集合。

在批量文件中，自定义参数列表的格式如下所示。

将每个自定义参数对的格式设置为 Key=Value，例如 {_promoCode}=PROMO1。
Microsoft Advertising 将接受你包含的前 8 个自定义参数键和值对，如果包含 8 个以上的自定义参数，将返回错误。每个键值对由分号和空格 (“分隔;“) ，例如 {_promoCode}=PROMO1;{_season}=summer。
键不能包含分号。如果 Value 包含分号，则必须将其转义为“\;”。此外，如果 Value 包含反斜杠，则还必须将其转义为“\”。
键不能超过 16 个 UTF-8 字节，值不能超过 250 UTF-8 个字节。密钥是必需的，值是可选的。键的最大大小不包括大括号和下划线，即“{”、“_”和“}”。

注意

使用批量服务时，必须使用周围的大括号和前导下划线设置密钥的格式，例如，如果密钥是 promoCode，则必须将其格式设置为 {_promoCode}。使用市场活动管理服务时，不能指定周围的大括号和下划线。

添加： 选
更新： 选。如果未为更新设置任何值，则不会更改此设置。若要删除所有自定义参数，请将此字段设置为 delete_value。 delete_value关键字 (keyword) 删除以前的设置。若要删除自定义参数的子集，请指定要保留的自定义参数，并省略任何不想保留的参数。新的自定义参数集将替换以前的任何自定义参数集。
删除： 只读

编辑上诉状态

确定是否可以对编辑评审发现的问题提出上诉。

下表介绍了可能的值。

值	说明
上诉	编辑问题很有吸引力。
AppealPending	编辑问题可上诉，已提出上诉。
NotAppealable	编辑问题没有吸引力。

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

编辑位置

编辑评审失败的广告的组件或属性。

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

编辑原因代码

标识失败原因的代码。有关可能的原因代码列表，请参阅编辑原因代码。

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

编辑状态

广告的编辑状态。

下表介绍了可能的值。

值	说明
活动	广告通过了编辑评审。
ActiveLimited	广告在一个或多个市场通过了编辑评审，广告的一个或多个元素正在另一个市场进行编辑评审。例如，广告通过了加拿大的编辑评审，并且仍在美国中等待评审。
反对	广告未通过编辑评审。
非活动	广告的一个或多个元素正在接受编辑评审。

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

编辑术语

编辑评审失败的术语。

如果术语组合导致失败，或者失败基于策略冲突，则不会设置此字段。

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

最终 URL 后缀

最终 URL 后缀可以包括跟踪参数，这些参数将追加到登陆页 URL 的末尾。建议将登陆页面所需的跟踪参数放在最终 URL 后缀中，以便始终将客户发送到登陆页面。有关更多详细信息和验证规则，请参阅技术指南中的最终 URL 后缀。

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

Id

广告的系统生成的标识符。

添加： 选。必须将此字段留空，或指定负标识符。然后，可以在依赖记录类型的 父 ID 字段中引用为广告设置的负标识符，例如动态搜索广告标签。如果要在同一批量文件中添加新广告和新的从属记录，则建议这样做。有关详细信息，请参阅批量文件架构引用密钥。
更新： 只读和必需
删除： 只读和必需

修改时间

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

注意

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

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

父 ID

包含广告的广告组的系统生成的标识符。

此批量字段映射到广告组记录的 Id 字段。

添加： 只读和必需。必须指定现有广告组标识符，或指定等于父广告组记录的 Id 字段的负标识符。如果要将新广告添加到同一批量文件中的新广告组，则建议这样做。有关详细信息，请参阅批量文件架构引用密钥。
更新： 只读
删除： 只读

注意

若要添加、更新和删除，必须指定 “父 ID ”或 “广告组” 字段。

路径 1

将追加到显示 URL 的域部分的可选路径的第一部分。显示 URL（例如 ，www.contoso.com ）将从显示 URL 的域生成。如果为 路径 1 指定了值，则会将其追加到显示 URL。如果还为 路径 2 指定了一个值，则该值也将追加到 路径 1 后的显示 URL。例如，如果域 contoso.com， 路径 1 设置为 subdirectory1， 路径 2 设置为 subdirectory2，则显示的 URL 将 www.contoso.com/subdirectory1/subdirectory2。

路径的最大输入长度为 15 个字符。请注意，对于具有双角字符的语言（例如繁体中文），路径的最大输入长度为 7 个字符。

路径可以包含 IF 和倒计时函数。无论所有未替换倒计时参数的总长度如何，最终显示的倒计时将始终使用可用字符总数中的 8 个字符。有关详细信息，请参阅倒计时自定义工具。

路径不能包含正斜杠 (/) 或换行 (\n) 字符。

如果路径包含空格，则会在显示广告时将其替换为下划线 (_) 。

路径 2

将追加到显示 URL 的域部分的可选路径的第二部分。显示 URL（例如 ，www.contoso.com ）将从动态搜索广告市场活动级别设置的域生成。如果为 路径 1 指定了值，则会将其追加到显示 URL。如果还为 路径 2 指定了一个值，则该值也将追加到 路径 1 后的显示 URL。例如，如果域 contoso.com， 路径 1 设置为 subdirectory1， 路径 2 设置为 subdirectory2，则显示的 URL 将 www.contoso.com/subdirectory1/subdirectory2。

如果还设置了 路径 1 ，则只能指定路径 2。

路径的最大输入长度为 15 个字符。请注意，对于具有双角字符的语言（例如繁体中文），路径的最大输入长度为 7 个字符。

路径不能包含正斜杠 (/) 或换行 (\n) 字符。如果路径包含空格，则会在显示广告时将其替换为下划线 (_) 。

发布者国家/地区

编辑指南不允许指定术语的发布者国家或地区的列表。

在批量文件中，发布者国家或地区的列表用分号 (;) 分隔。

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

状态

广告的状态。

可能的值为 Active、 Paused 或 Deleted。

添加： 选。默认值为 Active。
更新： 选。如果未为更新设置任何值，则不会更改此设置。
删除： 必填。 “状态”必须设置为 “已删除”。

Text

广告说明的第一部分。

文本必须至少包含一个单词。

副本的最大输入长度为 90 个字符。请注意，对于使用繁体中文的广告组，副本的最大输入长度为 45 个字符。

文本可以包含 IF 和倒计时函数。无论所有未替换倒计时参数的总长度如何，最终显示的倒计时将始终使用可用字符总数中的 8 个字符。有关详细信息，请参阅倒计时自定义工具。

文本不能包含换行符 (\n) 。

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

文本第 2 部分

广告说明的第二部分。

文本必须至少包含一个单词。

副本的最大输入长度为 90 个字符。请注意，对于使用繁体中文的广告组，副本的最大输入长度为 45 个字符。

文本不能包含换行符 (\n) 。

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

跟踪模板

要用作 FinalUrls 指定 URL 的默认跟踪模板。

以下验证规则适用于跟踪模板。有关支持的模板和参数的更多详细信息，请参阅 Microsoft Advertising 帮助文章我可以使用哪些跟踪或 URL 参数？

为较低级别的实体（例如广告）定义的跟踪模板将覆盖为较高级别的实体（例如市场活动）设置的模板。有关详细信息，请参阅实体限制。
跟踪模板的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。
跟踪模板必须是格式正确的 URL，从以下项之一开始： http://、 https://、 {lpurl}或 {unescapedlpurl}。
Microsoft Advertising 不会验证自定义参数是否存在。如果在跟踪模板中使用自定义参数，并且这些参数不存在，则登陆页 URL 将包含自定义参数的键和值占位符，而不进行替换。例如，如果跟踪模板为 https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}，并且未在市场活动、广告组、条件、关键字 (keyword) 或广告级别定义 {_season} 或 {_promocode}，则登陆页 URL 将相同。

通过

动态搜索广告记录 - 批量

广告组

Campaign

客户端 ID

自定义参数

编辑上诉状态

编辑位置

编辑原因代码

编辑状态

编辑术语

最终 URL 后缀

Id

修改时间

父 ID

路径 1

路径 2

发布者国家/地区

状态

Text

文本第 2 部分

跟踪模板

反馈

其他资源