批量文件架构
批量架构使用批量 API 定义要下载或上传的文件的内容。 对于下载和上传，大容量服务支持 DownloadEntity 值集中的文件类型和相应的架构。
有关使用批量服务管理市场活动的详细信息，请参阅 批量下载和上传。 有关了解数据文件内容的详细信息，请参阅以下部分。
文件架构
可以选择下载制表符或逗号分隔的记录集， (行) 和字段 (列) 。 第一列标题名为 Type。 其余列名称映射到相应记录类型内或关联的属性。
重要
可以随时添加) (行) 和字段 (列，不应依赖于批量下载或批量上传结果文件中的记录或字段顺序。 同样，除非参考文档中另有说明，否则不应依赖于每个字段中返回的一组固定值。
同样，在上传过程中，可以按任意顺序提交字段。 创建新实体时，上传记录顺序非常重要，如下 文类型层次结构中所述。
设置版本格式
批量格式版本与必应广告 API 版本分开。 格式版本支持灵活的升级路径，以采用最新的受支持功能，而不会中断应用程序。 最佳做法应始终升级到最新的格式版本。 目前唯一受支持的格式版本是 6.0。
若要使用批量下载指定文件格式版本，请在 DownloadCampaignsByAccountIds 或 DownloadCampaignsByCampaignIds 请求中将 FormatVersion 设置为 6.0。
若要使用批量上传指定版本，请将“格式版本记录”的“名称”字段设置为 6.0。
记录类型
下表详细说明了可以使用 格式版本 6.0 进行上传和下载的记录。
重要
可以随时添加) (行) 和字段 (列，不应依赖于批量下载或批量上传结果文件中的记录或字段顺序。
类型层次结构
下载文件将始终包含 格式版本 和 帐户 记录类型的记录。 对于上传， 格式版本 是必需的，并且必须在批量文件中的所有其他记录类型之前。
如果父实体是在同一文件中创建的，则它应位于批量文件中的任何依赖子记录之前。 例如，如下图所示，将网站链接广告扩展与市场活动关联时， 市场活动站点链接广告扩展 记录必须包含在 市场活动 记录和 Sitelink 广告扩展 记录之后的文件中。 市场活动站点链接广告扩展记录的 Id 和父 ID 字段应分别设置为 Sitelink Ad Extension 和 Campaign 记录的标识符。 如果 Sitelink 广告扩展 和 市场活动 记录也是新的，并且尚未分配Microsoft广告标识符，则应使用 引用密钥。
无需包含已分配有效Microsoft广告标识符的父实体的记录。
添加、更新和删除批量文件记录时，支持部分成功。 例如，如果尝试添加三个市场活动，并且文件中只正确指定了两个市场活动，则会添加两个市场活动。 结果文件将包括成功的 市场活动 记录、一条尝试 的市场活动 记录和一条 市场活动错误 记录的详细信息。
如果新的市场活动标识符尚不为人知（例如，在同一文件中添加市场活动、广告组、文本广告和关键字 (keyword) 时），请将市场活动名称指定为任何子记录的逻辑引用键。 无需在上传中指定现有父级。
批量记录支持部分更新，包括负面关键字、负面网站和目标条件。 例如，可以更新单个位置条件的出价，并且无需下载并上传市场活动或广告组的整个目标条件集。
更新记录时，需要更新记录的 ID 字段。 父记录的 父 ID 或 引用键 也是必需的。
更新市场活动或广告组名称时，如果提供了正确的 父 ID ，则为子记录指定新名称是可选的。
如果要将一组记录替换为另一组记录，则必须在新集之前指定已删除的记录。 例如，若要替换给定市场活动的所有现有市场活动负面关键字，首先将“状态”设置为“已删除”和“父 ID”设置为市场活动 ID 的“市场活动负面关键字”。 如果未指定任何 ID，即不要尝试删除特定的 camapaign 负关键字 (keyword) ，这将有效地删除该市场活动的所有市场活动负面关键字。 在“全部删除”记录下，可以包含一个或多个新的 市场活动负关键字 记录，其中包含上传添加操作所需的所有属性。
如果要将现有记录替换为具有相同唯一属性的新记录，则必须在新记录之前指定已删除的记录。 例如，若要替换给定广告组的现有广告组动态搜索广告目标，请首先包括一个“状态”设置为“已删除”的广告组动态搜索广告目标，将 Id 设置为现有动态广告目标 (网页条件) ID，并将“父 ID”设置为广告组 ID。 在已删除的记录下方，可以包含新的 广告组动态搜索广告目标 记录， (大概包含新的网页条件) 。
注意
在大多数情况下，可以更新现有记录，而不是提交单独的删除和添加记录，例如，可以更新现有市场活动性别准则的“出价调整”字段。
删除记录时，需要 ID 字段。 还需要对父实体的引用，无论该值是Microsoft播发分配的系统标识符还是父记录的 引用键 。 例如，删除广告组时，广告组记录的“父 ID”字段应与市场活动记录中的“Id”字段匹配，或者广告组记录的“市场活动”字段应与市场活动记录中的“市场活动”字段匹配。 如果同时提供两者，则忽略“广告组记录 (引用密钥) 的父 ID 字段。
除了少数例外，结果文件将仅包含已上传的列。 例如，如果上传不带 Id 列标题的新广告组 Negative Keyword，则结果文件将不包括为新的负关键字 (keyword) 分配的标识符。 大容量文件应包含 ID 列;但是，对于每个新的广告组负关键字，应将 ID 留空。 此规则的例外情况是市场活动、广告组、广告和关键字，在这种情况下，结果文件将包含所有列，而不考虑上传的列。
使用 delete_value 进行更新
若要删除现有设置，不应将空字符串 (“”) 写入 Bulk 文件，因为批量服务会忽略此类字符串。 使用保留的“delete_value”字符串删除或重置可选字段的值。
- 如果在可选字段中使用保留的“delete_value”字符串，则会删除以前的设置。 例如，如果将广告组记录的“自定义参数”字段设置为“delete_value”，则会从广告组中删除所有以前的自定义参数。 同样，如果将广告组记录的“跟踪模板”字段设置为“delete_value”，则会从广告组中删除以前的跟踪模板。
- 适用于 .NET、Java 和 Python 的必应广告 SDK 会自动编写“delete_value（如果适用）。 有关详细信息，请参阅批量Service Manager - 使用delete_value进行更新。
如果在必填字段中使用“delete_value”，请注意以下事项。
- 如果使用保留的“delete_value”字符串来代替所需的基元值，则会忽略它。 尽管字段未更新，但“delete_value”字符串将通过上传结果文件传递。 例如，如果将 “广告组 ”字段 (广告组名称) 广告组 记录设置为“delete_value”，则不会更新广告组的名称。
- 如果使用保留的“delete_value”字符串来代替所需的值集，则字段将更新为默认值，结果文件将反映该更改。 例如，如果将广告组记录的“网络分发”字段设置为“delete_value”，则广告组的网络分发将设置为 OwnedAndOperatedAndSyndicatedSearch，上传结果文件将反映相同的情况。
引用键
当引用尚未分配Microsoft广告标识符的大容量文件中前面的记录时，可以根据记录类型使用逻辑引用键或负引用键。
注意
如果父实体是在同一文件中创建的，则它应位于大容量文件中的任何依赖子记录之前。
负引用键
引用尚未分配Microsoft广告标识符的大容量文件中的上一条记录时，可以将扩展的 ID 字段设置为所选的负数。 此自定义 ID 称为负引用键。 然后，可以在依赖记录的 “ID” 字段中使用负引用键。
第一个示例演示如何为新的市场活动创建广告组。 将广告组记录中的“父 ID”字段设置为市场活动 (-111) 的负引用键。 如果要在应将广告组作为父 (（例如关键字或广告组标注广告扩展) ）的同一文件中添加其他记录，则还应该将广告组中的 Id 字段设置为负值，例如可从子记录引用的 -1111。
| 类型 | Id | 父 ID |
|---|---|---|
| Campaign | -111 | |
| 广告组 | -1111 | -111 |
第二个示例演示如何为新市场活动和新标注广告扩展创建市场活动标注广告扩展。 该示例还演示如何为新的广告组和另一个新的标注广告扩展创建广告组标注广告扩展。
- 将市场活动标注广告扩展记录中的父 ID 字段设置为市场活动 (-111) 的负引用键，并将市场活动标注广告扩展记录中的 Id 字段设置为标注广告扩展 (-11) 的负引用键。
- 将“广告组标注广告扩展”记录中的“父 ID”字段设置为广告组 (-1111) 的负引用键，并将广告组标注广告扩展记录中的 Id 字段设置为标注广告扩展 (-12) 的负引用键。
| 类型 | Id | 父 ID |
|---|---|---|
| 标注广告扩展 | -11 | |
| 标注广告扩展 | -12 | |
| Campaign | -111 | |
| 广告组 | -1111 | -111 |
| 市场活动标注广告扩展 | -11 | -111 |
| 广告组标注广告扩展 | -12 | -1111 |
逻辑引用键
引用新的 市场活动 或 广告组 记录时，可以使用市场活动和广告组名称，而不是将 父 ID 字段设置为子记录中的 负引用键 。 例如，若要向新市场活动添加新广告组，并向新广告组添加新关键字 (keyword) ，请在子记录中设置“市场活动”和“广告组”字段，如以下示例所示。
| 类型 | Campaign | 广告组 |
|---|---|---|
| Campaign | 女鞋 | |
| 广告组 | 女鞋 | 女子红鞋销售 |
客户端标识符
客户端标识符可用于将批量上传文件中的输入记录与结果文件中的输出记录相关联。 例如，添加新记录时，可以将 “客户端 ID” 字段设置为所选的字符串值。 Microsoft广告系统不对客户端标识符进行任何修改，并将它们传递给相应记录的结果文件。
错误
批量下载文件或批量上传结果文件可能包含相应 类型 字段包含错误后缀的记录。 例如， 产品广告错误 记录类型表示产品广告错误。 “ 错误” 和 “错误编号 ”列将包含有关错误的详细信息。
注意
上传结果文件可能包含对应于一条上传记录的多个错误记录。
与新功能（例如“最终 URL”）相关的错误将包括有关 错误在“字段路径” 列中发生位置的其他详细信息。 每个字段路径名称对应于 市场活动管理服务 数据对象之一的元素。 例如，如果市场活动记录的“跟踪模板”字段不以 http:// 或 https://、{lpurl} 或 {unescapedlpurl} 开头，则此字段路径值的值是 TrackingTemplate。 TrackingUrlTemplate 是市场活动管理服务中可用的市场活动数据对象的元素。
| 类型 | 跟踪模板 | 错误 | Error Number | 字段路径 |
|---|---|---|---|---|
| 市场活动错误 | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | InvalidUrlScheme | 4600 | TrackingTemplate |
| 市场活动错误 | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | CampaignServiceInvalidUrl | 2611 | TrackingTemplate |
重要
字段路径值可能会更改，因此不应依赖当前字符串格式。 并非所有错误都支持 字段路径 。 它支持相应的市场活动、广告组、扩展文本广告、产品广告、广告组产品分区、关键字和 Sitelink 广告扩展记录的移动最终 URL、最终 URL、跟踪模板和自定义参数字段。 还支持与 标注广告扩展 和 查看广告扩展 记录的所有字段相关的错误。
如果问题与编辑错误相关，则 “编辑位置”、“ 编辑术语”、“ 编辑原因代码”和 “发布者国家/地区 ”列也可能包含有关错误的详细信息。