广告组酒店列表组记录 - 批量

项目
11/13/2024

定义可在批量文件中上传和下载的广告组酒店列表组。

只要满足以下所述的验证规则，就可以在同一批量文件中上传多个广告组的 Ad Group Hotel 一览 组记录。

至少必须为酒店列表组树结构指定根节点。酒店列表组的根节点必须将其 “酒店属性” 字段设置为“全部”，并将 “酒店属性值 ”设置为 null 或空。如果对目录中所有酒店进行平均竞价，请将“ 子类型” 字段设置为 “单位”。如果要根据更具体的酒店属性对出价进行分区，请将“ 子类型” 字段设置为 “细分”，将 “父条件 ID ”设置为 null 或空，并将 “ID ”设置为负值。你将使用负值作为任何子节点的 父条件 ID 。
根节点被视为级别 0，树最多可以有 7 个级别深的分支。
每个上传请求，每个广告组最多可以包含 20,000 个酒店列表组树节点。广告组的整个酒店列表组树节点计数不能超过 20,000。
同一树 (同一广告组) 的酒店列表组树节点必须在文件中组合在一起。
在下载期间无法保证酒店列表组节点的顺序，父节点可能在子节点之后提供：但是，同一广告组的所有节点都将在文件中组合在一起。
如果要创建或修改树结构，则必须在子酒店列表组树节点之前对父酒店列表组树节点进行排序;但是，订单对于非结构性更改（如更新出价）无关紧要。例如，如果要在不添加、删除或更新树结构的情况下更新出价，则只需上传 ID、父 ID 和出价字段。
若要更新 “酒店属性”、“ 酒店属性值 ”或 “排除 ”字段，必须删除现有的酒店列表组树节点，并上传一个新的酒店列表组树节点，该节点将获取新的标识符。
如果任何操作失败，则可能已成功的所有剩余操作也将失败。
所有酒店列表组节点添加和删除操作都必须生成完整的树结构。
从根节点到分支末尾的每个路径都必须以叶节点 (Sub Type=Unit) 终止。每个单元都必须有出价，除非“ 排除 ”字段 为 true ，这意味着该节点是负广告组条件。
每个细分必须至少有一个叶节点，用于对细分条件的其余部分进行出价，即使用与其同级单位相同的操作数 () ，并将其 Hotel 属性值设置为 null 或为空。
如果要添加具有多个级别的分区，其中父级或子级尚不存在，请使用负 int 值作为引用来标识父级。例如，将父级的 Id 和子级的“ 父条件 ID ”字段设置为同一负值。负 ID 仅在调用期间有效。上传结果文件中返回每个成功添加的广告组条件的唯一系统标识符。
仅当“排除”字段为 false 时，“出价”字段才适用，这意味着节点是可出价的广告组条件。但是，对于细分分区节点，将忽略 Bid。这些元素仅与单元 (叶) 分区节点相关。
若要暂停任何酒店列表组，必须通过将广告组的 “状态” 字段更新为“已暂停”来暂停整个广告组。可以通过将市场活动的状态字段更新为“已暂停 ” 来暂停整个市场活动。
对于 “已删除” 操作，只需指定 ID 和 父 ID。
如果删除父酒店列表组，也会删除其所有子级和后代。
不能在分支中指定重复的酒店属性。

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

如果提供了有效的父 ID 值，下面的批量 CSV 示例将添加新的广告组酒店列表组。

Type,Name,Campaign,Time Zone,Campaign Type,Language,Sub Type,Budget Id,Budget,Budget Type,Bid Strategy Type,Bid Strategy PercentMaxCpc,Ad Schedule Use Searcher Time Zone,Client Id,Id,Parent ID,Parent Criterion Id,Ad Group,Ad Group Type,Search Network,Content Network,Percent Cpc Bid,Hotel Ad Group Type,Percent Bid,Hotel Attribute,Hotel Attribute Value,Is Excluded
Format Version,6,,,,,,,,,,,,,,,,,,,,,,,,,
Campaign,,Test Hotel Campaign HLG,PacificTimeUSCanadaTijuana,Hotel,All,,delete_value,25,DailyBudgetStandard,PercentCpc,8.3,false,0,,,,,,,,,,,,,,
AdGroup,,Test Hotel Campaign HLG,,,,,,,,,,,,,,,Test Hotel AdGroup,Hotel,On,Off,3.74,HotelAd,,,,,
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Subdivision,,,,,,,,-1,,,Test Hotel AdGroup,,,,,HotelAd,,All,,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-2,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,Marriott,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-3,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,Hilton,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-4,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,,false

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkAdGroupProductPartition
var bulkAdGroupProductPartition = new BulkAdGroupProductPartition
{
    // Map properties in the Bulk file to the BiddableAdGroupCriterion or
    // NegativeAdGroupCriterion object of the Campaign Management service.
    // Use the BiddableAdGroupCriterion to set the 'Is Excluded' field in the Bulk file to true,
    // and otherwise use the NegativeAdGroupCriterion to set the 'Is Excluded' field to false.
    BiddableAdGroupCriterion = new BiddableAdGroupCriterion
    {
        // 'Parent Id' column header in the Bulk file
        AdGroupId = adGroupIdKey,
        Criterion = new HotelListingGroup { 
            Condition = new HotelListingCondition
            {
                // 'Hotel Attribute Value' column header in the Bulk file
                Attribute = null,
                // 'Hotel Attribute' column header in the Bulk file
                Operand = "All",
            },
            // 'Parent Criterion Id' column header in the Bulk file
            ParentCriterionId = null
        },
        CriterionBid = new FixedBid
        {
            // 'Bid' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
            Amount = 0.50
        },
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Status' column header in the Bulk file
        Status = AdGroupCriterionStatus.Paused,
        // 'Tracking Template' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
        TrackingUrlTemplate = null,
        // 'Custom Parameter' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
        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 Group' column header in the Bulk file
    AdGroupName = null,
    // 'Campaign' column header in the Bulk file
    CampaignName = null,
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
};

uploadEntities.Add(bulkAdGroupProductPartition);

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

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

对于 Ad Group Hotel 一览组 记录，批量文件架构中提供了以下属性字段。

广告组
竞价
出价百分比
市场活动
客户端 ID
自定义参数
最终 URL 后缀
Id
排除
修改时间
父条件 ID
父 ID
Hotel 属性
Hotel 属性值
状态
子类型
跟踪模板

广告组

包含酒店一览组的广告组的名称。

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

注意

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

竞价

拍卖中要出价的金额。当市场活动出价方案为 ManualCpc 时，将使用此方案。

添加： 如果 “排除” 为 false 且子类型为 “单位”，则为必需项，否则不允许出价。
更新： 选。如果未为更新设置任何值，则不会更改此设置。
删除： 只读

出价百分比

拍卖中要出价的金额。当市场活动竞价方案为 PercentCpc 或佣金时，将使用此方案。

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) 删除以前的设置。若要删除自定义参数的子集，请指定要保留的自定义参数，并省略任何不想保留的参数。新的自定义参数集将替换以前的任何自定义参数集。
删除： 只读

最终 URL 后缀

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

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

Id

酒店列表组的系统生成的标识符。

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

排除

确定酒店列表组是表示可投标还是负面标准。

如果设置为 true ，则为负标准，否则为可出价条件。

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

修改时间

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

注意

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

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

父条件 ID

父酒店列表组的条件标识符。

此批量字段映射到 ParentNodeId ，并且必须为 null 才能指向根节点。

注意

此字段不适用于树根酒店列表组节点，该节点没有父级。

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

父 ID

包含酒店一览组的广告组的系统生成的标识符。

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

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

注意

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

Hotel 属性

条件的操作数。操作数隐式包含相等运算符。例如，可以将 Brand 读取为 Brand=。

使用 Hotel 属性作为 Hotel 属性值的操作数。

可以为每个市场活动和广告组指定多个酒店属性。如果酒店的属性值等于操作数的属性值，则满足每个条件。例如，如果操作数设置为 Brand，而属性设置为 Contoso，则如果酒店目录的 Brand 属性的值等于 Contoso，则满足条件。

在市场活动中，可以在市场活动级别和广告组级别设置酒店属性。下表描述了酒店属性 (操作数) 和酒店属性值 (属性) 广告组列表组记录的业务规则。

注意

如果对于根节点，酒店值设置为 null 或空，则 Hotel 属性必须为“All”。

Hotel Attribute (Operand)	Hotel 属性值 (属性) 说明	广告组酒店列表组规则
全部	不适用。	对于广告组的酒店列表组，根节点的操作数必须设置为“All”，并将属性设置为 null 或空。
品牌	酒店的制造商、品牌或发布者。最多 200 个字符。	Brand 操作数可以在多个分支中使用，但每个分支只能指定一次。
类别	酒店类别，例如“Inn”、“Motel”、“Resort”等。最多 200 个字符。	不适用。
市/县	酒店所在的城市。	不适用。
国家/地区	酒店所在的国家或地区。	不适用。
CustomLabel0-4 提供五个自定义标签操作数值，即 CustomLabel0、CustomLabel1、CustomLabel2、CustomLabel3 和 CustomLabel4。	每个 CustomLabel 操作数都可以在多个分支中使用，但每个分支只能指定一次。例如，一个分支可能包含 CustomLabel0 和 CustomLabel1，但不能包含具有 CustomLabel1 操作数的另一个节点。最多 200 个字符。	不适用。
HotelId	酒店标识符。最多 1,024 个字符。	ID 操作数可以在多个分支中使用，但每个分支只能指定一次。
StarRating	1-5 星的酒店评级。	不适用。
状态	酒店所在的状态。	不适用。

添加： 必填
更新： 只读。不能更新条件或值字段。若要更新条件，必须删除酒店列表组并添加新组。
删除： 只读

Hotel 属性值

条件的属性值。

添加： 必填
更新： 只读。不能更新条件或值字段。若要更新条件，必须删除酒店列表组并添加新组。
删除： 只读

状态

酒店列表组的状态。

可能的值为 Active 或 Deleted。

添加： 选。唯一可能的状态是 “活动”。如果将状态设置为 “已删除” ，则会忽略它，并且返回的记录的状态将设置为 “活动”。
更新： 选
删除： 必填。 “状态”必须设置为 “已删除”。

子类型

酒店列表组的类型。

可能的值为 Subdivision 和 Unit。