文本广告记录 - 批量

项目
11/13/2024

定义可在批量文件中下载和上传的文本广告。

重要

从 2020 年 4 月开始，不支持 (STA) 提供独立文本广告。

标准文本广告已弃用，转而使用扩展文本广告 (EXTA) 。 ) 2017 年 7 月 31 日终止了 (STA 添加和更新标准文本广告的支持。现在，广告客户可以获取和删除，但无法再添加新的 STA 或更新现有的标准文本广告。规则的一个例外是，你仍然可以将 STA 状态更新，例如从 “活动” 更改为 “已暂停”。否则，尝试添加或更新 STA 将导致 CampaignServiceAdTypeInvalid 错误。

可以通过在 DownloadCampaignsByAccountIds 或 DownloadCampaignsByCampaignIds 服务请求中包含 TextAds 的 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,Ad Format Preference,Name,App Platform,App Id,Final Url,Mobile Final Url,Tracking Template,Custom Parameter,Title Part 1,Title Part 2,Path 1,Path 2
Format Version,,,,,,,,,,,,,,6.0,,,,,,,,,,
Text Ad,Active,,-1111,ParentCampaignNameGoesHere,AdGroupNameGoesHere,ClientIdGoesHere,,Contoso Quick Setup,Find New Customers & Increase Sales!,contoso.com,,,All,False,,,,https://www.contoso.com/womenshoesale,https://mobile.contoso.com/womenshoesale,,{_promoCode}=PROMO1; {_season}=summer,,,,

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkTextAd
var bulkTextAd = new BulkTextAd
{
    // '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 
    // TextAd object of the Campaign Management service.
    TextAd = new TextAd
    {
        // 'Ad Format Preference' column header in the Bulk file
        AdFormatPreference = "All",
        // 'Destination Url' column header in the Bulk file
        DestinationUrl = null,
        // 'Device Preference' column header in the Bulk file
        DevicePreference = 0,
        // 'Display Url' column header in the Bulk file
        DisplayUrl = "contoso.com",
        // 'Mobile Final Url' column header in the Bulk file
        FinalMobileUrls = new[] {
            // Each Url is delimited by a semicolon (;) in the Bulk file
            "https://mobile.contoso.com/womenshoesale"
        },
        // 'Final Url' column header in the Bulk file
        FinalUrls = new[] {
            // Each Url is delimited by a semicolon (;) in the Bulk file
            "https://www.contoso.com/womenshoesale"
        },
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Status' column header in the Bulk file
        Status = AdStatus.Active,
        // 'Text' column header in the Bulk file
        Text = "Find New Customers & Increase Sales!",
        // 'Title' column header in the Bulk file
        Title = "Contoso Quick Setup",
        // '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(bulkTextAd);

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

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

对于 文本广告 记录，批量文件架构中提供了以下属性字段。

广告格式首选项
广告组
市场活动
客户端 ID
自定义参数
设备首选项
显示 URL
编辑上诉状态
编辑位置
编辑原因代码
编辑状态
编辑术语
最终 URL
Id
移动最终 URL
修改时间
父 ID
发布者国家/地区
状态
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}。使用市场活动管理服务时，不能指定周围的大括号和下划线。

添加： 不支持
更新： 不支持
删除： 只读

设备首选项

此字段确定首选项是在所有设备上显示文本广告，还是仅在移动设备上显示。

可能的值为 All 和 Mobile，这与市场活动管理服务中使用的值不同。

SixMonths

在批量下载和上传结果文件中，此字段永远不会为空。如果未指定设备首选项，将返回默认值 All 。

重要

必须为每个广告组定义至少一个非移动首选的文本广告，否则所有文本广告的广告副本将适用于所有设备。

添加： 不支持
更新： 不支持
删除： 只读

显示 URL

要显示在广告中的 URL。

显示 URL 的子目录可以包含动态文本字符串，例如 {关键字 (keyword) };但是，URL 主机名不能包含动态文本。有关详细信息，请参阅 Microsoft Advertising 帮助文章使用动态文本参数自动自定义广告。

URL 的最大输入长度为 200 个字符，可以包含动态文本字符串。但是，如果 URL 在动态文本替换发生后超过 35 个字符，广告将无法显示。

添加： 不支持
更新： 不支持
删除： 只读

编辑上诉状态

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

下表介绍了可能的值。

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

添加： 不支持
更新： 只读
删除： 只读

编辑位置

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

添加： 不支持
更新： 只读
删除： 只读

编辑原因代码

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

添加： 不支持
更新： 只读
删除： 只读

编辑状态

广告的编辑状态。

下表介绍了可能的值。

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

添加： 不支持
更新： 只读
删除： 只读

编辑术语

编辑评审失败的术语。

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

添加： 不支持
更新： 只读
删除： 只读

最终 URL

登陆页 URL。

以下验证规则适用于最终 URL 和最终移动 URL。

URL 的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。
最多可为最终 URL 和最终移动 URL 指定 10 个项目;但是，每个列表中的第一项仅用于传递。该服务最多允许 10 个，以确保潜在的向前兼容性。
每个 URL 由分号和空格 (“分隔;“) 。
仅允许使用“{”和“}”来描述标记，例如“{lpurl}”。
每个 URL 必须是格式正确的 URL，以 http:// 或 https:// 开头。
如果指定“最终移动 URL”，还必须指定“最终 URL”。

另请注意，如果设置了“跟踪模板”或“自定义参数”字段，则至少需要一个“最终 URL”。

注意

仅当关键字 (keyword) 未指定最终 URL 时，才使用此 URL。

添加： 不支持
更新： 不支持
删除： 只读

Id

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

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

移动最终 URL

移动登陆页 URL。

以下验证规则适用于最终 URL 和最终移动 URL。

URL 的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。
最多可为最终 URL 和最终移动 URL 指定 10 个项目;但是，每个列表中的第一项仅用于传递。该服务最多允许 10 个，以确保潜在的向前兼容性。
每个 URL 由分号和空格 (“分隔;“) 。
仅允许使用“{”和“}”来描述标记，例如“{lpurl}”。
每个 URL 必须是格式正确的 URL，以 http:// 或 https:// 开头。
如果指定“最终移动 URL”，还必须指定“最终 URL”。

注意

仅当关键字 (keyword) 未指定移动最终 URL 时，才使用此 URL。

添加： 不支持
更新： 不支持
删除： 只读

修改时间

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

注意

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

添加： 不支持
更新： 只读
删除： 只读

父 ID

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

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

添加： 不支持
更新： 只读
删除： 只读

注意

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

发布者国家/地区

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

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

添加： 不支持
更新： 只读
删除： 只读

状态

广告的状态。

可能的值为 Active、 Paused 或 Deleted。

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

Text

广告副本。

文本必须至少包含一个单词，并且可以包含动态文本字符串，例如 {关键字 (keyword) }。有关详细信息，请参阅 Microsoft Advertising 帮助文章使用动态文本参数自动自定义广告。

副本的最大输入长度为 300 个字符，可以包含动态文本字符串。如果动态文本替换发生后长度超过 80 个字符，广告将无法显示，或者将使用默认文本。请注意，对于使用繁体中文的广告组，副本的最大输入长度为 150 个字符，替换后文本限制为 40 个字符。

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

添加： 不支持
更新： 不支持
删除： 只读

标题

广告的标题。

标题必须至少包含一个单词。广告的副本和标题组合在一起必须至少三个字。

标题可以包含动态文本字符串，例如 {关键字 (keyword) }。有关详细信息，请参阅 Microsoft Advertising 帮助文章使用动态文本参数自动自定义广告。

标题的最大输入长度为 80 个字符，可以包含动态文本字符串。如果动态文本替换发生后长度超过 25 个字符，广告将无法显示，或使用默认文本。请注意，对于使用繁体中文的广告组，替换后的标题限制为 15 个字符。

标题不能包含换行符 (\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

编辑上诉状态

编辑位置

编辑原因代码

编辑状态

编辑术语

最终 URL

Id

移动最终 URL

修改时间

父 ID

发布者国家/地区

状态

Text

标题

跟踪模板

反馈

其他资源