Ad 组产品分区记录 - 批量

项目
11/14/2024

定义可在批量文件中上传和下载的广告组产品分区。

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

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

提示

有关Microsoft购物市场活动的概述和详细信息，请参阅产品广告和智能购物市场活动技术指南。

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

如果提供了有效的父 ID 值，下面的批量 CSV 示例将添加新的广告组产品分区。

Type,Status,Id,Parent Id,Sub Type,Campaign,Ad Group,Client Id,Modified Time,Bid,Name,Product Condition 1,Product Value 1,Is Excluded,Parent Criterion Id,Tracking Template,Final Url Suffix,Custom Parameter
Format Version,,,,,,,,,,6.0,,,,,,,
Ad Group Product Partition,Paused,,-1112,,,,ClientIdGoesHere,,0.5,,All,,FALSE,,,,{_promoCode}=PROMO1; {_season}=summer

如果使用用于 .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 ProductPartition { 
            Condition = new ProductCondition
            {
                // 'Product Value 1' column header in the Bulk file
                Attribute = null,
                // 'Product Condition 1' 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
        },
        // 'Destination Url' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
        DestinationUrl = null,
        // '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();

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

广告组
竞价
出价调整
市场活动
客户端 ID
自定义参数
目标 URL
最终 URL 后缀
Id
排除
修改时间
父条件 ID
父 ID
产品条件 1
产品价值 1
状态
子类型
跟踪模板

广告组

包含产品分区的广告组的名称。

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

注意

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

竞价

拍卖中要出价的金额。

注意

对于为赞助产品设置Microsoft购物市场活动中的广告组，如果广告组的 “出价选项” 设置为 BidBoost，则此字段不适用。有关详细信息，请参阅出价调整。

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

出价调整

百分比 (大于零) ，这允许你的赞助产品出价灵活。

例如，假设合作伙伴通过“ 出价”字段) (在其产品组中出价 5 美元。如果你的出价调整 (此字段) 设置为 20 (%) ，并且广告组的最大出价为 0.50 (50 美分) ，则你的份额将是 50 美分，而不是 1 美元。

仅当广告组的 “出价选项 ”设置为 BidBoost 时，此字段才适用。如果广告组的出价选项设置为 BidValue，则拍卖将使用产品组的出价。

支持的值为负 90 (-90) 到正 900 (900) 。

注意

此设置仅适用于为赞助产品设置Microsoft购物市场活动中的广告组。赞助产品仅在美国中提供，目前处于开放 beta 阶段。

加：自选。如果未包括，则出价调整将设置为默认值 0 。
更新： 必填
删除： 只读

Campaign

包含广告组和产品分区的市场活动的名称。

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

客户端 ID

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

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

自定义参数

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

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

将每个自定义参数对的格式设置为 Key=Value，例如 {_promoCode}=PROMO1。
Microsoft广告将接受包含的前 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 跟踪。

URL 可以包含动态参数，例如 {MatchType}。有关支持的参数列表，请参阅Microsoft广告帮助文章我可以使用哪些跟踪或 URL 参数？。

URL 最多可以包含 1,024 个字符。如果 URL 未指定协议，则当用户单击广告时，系统会使用 HTTP 协议。如果在添加广告时 URL 指定了 HTTP 协议，则服务将删除 http:// 协议字符串， (HTTP 协议字符串不计入 1,024 个字符限制) ;但是，该服务不会从 URL 中删除 HTTPS 协议字符串 (https：//) 。

注意

如果指定，则使用此目标 URL;否则，目标 URL 由你在 Microsoft 商家中心目录中为产品/服务指定的“链接”的相应值确定。

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

最终 URL 后缀

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

Id

产品分区的系统生成的标识符。

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

排除

确定产品分区是表示可出价还是负面标准。

如果设置为 TRUE ，则为负标准，否则为 FALSE ，则为可投标条件。

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

修改时间

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

注意

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

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

父条件 ID

父产品分区的条件标识符。

注意

此字段不适用于没有父级的树根产品分区节点。

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

父 ID

包含产品分区的广告组的系统生成的标识符。

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

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

注意

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

产品条件 1

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

使用产品条件 1 作为产品值 1 的操作数。

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

在购物市场活动中，可以在市场活动级别和广告组级别设置产品条件。下表描述了市场活动产品范围和广告组产品分区记录) 业务规则 (操作数) 和产品价值 (属性。

产品条件 (操作数)	产品价值 (属性) 说明	市场活动产品范围规则	广告组产品分区规则
全部	必须为 null。	不适用。	对于广告组的产品分区，根节点的操作数必须设置为“All”，并将属性设置为 null 或空。
品牌	产品的制造商、品牌或发布者。最多 1,000 个字符。	每个市场活动产品范围筛选器只能指定一次品牌操作数。	Brand 操作数可以在多个分支中使用，但每个分支只能指定一次。
CategoryL1-5 有五个类别操作数值可用，即 CategoryL1、CategoryL2、CategoryL3、CategoryL4 和 CategoryL5。	由Microsoft商家中心商店定义的产品类别。 CategoryL0 是最高级别的类别，CategoryL4 是最低级别或最精细的类别。最多 100 个字符。	每个 CategoryL 操作数可按市场活动产品范围筛选器使用一次。如果指定将操作数设置为 1 到 5 的产品类别的产品条件，它们必须按升序进行指定。例如，如果前面的产品条件的操作数为“CategoryL1”且属性为“Animals & 宠物用品”，则可以将操作数设置为“CategoryL2”。	每个 CategoryL 操作数都可以在多个分支中使用，但每个分支只能指定一次。例如，一个分支可能包含 CategoryL1 和 CategoryL2，但不能包含具有 CategoryL2 操作数的另一个节点。如果将操作数设置为从 1 到 5 的产品类别，则必须按升序指定它们。例如，如果高级产品分区的操作数为“CategoryL1”且属性为“Animals & 宠物用品”，则可以将操作数设置为“CategoryL2”。无需在直接父分区中指定以前的级别产品类别操作数。例如，如果父分区的父级指定 CategoryL1 条件，则可为其分区指定 CategoryL2 条件。
频道	本地库存广告 (LIA) 频道。可能的值包括“本地存储”和“Online”。如果市场活动尚未选择加入本地库存广告，则默认情况下所有产品/服务仅联机 (Channel=Online) 和单通道 (ChannelExclusivity=单通道) 。有关详细信息，请参阅本地库存广告帮助页。	每个市场活动产品范围筛选器只能指定一次通道操作数。	通道操作数可以在多个分支中使用，但每个分支只能指定一次。
ChannelExclusivity	本地库存广告 (LIA) 频道排他性。可能的值包括“单通道”和“多通道”。如果市场活动尚未选择加入本地库存广告，则默认情况下所有产品/服务仅联机 (Channel=Online) 和单通道 (ChannelExclusivity=单通道) 。有关详细信息，请参阅本地库存广告帮助页。	每个市场活动产品范围筛选器只能指定一次 ChannelExclusivity 操作数。	ChannelExclusivity 操作数可以在多个分支中使用，但每个分支只能指定一次。
条件	产品的条件。如果操作数设置为 Condition，则可以指定的支持属性值为 New、 Used 和 Refurbished。	每个市场活动产品范围筛选器只能指定一次条件操作数。	Condition 操作数可以在多个分支中使用，但每个分支只能指定一次。
CustomLabel0-4 提供五个自定义标签操作数值，即 CustomLabel0、CustomLabel1、CustomLabel2、CustomLabel3 和 CustomLabel4。	由商家定义的自定义标签。自定义标签（例如 CustomLabel0 和 CustomLabel4）不会基于任何层次结构进行验证。最多 100 个字符。此操作数不适用于赞助产品。	每个 CustomLabel 操作数可以为每个市场活动产品范围筛选器使用一次。	每个 CustomLabel 操作数都可以在多个分支中使用，但每个分支只能指定一次。例如，一个分支可能包含 CustomLabel0 和 CustomLabel1，但不能包含具有 CustomLabel1 操作数的另一个节点。
GTIN	商家定义的全球贸易项编号。 GTIN 字段限制为 50 个字符，每个 GTIN 值最多包含 14 位数字。此操作数仅适用于赞助产品。	每个市场活动产品范围筛选器只能指定一次 GTIN 操作数。	GTIN 操作数可以在多个分支中使用，但每个分支只能指定一次。
Id	商家定义的产品标识符。最多 1,000 个字符。	每个市场活动产品范围筛选器只能指定 ID 操作数一次。	ID 操作数可以在多个分支中使用，但每个分支只能指定一次。
MPN	商家定义的全球贸易项编号。最多 70 个字符。此操作数仅适用于赞助产品。	每个市场活动产品范围筛选器只能指定 MPN 操作数一次。	MPN 操作数可以在多个分支中使用，但每个分支只能指定一次。
ProductType1-5 提供五个产品类型操作数值，即 ProductType1、ProductType2、ProductType3、ProductType4 和 ProductType5。	商家定义的产品类型或类别。 ProductType1 是最高级别的产品类型，ProductType5 是最低级别或最精细的产品类型。最多 100 个字符。此操作数不适用于赞助产品。	每个产品类型操作数可以按市场活动产品范围筛选器使用一次。如果指定将操作数设置为 1 到 5 的产品类型的产品条件，它们必须按升序进行指定。例如，如果前面的产品条件的操作数“ProductType1”具有属性“Animals & Pet Supplies”，则可以将操作数设置为“ProductType2”。	每个 ProductType 操作数都可以在多个分支中使用，但每个分支只能指定一次。例如，一个分支可能包含 ProductType1 和 ProductType2，但不能包含具有 ProductType2 操作数的另一个节点。如果将操作数设置为从 1 到 5 的产品类型，则必须按升序指定它们。例如，如果较高级别的产品分区的操作数为“ProductType1”且属性为“Animals & Pet Supplies”，则可以将操作数设置为“ProductType2”。无需在直接父分区中指定以前的级别产品类型操作数。例如，如果父级的父级指定了 ProductType1 条件，则可为其分区指定 ProductType2 条件。

加：必填
更新： 只读。不能更新条件或值字段。若要更新条件，必须删除产品分区并添加新分区。
删除： 只读

产品价值 1

条件的属性值。

属性的值必须与客户的 Microsoft 商家中心目录文件中指定的值完全匹配。

加：必填
更新： 只读。不能更新条件或值字段。若要更新条件，必须删除产品分区并添加新分区。
删除： 只读

状态

产品分区的状态。

可能的值为 Active 或 Deleted。

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

子类型

产品分区的类型。

可能的值为 Subdivision 和 Unit。