通过

关键字记录 - 批量

  • 项目

定义可在批量文件中下载和上传的关键字 (keyword) 。

通过在 DownloadCampaignsByAccountIds 或 DownloadCampaignsByCampaignIds 服务请求中包含 Keywords 的 DownloadEntity 值，可以下载帐户中的所有 Keyword 记录。 此外，下载请求必须包括 EntityData 范围。 若要在下载的市场活动记录中包含“关键字相关性”、“登陆页相关性”、“登陆页用户体验”和“质量分数”字段，还必须包括 QualityScoreData 范围。 如果还包含 BidSuggestionsData 范围，则批量文件还可以包含与每个下载关键字 (keyword) 对应的单独的关键字最佳位置出价、关键字主线出价和关键字首页出价记录。 有关批量服务的更多详细信息（包括最佳做法），请参阅 批量下载和上传。

如果提供了有效的父 ID 值，下面的批量 CSV 示例将添加新关键字 (keyword) 。

Type,Status,Id,Parent Id,Campaign,Ad Group,Client Id,Modified Time,Keyword,Match Type,Bid,Param1,Param2,Param3,Name,Final Url,Mobile Final Url,Tracking Template,Final Url Suffix,Custom Parameter,Bid Strategy Type
Format Version,,,,,,,,,,,,,,6.0,,,,,,
Keyword,Active,,-1111,ParentCampaignNameGoesHere,AdGroupNameGoesHere,ClientIdGoesHere,,red shoes,Broad,0.5,,,,,https://www.contoso.com/womenshoesale,https://mobile.contoso.com/womenshoesale,,,{_promoCode}=PROMO1; {_season}=summer,ManualCpc

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

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkKeyword
var bulkKeyword = new BulkKeyword
{
    // 'Parent Id' column header in the Bulk file
    AdGroupId = adGroupIdKey,
    // 'Ad Group' column header in the Bulk file
    AdGroupName = "AdGroupNameGoesHere",
    // 'Campaign' column header in the Bulk file
    CampaignName = "ParentCampaignNameGoesHere",
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
                
    // Map properties in the Bulk file to the 
    // Keyword object of the Campaign Management service.
    Keyword = new Keyword
    {
        // 'Bid' column header in the Bulk file
        Bid = new Bid
        {
            Amount = 0.50,
        },
        // 'Bid Strategy Type' column header in the Bulk file
        BiddingScheme = new ManualCpcBiddingScheme { },
        // 'Destination Url' column header in the Bulk file
        DestinationUrl = null,
        // 'Mobile Final Url' column header in the Bulk file
        FinalMobileUrls = new[] {
            // Each Url is delimited by a semicolon (;) in the Bulk file
            "https://mobile.contoso.com/womenshoesale"
        },
        // 'Final Url' column header in the Bulk file
        FinalUrls = new[] {
            // Each Url is delimited by a semicolon (;) in the Bulk file
            "https://www.contoso.com/womenshoesale"
        },
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Match Type' column header in the Bulk file
        MatchType = MatchType.Broad,
        // 'Param 1 column header in the Bulk file
        Param1 = null,
        // 'Param 2' column header in the Bulk file
        Param2 = null,
        // 'Param 3' column header in the Bulk file
        Param3 = null,
        // 'Status' column header in the Bulk file
        Status = KeywordStatus.Active,
        // 'Text' column header in the Bulk file
        Text = "red shoes",
        // 'Tracking Template' column header in the Bulk file
        TrackingUrlTemplate = null,
        // 'Custom Parameter' column header in the Bulk file
        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"
                },
            }
        },
    },
};

uploadEntities.Add(bulkKeyword);

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

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

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

广告组

包含关键字 (keyword) 的广告组的名称。

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

注意

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

竞价

每次有人点击广告时要支付的最高金额。

你使用相同的关键字 (keyword) 向其他广告客户出价，因此，通常，更高的出价有助于你的广告显示在搜索结果页面上更理想的位置。

可以为每个关键字 (keyword) 设置自定义出价，而不是使用默认广告组级别出价。 关键字的自定义出价将覆盖这些特定关键字的广告组默认出价。 使用自定义出价，可以将时间和金钱集中在最有利可图的关键字上，但需要花费更多时间来管理单个出价。

如果未设置关键字 (keyword) 级别出价，则使用广告组 Cpc 出价。 有关详细信息，请参阅 预算和投标策略。

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

出价策略类型

要如何管理出价的出价策略类型。

广告组和关键字的出价策略类型为“InheritFromParent”。

注意

自 2021 年 4 月起，无法为广告组或关键字设置任何出价策略。 如果尝试为广告组或关键字设置出价策略，请求将被忽略，而不会出错。 广告组和关键字将继承其市场活动的出价策略。

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

Campaign

包含关键字 (keyword) 的活动的名称。

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

客户端 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。 如果指定，将使用关键字 (keyword) 的目标 URL;否则，使用广告的目标 URL。

重要

自 2018 年 11 月起，无法添加或更新关键字 (keyword) 目标 URL。 可以改用 最终 URL ，否则 Microsoft Advertising 将使用广告的最终 URL。 有关详细信息，请参阅将关键字 (keyword) 目标 URL 迁移到最终 URL。

添加： 不允许
更新： 不允许
删除： 只读

编辑上诉状态

确定是否可以对编辑评审发现的问题提出上诉。

下表介绍了可能的值。

值 说明
上诉 编辑问题很有吸引力。
AppealPending 编辑问题可上诉，已提出上诉。
NotAppealable 编辑问题没有吸引力。

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

编辑位置

编辑评审失败的关键字 (keyword) 的组件或属性。

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

编辑原因代码

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

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

编辑状态

关键字 (keyword) 的编辑状态。

下表介绍了可能的值。

值 说明
活动 关键字 (keyword) 通过了编辑评审。
ActiveLimited 关键字 (keyword) 一个或多个市场通过了编辑评审，关键字 (keyword) 的一个或多个要素正在另一个市场进行编辑评审。 例如，关键字 (keyword) 通过了加拿大的编辑评审，仍在美国中等待评审。
反对 关键字 (keyword) 编辑评审失败。
非活动 关键字 (keyword) 的一个或多个元素正在接受编辑评审。

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

编辑术语

编辑评审失败的术语。

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

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

最终 URL

登陆页 URL。 如果指定，将使用关键字 (keyword) 的最终 URL;否则，使用广告的最终 URL。

以下验证规则适用于最终 URL 和最终移动 URL。

  • URL 的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。

  • 最多可为最终 URL 和最终移动 URL 指定 10 个项目;但是，每个列表中的第一项仅用于传递。 该服务最多允许 10 个，以确保潜在的向前兼容性。

  • 每个 URL 由分号和空格 (“分隔;“) 。

  • 仅允许使用“{”和“}”来描述标记，例如“{lpurl}”。

  • 每个 URL 必须是格式正确的 URL，以 http:// 或 https:// 开头。

  • 如果指定“最终移动 URL”，还必须指定“最终 URL”。

另请注意，如果设置了“跟踪模板”或“自定义参数”字段，则需要“最终 URL”字段。

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

最终 URL 后缀

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

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

Id

关键字 (keyword) 的系统生成的标识符。

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

继承的出价策略类型

如果关键字 (keyword) 的“出价策略类型”设置为 InheritFromParent，则从父市场活动或广告组继承的出价策略类型。 此值等于父市场活动或广告组的 “出价策略类型” 字段。 可能的值为 EnhancedCpc、 ManualCpc、 MaxClicks、 MaxConversions、 TargetCpa 和 TargetRoas。

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

关键字

关键字 (keyword) 文本。

文本最多可以包含 100 个字符。

应在为关键字 (keyword) 所属的广告组指定的 Language 值的区域设置中指定关键字 (keyword) 。

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

关键字相关性

一个数字分数，指示你的广告被点击的可能性，以及你的关键字 (keyword) 与针对相同流量的其他关键字的竞争程度。 此分数可预测关键字 (keyword) 是否可能导致广告点击，并考虑到过去关键字 (keyword) 相对于广告位置的表现。

注意

关键字相关性等效于 Microsoft Advertising Web 应用程序中使用的 “预期 Click-Through 速率 ”标签。

3 的分数高于平均值;2 的分数为平均值;分数为 1 被视为低于平均值。

如果指定跨多天的时间段，则时间段内每天的分数将相同，并且该值是最近计算的分数。

此列的数据通常在 UTC 日结束后 14-18 小时更新。

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

登陆页相关性

一个数字分数，指示广告和登陆页面与客户的搜索查询或其他输入的相关性。

注意

登陆页面相关性等效于 Microsoft Advertising Web 应用程序中使用 的广告相关性 标签。

3 的分数高于平均值;2 的分数为平均值;分数为 1 被视为低于平均值。

如果指定跨多天的时间段，则时间段内每天的分数将相同，并且该值是最近计算的分数。

此列的数据通常在 UTC 日结束后 14-18 小时更新。

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

登陆页用户体验

一个数字分数，指示登陆页面是否可能为点击你的广告并登录你的网站的客户提供良好的体验。

注意

登陆页用户体验等效于 Microsoft Advertising Web 应用程序中使用的 登陆页面体验 标签。

3 的分数高于平均值;2 的分数为平均值;分数为 1 被视为低于平均值。

如果指定跨多天的时间段，则时间段内每天的分数将相同，并且该值是最近计算的分数。

此列的数据通常在 UTC 日结束后 14-18 小时更新。

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

匹配类型

要比较关键字 (keyword) 和用户的搜索词的匹配类型。

关键字 (keyword) 支持的匹配类型值为 Broad、Exact 和 Phrase。

注意：如果已为搜索市场活动启用预测定位，则匹配类型为“预测”。 在这种情况下，无法添加、更新和删除匹配类型，因为我们使用预测性定位将你的广告与相关的搜索查询相匹配。

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

移动最终 URL

移动登陆页 URL。 如果指定，将使用关键字 (keyword) 的最终移动 URL;否则，使用广告的最终移动 URL。

以下验证规则适用于最终 URL 和最终移动 URL。

  • URL 的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。

  • 最多可为最终 URL 和最终移动 URL 指定 10 个项目;但是，每个列表中的第一项仅用于传递。 该服务最多允许 10 个，以确保潜在的向前兼容性。

  • 每个 URL 由分号和空格 (“分隔;“) 。

  • 仅允许使用“{”和“}”来描述标记，例如“{lpurl}”。

  • 每个 URL 必须是格式正确的 URL，以 http:// 或 https:// 开头。

  • 如果指定“最终移动 URL”，还必须指定“最终 URL”。

另请注意，如果设置了 TrackingUrlTemplate 或 UrlCustomParameters 元素，则至少需要一个最终 URL。

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

修改时间

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

注意

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

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

Param1

如果广告的标题、文本、显示 URL 或目标 URL 包含 {Param1} 动态替换字符串，则用作广告中替换值的字符串。

注意

尽管您可以使用 {Param1} 指定广告的目标 URL，但建议不要。 相反，应设置关键字 (keyword) 的 DestinationUrl 元素。

该字符串最多可以包含 1,022 个字符。 实际限制取决于引用替换字符串的元素的长度。 例如，文本广告标题的长度最多可以包含 25 个字符。

在广告副本中实现动态文本时，应提供一个默认字符串，例如{Param1：default}，如果关键字 (keyword) 的 Param1 为 null 或为空，或者如果包含 Param1 替换值将导致扩展的字符串超出元素的限制，则系统将使用该字符串;否则，广告将不会提供此关键字 (keyword) 。 有关详细信息，请参阅 Microsoft Advertising 帮助文章 使用动态文本参数自动自定义广告。

另请注意，如果广告组只有一个广告，并且该广告使用 {Param1} 但未提供默认字符串（例如 {Param1：default}），则必须为该替换提供有效的 Param1 值。 否则，无法添加或更新此关键字 (keyword) 。

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

Param2

如果标题、文本、显示 URL 或目标 URL 包含 {Param2} 动态替换字符串，则用作广告中替换值的字符串。

通常，在标题或文本中使用 {Param2} 替换字符串， (广告副本说明) 广告元素。

字符串最多可以包含 70 个字符。 实际限制取决于引用替换字符串的元素的长度。 例如，文本广告标题的长度最多可以包含 25 个字符。

在广告副本中实现动态文本时，应提供一个默认字符串，例如{Param2：default}，如果用于关键字 (keyword) 的 Param2 为 null 或为空，或者如果包含 Param2 替换值将导致扩展的字符串超出元素的限制，则系统将使用该字符串;否则，广告将不会提供此关键字 (keyword) 。 有关详细信息，请参阅 Microsoft Advertising 帮助文章 使用动态文本参数自动自定义广告。

另请注意，如果广告组只有一个广告，并且该广告使用 {Param2} 但不提供默认字符串（例如 {Param2：default}），则必须为该替换提供有效的 Param2 值。 否则，无法添加或更新此关键字 (keyword) 。

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

Param3

如果标题、文本、显示 URL 或目标 URL 包含 {Param3} 动态替换字符串，则用作广告中替换值的字符串。

通常，在标题或文本中使用 {Param3} 替换字符串 (广告副本说明) 广告元素。

字符串最多可以包含 70 个字符。 实际限制取决于引用替换字符串的元素的长度。 例如，文本广告标题的长度最多可以包含 25 个字符。

在广告副本中实现动态文本时，应提供一个默认字符串，例如{Param3：default}，如果 param3 for a 关键字 (keyword) 为 null 或为空，或者如果包含 Param3 替换值将导致扩展的字符串超出元素的限制，则系统将使用该字符串;否则，此关键字 (keyword) 将不会提供广告。 有关详细信息，请参阅 Microsoft Advertising 帮助文章 使用动态文本参数自动自定义广告。

另请注意，如果广告组只有一个广告，并且该广告使用 {Param3} 但不提供默认字符串（例如 {Param3：default}），则必须为该替换提供有效的 Param3 值。 否则，无法添加或更新此关键字 (keyword) 。

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

父 ID

包含关键字 (keyword) 的广告组的系统生成的标识符。

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

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

注意

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

发布者国家/地区

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

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

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

质量分数

数字分数通过衡量关键字和登陆页面与客户搜索词的相关性来显示广告在市场中具有的竞争力。 质量分数由 Microsoft Advertising 使用 关键字相关性、 登陆页面相关性和 登陆页面用户体验 子分数来计算。 如果可用，质量分数的范围可以从低 1 到高 10。

质量分数基于自有和运营的搜索流量的最后滚动 30 天。 如果关键字 (keyword) 出价未赢得任何拍卖，则可以在没有任何印象的情况下分配质量分数。 联合网络的流量不会影响质量分数。 如果未计算分数，文件中的值将为“” (空字符串) 。 如果 30 天或更长的关键字 (keyword) 没有展示，则可能会出现这种情况。

质量分数通常在 UTC 日结束后 14-18 小时更新。 将为所有时区中的关键字分配相应 UTC 日的质量分数。

如果一天中多次运行报表，则质量分数值可能会根据你运行报表的时间（相对于计算分数的时间）从报表更改为报表。

如果指定跨多天的时间段，则质量分数是当前和最近计算的分数，并且将报告为时间段内每天的相同分数。 使用历史质量分数来了解质量分数随时间的变化情况。 历史质量分数是滚动质量分数的每日快照。 有关历史质量分数的详细信息，请参阅报表属性和性能统计信息中的 HistoricalQualityScore 列。

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

状态

关键字 (keyword) 的状态。

可能的值为 Active、 Paused、 Inactive 或 Deleted。

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

跟踪模板

要用作 FinalUrls 指定 URL 的默认跟踪模板。

以下验证规则适用于跟踪模板。 有关支持的模板和参数的更多详细信息，请参阅 Microsoft Advertising 帮助文章 我可以使用哪些跟踪或 URL 参数？

  • 为较低级别的实体（例如广告）定义的跟踪模板将覆盖为较高级别的实体（例如市场活动）设置的模板。 有关详细信息，请参阅 实体限制。

  • 跟踪模板的长度限制为 2,048 个字符。 HTTP 或 HTTPS 协议字符串计入 2,048 个字符限制。

  • 跟踪模板必须是格式正确的 URL，从以下项之一开始： http://、 https://、 {lpurl}或 {unescapedlpurl}。

  • Microsoft Advertising 不会验证自定义参数是否存在。 如果在跟踪模板中使用自定义参数，并且这些参数不存在，则登陆页 URL 将包含自定义参数的键和值占位符，而不进行替换。 例如，如果跟踪模板为 https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}，并且未在市场活动、广告组、条件、关键字 (keyword) 或广告级别定义 {_season} 或 {_promocode}，则登陆页 URL 将相同。

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