源记录 - 批量

项目
11/13/2024

定义可在批量文件中下载和上传的源。

提示

有关如何使用源和源项的概述，请参阅广告定制器源、自动库存源和页面源技术指南。

注意

在 2023 年 2 月 1 日之前，将展开的文本广告升级到响应式搜索广告。在此日期之后，你将无法再创建新的或编辑现有的扩展文本广告。有关详细信息，请参阅关于响应式搜索广告。
计划的源将继续运行，使用广告定制器源的现有扩展文本广告将继续提供。你将能够查看其性能报告。
你仍然可以暂停、运行或删除现有的广告定制器源。否则，尝试为展开的文本广告创建或编辑现有广告定制器将导致 CustomerNotEligibleForAdCustomizersFeed 错误。
详细了解此更改。

如果要在同一大容量文件中创建新的父实体和子实体，则必须根据层次结构在依赖项之后包括依赖记录：

每个帐户可以有 100 个源， (此最大数量包括) 的所有源类型，每个帐户) (行的最大源项数为 500 万。

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

以下批量 CSV 示例将添加一个新的页面源、自动清单和广告定制器源，每个源都有一个源项。

Type,Status,Id,Parent Id,Sub Type,Campaign,Ad Group,Client Id,Modified Time,Start Date,End Date,Device Preference,Keyword,Match Type,Target,Physical Intent,Name,Ad Schedule,Audience Id,Feed Name,Custom Attributes
Format Version,,,,,,,,,,,,,,,,6,,,,
Feed,Active,-20,,PageFeed,,,PageFeedClientIdGoesHere,,,,,,,,,,,,MyPageFeedName,"[{""name"":""Page Url"",""feedAttributeType"":""Url"",""isPartOfKey"":true},{""name"":""Custom Label"",""feedAttributeType"":""StringList""},{""name"":""Ad Title"",""feedAttributeType"":""String""}]"
Feed,Active,-21,,AdCustomizerFeed,,,AdCustomizerFeedClientIdGoesHere,,,,,,,,,,,,MyAdCustomizerFeedName,"[{""name"":""DateTimeName"",""feedAttributeType"":""DateTime""},{""name"":""Int64Name"",""feedAttributeType"":""Int64""},{""name"":""PriceName"",""feedAttributeType"":""Price""},{""name"":""StringName"",""feedAttributeType"":""String"",""isPartOfKey"":true}]"
Feed,Active,123456789,DynamicDataAutoListingFeedNew,CampaignName,AUTO ad group,-21,,DynamicDataAutosListingFeed,,"[{""name"":""Vehicle ID""},{""name"":""Final URL""},{""name"":""Image URL""},{""name"":""Make""},{""name"":""Model""},{""name"":""Price""},{""name"":""Title""},{""name"":""Target campaign""},{""name"":""Target ad group""},{""name"":""Latitude""},{""name"":""Longitude""},{""name"":""Mileage value""},{""name"":""Mileage unit""},{""name"":""Year""},{""name"":""Fuel type""},{""name"":""Transmission""},{""name"":""City""},{""name"":""VIN""},{""name"":""State of vehicle""}]"
Feed Item,Active,123456789,DynamicDataAutoListingFeedNew,CampaignName,AUTO ad group,,-21,,,"{""Vehicle Id"":""2g161290-1d13"",""""Final Url"""":""https:\/\/www.contoso.com\/used-Redmond1"",""Image Urls"":""https:\/\/www.contoso.com\/inventoryphotos\/01.jpg;https:\/\/www.contoso.com\/inventoryphotos\/02.jpg"",""Make"":""Contoso"",""Model"":""SUV"",""Price"":""65495.00 USD"",""Title"":""2020 SUV"",""Target campaign"":""CampaignName"",""Target ad group"":"""",""Latitude"":"""",""Logitude"":"""",""Mileage Value"":""13000"",""Mileage Unit"":""MI"",""Year"":""2020"",""Fuel Type"":"""",""Transmission"":"""",""City"":""Redmond"",""Vin"":""SALLJGML8HA004044"",""State of Vehicle"":""USED"",""Trim"":""HSE""}"
Feed Item,Active,-200,-20,,,,20;200,,2020/06/22 00:00:00,2020/06/30 00:00:00,,,,,,,,,,"{""Page Url"":""https://contoso.com/3001"",""Custom Label"":[""Label_1_3001"",""Label_2_3001""],""Ad Title"":""An ad title""}"
Feed Item,Active,-210,-21,,,,21;210,,2020/06/22 00:00:00,2020/06/30 00:00:00,,value,Broad,,PeopleIn,,(Sunday[09:00-17:00]),,,"{""DateTimeName"":""2020/06/22 00:00:00"",""Int64Name"":237601,""PriceName"":""$601"",""StringName"":""s237601""}"

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkFeed
var bulkAdCustomizerFeed = new BulkFeed
{
    // 'Parent Id' column header in the Bulk file
	AccountId = 0,

	// 'Custom Attributes' column header in the Bulk file
	CustomAttributes = new[]
	{
		// Each FeedCustomAttributeContract is represented as a JSON list item in the Bulk file.
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "DateTime",
			Name = "DateTimeName"
		},
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "Int64",
			Name = "Int64Name"
		},
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "Price",
			Name = "PriceName"
		},
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "String",
			Name = "StringName",
			IsPartOfKey = true
		}
	},

	// 'Id' column header in the Bulk file
	Id = adCustomizerFeedIdKey,
	// 'Feed Name' column header in the Bulk file
	Name = "My AdCustomizerFeed " + DateTime.UtcNow,
	// 'Sub Type' column header in the Bulk file
	SubType = "AdCustomizerFeed",
	// 'Client Id' column header in the Bulk file
	ClientId = "ClientIdGoesHere",
	// 'Status' column header in the Bulk file
	Status = Status.Active
};

uploadEntities.Add(bulkAdCustomizerFeed);

// Map properties in the Bulk file to the BulkFeed
var bulkPageFeed = new BulkFeed
{
	// 'Parent Id' column header in the Bulk file
	AccountId = 0,

	// 'Custom Attributes' column header in the Bulk file
	CustomAttributes = new []
	{
		// Each FeedCustomAttributeContract is represented as a JSON list item in the Bulk file.
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "Url",
			Name = "Page Url"
		},
		new FeedCustomAttributeContract
		{
			FeedAttributeType = "StringList",
			Name = "Custom Label"
		}
	},
	
	// 'Id' column header in the Bulk file
	Id = pageFeedIdKey,                    
	// 'Feed Name' column header in the Bulk file
	Name = "My PageFeed " + DateTime.UtcNow,
	// 'Sub Type' column header in the Bulk file
	SubType = "PageFeed",
	// 'Client Id' column header in the Bulk file
	ClientId = "ClientIdGoesHere",
	// 'Status' column header in the Bulk file
	Status = Status.Active
};

uploadEntities.Add(bulkPageFeed);

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

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

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

客户端 ID
自定义属性
源名称
Id
修改时间
父 ID
状态
子类型

客户端 ID

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

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

自定义属性

属性针对每个源子类型进行自定义，并定义要插入广告中的产品或服务的相关信息。

对于 AdCustomizerFeed 子类型，每个源项最多可以包含 100 个自定义属性，其中每个自定义属性名称都是唯一的。

对于 DynamicDataAutosListingFeed 子类型，每个源项最多可以包含 100 个自定义属性，其中每个自定义属性名称都是唯一的。

对于 PageFeed 子类型，可以为每个源项包含一个或两个自定义属性，其中每个自定义属性名称都是唯一的。

自定义属性在批量文件中以 JSON 字符串的形式表示。有关详细信息，请参阅 feedAttributeType、 isPartOfKey 和下面的名称。

下面是可以为页面源上传的示例自定义属性。

注意

在逗号分隔的大容量文件中，需要用一组额外的双引号将属性、每个属性键和每个属性值括起来，上述 JSON 字符串将编写为“[{”name“”：“”Page Url“”，“”feedAttributeType“”：“”Url“”，“”isPartOfKey“”：true}，{“”name“：：”“自定义标签”“，”“feedAttributeType”“”：“”StringList“”}，{“”name“”：“”Ad Title“”，“”feedAttributeType“”“：”“String”“}]”。

[
	{
		"name": "Page Url",
		"feedAttributeType": "Url",
		"isPartOfKey": true
	},
	{
		"name": "Custom Label",
		"feedAttributeType": "StringList"
	},
	{
		"name": "Ad Title",
		"feedAttributeType": "String"
	}
]

添加： 必填。对于广告定制器和 DynamicDataAutosListing 源，必须至少设置一个具有 name 和 feedAttributeType 键的属性。对于页面源，必须至少设置一个名称设置为“页面 URL”的属性。仅使用名称 feedAttributeType 和 isPartOfKey 键。
更新： 选。创建源后，无法删除自定义属性。可以通过仅上传新属性来添加新的自定义属性，即不要包含具有新属性的现有属性。如果包含具有新属性的现有属性，则会返回错误。如果将此字段留空或上传现有属性的确切副本，且未进行任何修改，则不会进行任何更改。
删除： 只读

feedAttributeType

每个自定义属性的数据类型。在源记录中定义数据类型，然后在源项中设置值。只要每个自定义属性名称在源中是唯一的，就可以定义具有相同数据类型的多个属性。

可以为广告定制器源设置四种不同的 feedAttributeType 数据类型：

feedAttributeType	用例	接受的源项值
String	产品名称、产品类别、说明	任何字母、数字或符号
Int64	库存计数，可用颜色数	任何整数
价格	产品成本，销售折扣	任何数字 (包括小数) 和有效货币字符
日期时间	活动开始时间，销售的最后一天	yyyy/mm/dd HH：mm：ss 若要在一天开始时默认为午夜，可以省略 HH：mm：ss 部分。

例如，我们可以定义广告定制器源的自定义属性。

[
	{
		"name": "DateTimeName",
		"feedAttributeType": "DateTime"
	},
	{
		"name": "Int64Name",
		"feedAttributeType": "Int64"
	},
	{
		"name": "PriceName",
		"feedAttributeType": "Price"
	},
	{
		"name": "StringName",
		"feedAttributeType": "String",
		"isPartOfKey": true
	}
]

然后，我们可以映射源项上传中的每个源名称，即“DateTimeName”、“Int64Name”、“PriceName”和“StringName”：

{
	"DateTimeName": "2020/06/22 00:00:00",
	"Int64Name": 237601,
	"PriceName": "$601",
	"StringName": "s237601"
}

可以为 DynamicDataAutosListing 源设置六种不同的 feedAttributeType 数据类型：

feedAttributeType	用例	接受的源项值
String	车辆名称、车辆类别、说明	任何字母、数字或符号
Int64	车辆年份，引擎	任何整数
价格	车辆成本、销售折扣	任何数字 (包括小数) 和有效货币字符
日期时间	活动开始时间，销售的最后一天	yyyy/mm/dd HH：mm：ss 若要在一天开始时默认为午夜，可以省略 HH：mm：ss 部分。
URL	包含要包含在源中的网站的 URL。	必须为每个源项包含一个 URL。
StringList	允许对源中的 URL 进行分组的标签。	每个源项可以包含 1 到 10 个自定义标签。每个自定义标签都以 JSON 表示法表示为列表项。例如，源项的自定义标签部分可以编写为 “”自定义标签“”：[“”Label_1_3001“”，“”Label_2_3001“]]

例如，我们可以定义 DynamicDataAutosListing 源的自定义属性。

[
	{
		"name": "DateTimeName",
		"feedAttributeType": "DateTime"
	},
	{
		"name": "Int64Name",
		"feedAttributeType": "Int64"
	},
	{
		"name": "PriceName",
		"feedAttributeType": "Price"
	},
	{
		"name": "StringName",
		"feedAttributeType": "String",
		"isPartOfKey": true
	},
	{
		"name": "Page Url",
		"feedAttributeType": "Url",
		"isPartOfKey": true
	},
	{
		"name": "Custom Label",
		"feedAttributeType": "StringList"
	}
]

然后，我们可以映射源项上传中的每个源名称，即“DateTimeName”、“Int64Name”、“PriceName”和“StringName”：

{
	"DateTimeName": "2020/06/22 00:00:00",
	"Int64Name": 237601,
	"PriceName": "$601",
	"StringName": "s237601",
	"Page Url": "https://contoso.com/3001",
	"Custom Label": [
		"Label_1_3001",
		"Label_2_3001"
	],
}

以下是 feedAttributeType 可以为页面源设置的数据类型：

feedAttributeType	用例	接受的源项值
String	显示的静态标题，而不是动态生成的标题。	任何最多 63 个字符的字母、数字或符号。每个源项可以包含一个广告标题。
StringList	允许对源中的 URL 进行分组的标签。	每个源项可以包含 1 到 10 个自定义标签。每个自定义标签都以 JSON 表示法表示为列表项。例如，源项的自定义标签部分可以编写为 “”自定义标签“”：[“”Label_1_3001“”，“”Label_2_3001“]]
URL	包含要包含在源中的网站的 URL。	必须为每个源项包含一个 URL。

例如，我们可以定义页面源的自定义属性。

注意

对于页面源，是 feedAttributeType 可选的。如果设置 feedAttributeType，则必须将“页面 Url”设置为“Url”，将“StringList”设置为“自定义标签”，并将“Ad Title” 命名属性设置为“String”。

[
	{
		"name": "Page Url",
		"feedAttributeType": "Url",
		"isPartOfKey": true
	},
	{
		"name": "Custom Label",
		"feedAttributeType": "StringList"
	},
	{
		"name": "Ad Title",
		"feedAttributeType": "String"
	}
]

然后，我们可以映射每个源名称，即源项上传中的“页面 URL”、“自定义标签”和“广告标题”：

{
	"Page Url": "https://contoso.com/3001",
	"Custom Label": [
		"Label_1_3001",
		"Label_2_3001"
	],
    "Ad Title": "Find New Customers & Increase Sales!",
}

isPartOfKey

确定 isPartOfKey 自定义属性的值在汇总到源的所有源项记录中是否必须唯一。 isPartOfKey如果设置为“true”，则值必须是唯一的，否则可以为同一自定义属性上传重复值。

对于广告定制器源和源项，名为“自定义 ID”的字符串始终被视为唯一键， isPartOfKey 即始终为“true”。 “自定义 ID”属性是目前通过 Microsoft Advertising Web 应用程序为广告定制器源设置唯一键的唯一方法。使用批量 API 可以更灵活地使用任何属性名称作为唯一键。

对于页面源和源项，“页面 Url”始终被视为唯一键， isPartOfKey 即始终为“true”。

对于 DynamicDataAutosListing 源和源项，“VehicleId”始终被视为唯一键， isPartOfKey 即始终为“true”。

name

属性 name 用于跨源和源项映射不同的自定义属性。实际上，这是确保特定源项汇总到源中的同一“列”的方式。在上面的广告定制器示例中，源和源项同时使用了“DateTimeName”、“Int64Name”、“PriceName”和“StringName”名称。

源名称

源的名称。

该名称必须是唯一的， (不区分大小写) 帐户中的所有源。该名称最多可包含 128 个字符。

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

Id

源的系统生成的标识符。

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

修改时间

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

注意

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

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

父 ID

包含源的帐户的系统生成的标识符。

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

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

状态

源的状态。

可能的值为 Active 或 Deleted。

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

子类型

源子类型包含在批量下载文件中，以便于可读。

可能的值有：

PageFeed
AdCustomizerFeed
DynamicDataToursAndActivitiesFeed
DynamicDataCreditCardsFeed
DynamicDataCruisesFeed
DynamicDataHealthInsuranceFeed
DynamicDataProfessionalServiceFeed
DynamicDataMortgageLendersFeed
DynamicDataEventsFeed
DynamicDataHotelsAndVacationRentalsFeed
DynamicDataCustomFeed
DynamicDataAutosListingFeed

将来可能支持新值，因此不得依赖于一组固定值。

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

通过

源记录 - 批量

客户端 ID

自定义属性

feedAttributeType

isPartOfKey

name

源名称

Id

修改时间

父 ID

状态

子类型

反馈

其他资源