传单广告扩展记录 - 批量

项目
11/13/2024

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

传单扩展使广告客户能够向潜在客户分发产品或商店目录 (传单) 。

它们可以在广泛的查询（如“每周交易”或“每周销售额”）上突出显示，从而鼓励购物者点击你的广告，而不是竞争对手的广告。根据其性质，它们有助于更好地通知搜索者，因此，提高用户参与度，例如点击率。

注意

功能试点 (GetCustomerPilotFeatures 返回 802) ，客户可以使用传单扩展。

可以将传单广告扩展与帐户或帐户中的市场活动及广告组相关联。 (帐户、市场活动或广告组) 的每个实体最多可与 3 个传单广告扩展相关联。使用帐户传单广告扩展、广告组传单广告扩展和市场活动传单广告扩展记录来管理传单广告扩展关联。

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

以下批量 CSV 示例会将新的 Flyer Ad Extension 添加到帐户的共享库。

Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Start Date,End Date,Store Id,Name,Ad Schedule,Use Searcher Time Zone,Flyer Name,Description,Final Url,Mobile Final Url,Media Ids,Media Urls
Format Version,,,,,,,,,,,6.0,,,,,,
Flyer Ad Extension,Active,-18,0,,,ClientIdGoesHere,,,12/31/2020,,,(Monday[09:00-21:00]),FALSE,Flyer name goes here, Flyer description goes here,https://www.contoso.com/one; https://www.contoso.com/two; https://www.contoso.com/three,https://mobile.contoso.com/one; https://mobile.contoso.com/two; https://mobile.contoso.com/three,12345678,

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

// Map properties in the Bulk file to the BulkFlyerAdExtension
var bulkFlyerAdExtension = new BulkFlyerAdExtension
{
    // 'Parent Id' column header in the Bulk file
    AccountId = 0,
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",

    // Map properties in the Bulk file to the 
    // FlyerAdExtension object of the Campaign Management service.
    FlyerAdExtension = new FlyerAdExtension
    {
        // 'Description' column header in the Bulk file
        Description = "Flyer description",

        // 'Id' column header in the Bulk file
        Id = flyerAdExtensionIdKey,
                        
        // '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/one",
            "https://www.contoso.com/two",
            "https://www.contoso.com/three"
        },
        // '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/one",
            "https://mobile.contoso.com/two",
            "https://mobile.contoso.com/three"
        },
        // 'Flyer Name' column header in the Bulk file
        FlyerName = "Flyer name",
        // 'Media Ids' column header in the Bulk file
        ImageMediaIds = new[] {
            (long)12345678,
        },
        // 'Media Urls' column header in the Bulk file
        ImageMediaUrls = null,
        // 'Store Id' column header in the Bulk file
        StoreId = 12345678,
        // '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"
                },
            }
        },
        // 'Ad Schedule' column header in the Bulk file
        Scheduling = new Schedule
        {
            // Each day and time range is delimited by a semicolon (;) in the Bulk file
            DayTimeRanges = new[]
            {
                // Within each day and time range the format is Day[StartHour:StartMinue-EndHour:EndMinute].
                new DayTime
                {
                    Day = Day.Monday,
                    StartHour = 9,
                    StartMinute = Minute.Zero,
                    EndHour = 21,
                    EndMinute = Minute.Zero,
                },
            },
            // 'End Date' column header in the Bulk file
            EndDate = new Microsoft.BingAds.V13.CampaignManagement.Date
            {
                Month = 12,
                Day = 31,
                Year = DateTime.UtcNow.Year + 1
            },
            // 'Start Date' column header in the Bulk file
            StartDate = null,
            // 'Use Searcher Time Zone' column header in the Bulk file
            UseSearcherTimeZone = false,
        },

        // 'Status' column header in the Bulk file
        Status = AdExtensionStatus.Active,
    },
};

uploadEntities.Add(bulkFlyerAdExtension);

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

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

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

广告计划
客户端 ID
说明
编辑位置
编辑原因代码
编辑状态
编辑术语
"结束日期"
最终 URL
传单名称
Id
媒体 ID
媒体 URL
移动最终 URL
修改时间
父 ID
发布者国家/地区
"开始日期"
状态
应用商店 ID
使用搜索器时区
版本

广告计划

希望广告扩展插件随广告一起显示的日期和时间范围列表。每天和时间范围包括计划的星期几、开始/结束小时和开始/结束分钟。每天和时间范围都用左括号和右括号括起来，并用分号 (;) 分隔符分隔其他日期和时间范围。在每天和时间范围内，格式为 Day[StartHour：StartMinue-EndHour：EndMinute]。

StartHour 的可能值范围为 00 到 23，其中 00 相当于 12：00AM，12 等于中午 12：00。

EndHour 的可能值范围为 00 到 24，其中 00 相当于凌晨 12：00,12 等于中午 12：00。

StartMinute 和 EndMinute 的可能值范围为 00 到 60。

以下示例演示工作日从上午 9：00 到晚上 9：00 的日期和时间范围： (Monday[09：00-21：00]) ; (Tuesday[09：00-21：00]) ; (星期三[09：00-21：00]) ; (星期四[09：00-21：00]) ; (星期五[09：00-21：00])

添加： 选。如果未设置此字段，广告扩展插件将有资格在日历开始和结束日期期间随时进行计划。
更新： 选。无法更新单个日期和时间范围。可以通过发送应替换上一组的新集来有效地更新日期和时间范围。 “广告计划”和“使用搜索程序时区”字段相互依赖，并一起更新。如果在更新期间将这两个字段留空，则两个字段都不会更新。如果包括其中任何字段的值，则会删除或替换其中每个字段的先前值。
删除： 只读

客户端 ID

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

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

说明

广告客户、代理或客户经理可用于跟踪、标记或管理传单扩展的说明。

此说明不会随广告或图像一起显示。

此元素的最大长度为 1,024 个字符。

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

编辑位置

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

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

编辑原因代码

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

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

编辑状态

广告扩展的编辑状态。

下表介绍了可能的值。

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

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

编辑术语

编辑评审失败的术语。

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

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

End Date

格式化为 MM/DD/YYYY 的广告扩展计划结束日期字符串。

结束日期是包含的。例如，如果将此字段设置为 2020 年 12 月 31 日，广告扩展将在 2020 年 12 月 31 日晚上 11：59 停止显示。

结束日期必须在开始日期后的 30 天内。

添加： 必填
更新： 选。结束日期可以缩短或延长，只要开始日期未设置或出现在新的结束日期之前的 30 天。
删除： 只读

最终 URL

登陆页 URL。

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

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

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

传单名称

传单名称。

此元素的最大长度为 150 个字符。

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

Id

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

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

媒体 ID

要包含在广告中的图像的标识符。

只能设置一个媒体 ID。

每个媒体 ID 对应于“GenericImage”子类型的图像。

图像的最小宽度和高度应为 220px，最大文件大小应为 3.9MB。

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

媒体 URL

已添加的媒体的 URL。

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

移动最终 URL

移动设备的登陆页 URL。

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

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

修改时间

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

注意

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

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

父 ID

包含广告扩展的帐户的系统生成的标识符。

此批量字段映射到帐户记录的 ID 字段。

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

发布者国家/地区

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

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

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

开始日期

格式化为 MM/DD/YYYY 的广告扩展计划开始日期字符串。

开始日期是包含的。例如，如果将 StartDate 设置为 5/5/2020，广告扩展将在 2020 年 5 月 5 日凌晨 12：00 开始显示。

结束日期必须在开始日期后的 30 天内。

添加： 必填
更新： 选。开始日期可以缩短或延长，前提是结束日期未设置或出现在新开始日期后的 30 天内。
删除： 只读

状态

广告扩展的状态。

可能的值为 Active 或 Deleted。

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

应用商店 ID

用于产品广告的 Microsoft 商家中心商店的唯一标识符。

添加： 选
更新： 只读。设置后，无法更新存储 ID。
删除： 只读

使用搜索器时区

确定是使用帐户时区还是搜索用户的时区（可在其中投放广告）。

如果希望广告扩展显示在搜索用户的时区中，则将此属性设置为 TRUE ，否则将其设置为 FALSE。

添加： 选。如果未指定此字段或将其留空，则将设置默认值 FALSE ，并使用帐户时区。
更新： 选。如果将此字段设置为 delete_value 字符串，则实际上将重置为默认值 FALSE。 “广告计划”和“使用搜索程序时区”字段相互依赖，并一起更新。如果在更新期间将这两个字段留空，则两个字段都不会更新。如果包括其中任何字段的值，则会删除或替换其中每个字段的先前值。
删除： 只读

版本

广告扩展内容已更新的次数。添加扩展时，版本设置为 1，每次修改时都会递增。

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

通过

传单广告扩展记录 - 批量

广告计划

客户端 ID

说明

编辑位置

编辑原因代码

编辑状态

编辑术语

End Date

最终 URL

传单名称

Id

媒体 ID

媒体 URL

移动最终 URL

修改时间

父 ID

发布者国家/地区

开始日期

状态

应用商店 ID

使用搜索器时区

版本

反馈

其他资源