位置广告扩展记录 - 批量

项目
11/13/2024

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

可以将位置广告扩展插件与帐户或该帐户中的市场活动相关联。每个实体 (帐户或市场活动) 可以与你决定的任意数量的位置广告扩展相关联，最多与帐户中的位置广告扩展的总数相关联。使用帐户位置广告扩展和市场活动位置广告扩展记录来管理位置广告扩展关联。

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

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

Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Start Date,End Date,Business Name,Phone Number,Device Preference,Name,Ad Schedule,Use Searcher Time Zone,Address Line 1,Address Line 2,Postal Code,City,State Or Province Code,Province Name,Latitude,Longitude,Country Code
Format Version,,,,,,,,,,,,,6.0,,,,,,,,,,,
Location Ad Extension,Active,-15,0,,,ClientIdGoesHere,,,12/31/2020,Contoso Shoes,206-555-0100,,,(Monday[09:00-21:00]),FALSE,1234 Washington Place,Suite 1210,98608,Woodinville,,WA,0,0,US

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkLocationAdExtension
var bulkLocationAdExtension = new BulkLocationAdExtension
{
    // '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 
    // LocationAdExtension object of the Campaign Management service.
    LocationAdExtension = new LocationAdExtension
    {
        Address = new Address
        {
            // 'City' column header in the Bulk file
            CityName = "Woodinville",
            // 'Country Code' column header in the Bulk file
            CountryCode = "US",
            // 'Postal Code' column header in the Bulk file
            PostalCode = "98608",
            // 'State Or Province Code' column header in the Bulk file
            ProvinceCode = null,
            // 'Province Name' column header in the Bulk file
            ProvinceName = "WA",
            // 'Address Line 1' column header in the Bulk file
            StreetAddress = "1234 Washington Place",
            // 'Address Line 2' column header in the Bulk file
            StreetAddress2 = "Suite 1210",
        },
        // 'Business Name' column header in the Bulk file
        CompanyName = "Contoso Shoes",
        // 'Geo Code Status' column header in the Bulk file
        GeoCodeStatus = null,
        GeoPoint = new GeoPoint
        {
            // 'Latitude' column header in the Bulk file
            LatitudeInMicroDegrees = 0,
            // 'Longitude' column header in the Bulk file
            LongitudeInMicroDegrees = 0,
        },
        // 'Id' column header in the Bulk file
        Id = locationAdExtensionIdKey,
        // 'Phone Number' column header in the Bulk file
        PhoneNumber = "206-555-0100",

        // '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(bulkLocationAdExtension);

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

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

对于 Location Ad Extension 记录，批量文件架构中提供了以下属性字段。

广告计划
地址行 1
地址行 2
企业名称
市/县
客户端 ID
国家/地区代码
编辑位置
编辑原因代码
编辑状态
编辑术语
"结束日期"
地理代码状态
Id
Latitude
Longitude
修改时间
父 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])

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

地址行 1

地址的第一行。

第一行最多可以包含 80 个字符。

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

地址行 2

地址的第二行。

第二行最多可以包含 80 个字符。

添加： 选
更新： 选。如果未为更新设置任何值，则会删除以前的设置。
删除： 只读

企业名称

企业名称。

名称最多可以包含 80 个字符。

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

市/县

街道地址所在的城市的名称。

名称最多可以包含 80 个字符。

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

客户端 ID

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

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

Country Code

街道地址所在的国家或地区。

国家/地区代码必须包含 2 个字符的国家/地区代码。支持的国家/地区代码值包括 AR、AT、AU、BR、CA、CH、CL、CO、DE、DK、ES、FI、FR、GB、HK、ID、IE、IN、IT、MX、MY、NL、NZ、NO、PE、PH、SE、SG、TH、TW、US、VE 和 VN。

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

编辑位置

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

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

编辑原因代码

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

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

编辑状态

广告扩展的编辑状态。

下表介绍了可能的值。

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

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

编辑术语

编辑评审失败的术语。

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

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

End Date

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

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

添加： 选。如果未指定结束日期，除非暂停关联的市场活动、广告组或广告，否则广告扩展将继续交付。
更新： 选。只要开始日期为 null 或出现在新的结束日期之前，就可以缩短或延长结束日期。如果将此字段设置为 delete_value 字符串，则实际上删除了结束日期。 “广告计划”、“结束日期 ”、“开始日期”和“使用搜索器时区”字段相互依赖，并一起更新。如果在更新期间将所有这些字段留空，则不会更新这些字段。如果包含其中任何字段的值，则会删除或替换所有这些字段的先前值。若要删除以前的所有计划设置，请将其中每个字段设置为 delete_value。
删除： 只读

地理代码状态

一个状态值，该值指示是否已确定企业的纬度和经度坐标。

如果提供坐标，状态将设置为 “完成”;否则，状态将指示确定指定企业地址坐标的进度。

下表介绍了可能的值。

值	说明
完成	已成功确定业务的纬度和经度。
已失败	无法确定业务的纬度和经度。
Invalid	无法确定业务的纬度和经度，可能是因为地址未解析。
Pending	在确定业务的纬度和经度的过程中。

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

Id

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

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

Latitude

以度为单位指定的纬度。纬度必须大于或等于 -85 且小于或等于 +85。

注意

市场活动管理服务使用微度，即从 -85000000 到 85000000。通过 SDK 使用 BulkLocationAdExtension 时，应使用微度，因为 BulkLocationAdExtension 实现从微度转换，并将值写入批量文件中的度数。

当用户单击广告上的地址时，纬度和经度坐标用于在必应地图上标记业务的位置。如果指定的坐标不在有效值的范围内，则服务将根据地址确定坐标。

如果指定已知坐标，则服务不会确认指定的坐标是否与指定的业务地址匹配。如果未提供坐标，批量服务将使用企业的地址来确定坐标。

注意

添加超过 10 个位置广告扩展时，服务将脱机解析坐标，并在执行服务操作期间提前解析坐标。在确定坐标之前，不会在广告中使用位置，这可能需要几秒钟到几分钟的时间，具体取决于要添加的位置广告扩展的数量和当前需求。

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

Longitude

以度为单位指定的经度。经度必须大于或等于 -180 且小于或等于 +180。

注意

市场活动管理服务使用微度，即从 -180000000 到 180000000。通过 SDK 使用 BulkLocationAdExtension 时，应使用微度，因为 BulkLocationAdExtension 实现从微度转换，并将值写入批量文件中的度数。

当用户单击广告上的地址时，纬度和经度坐标用于在必应地图上标记业务的位置。如果指定的坐标不在有效值的范围内，则服务将根据地址确定坐标。

如果指定已知坐标，则服务不会确认指定的坐标是否与指定的业务地址匹配。如果未提供坐标，批量服务将使用企业的地址来确定坐标。

注意

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

修改时间

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

注意

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

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

父 ID

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

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

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

电话号码

要包含在广告中的企业可点击电话号码。

电话号码最多可以包含 35 个字符，并且必须对指定的国家或地区有效。

如果市场活动还包括呼叫分机，则呼叫扩展中的电话号码将覆盖位置广告分机的电话号码。

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

邮政编码

邮政编码。

邮政编码最多可以包含 80 个字符。

添加： 选
更新： 选。如果未为更新设置任何值，则会删除以前的设置。
删除： 只读

省/自治区/直辖市名称

街道地址所在的州或省的名称，例如 华盛顿。

名称最多可以包含 50 个字符。

必须指定省/自治区/直辖市或省/自治区/直辖市

注意

如果“国家/地区代码”字段设置为 FR、IE 或 SG，则不需要“州或省/自治区代码”和“省名称”。

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

发布者国家/地区

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

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

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

开始日期

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

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

添加： 选。如果未指定开始日期，广告扩展将立即符合计划条件。
更新： 选。只要结束日期为 null 或发生在新的开始日期之后，就可以缩短或延长开始日期。如果将此字段设置为 delete_value 字符串，则实际上将删除开始日期，并且广告扩展将立即符合计划条件。 “广告计划”、“结束日期 ”、“开始日期”和“使用搜索器时区”字段相互依赖，并一起更新。如果在更新期间将所有这些字段留空，则不会更新这些字段。如果包含其中任何字段的值，则会删除或替换所有这些字段的先前值。若要删除以前的所有计划设置，请将其中每个字段设置为 delete_value。
删除： 只读

省/自治区/直辖市/自治区/直辖市/

标识街道地址所在的州或省（例如 WA）的代码。

代码最多可以包含 50 个字符。

必须指定省/自治区/直辖市或省/自治区/直辖市

注意

如果“国家/地区代码”字段设置为 FR、IE 或 SG，则不需要“州或省/自治区代码”和“省名称”。

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

状态

广告扩展的状态。

可能的值为 Active 或 Deleted。

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

使用搜索器时区

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

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

添加： 选。如果未指定此字段或将其留空，则将设置默认值 FALSE ，并使用帐户时区。
更新： 选。如果将此字段设置为 delete_value 字符串，则实际上将重置为默认值 FALSE。 “广告计划”、“结束日期 ”、“开始日期”和“使用搜索器时区”字段相互依赖，并一起更新。如果在更新期间将所有这些字段留空，则不会更新这些字段。如果包含其中任何字段的值，则会删除或替换所有这些字段的先前值。若要删除以前的所有计划设置，请将其中每个字段设置为 delete_value。
删除： 只读

版本

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

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

通过

位置广告扩展记录 - 批量

广告计划

地址行 1

地址行 2

企业名称

市/县

客户端 ID

Country Code

编辑位置

编辑原因代码

编辑状态

编辑术语

End Date

地理代码状态

Id

Latitude

Longitude

修改时间

父 ID

电话号码

邮政编码

省/自治区/直辖市名称

发布者国家/地区

开始日期

省/自治区/直辖市/自治区/直辖市/

状态

使用搜索器时区

版本

反馈

其他资源