通过

迁移到版本 13

  • 项目

注意

必应广告 API 版本 12 日落，截至 2019 年 10 月 31 日。

以下部分介绍了必应广告 API 从版本 12 到版本 13 的更改。

所有服务的身份验证

面向开发人员 的Microsoft标识平台终结点 现已推出。 Microsoft标识平台终结点允许来自 Azure AD 的工作或学校帐户以及 MSA) (个人Microsoft帐户，例如 hotmail.com、outlook.com 和 msn.com。 Live Connect 终结点仅允许使用个人帐户进行身份验证。

尽管从 Live Connect 终结点迁移到 Microsoft 标识平台终结点 与从版本 12 迁移到 13 无关，但我们知道，许多开发人员希望在同一冲刺期间升级。

重要

对于Microsoft广告用户，建议使用 Live Connect 终结点。 请升级到 Microsoft 标识平台终结点 ，以确保应用程序可以支持所有用户，而不会造成摩擦或服务中断。 只有 Microsoft 标识平台终结点 (v2.0) 允许你获取访问令牌，以通过必应广告 API 对工作和个人帐户进行身份验证。

Ad Insight

有关全面的版本 13 服务参考文档，请参阅 Ad Insight。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/AdInsight/v13。

生产终结点为 https://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc。

沙盒终结点为 https：//adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc。

数据协定命名空间

在版本 12 中，某些实体的数据协定命名空间与 Ad Insight 目标命名空间不同。 如果使用了以下任何版本 12 命名空间，则必须在 https://bingads.microsoft.com/AdInsight/v13 版本 13 中使用。

  • Microsoft.BingAds.广告商.AdInsight.Api.DataContract.V12.Entity.SearchParameters
  • Microsoft.BingAds.广告商.AdInsight.Api.DataContract.V12.Entity.Common
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.Criterions
  • Microsoft.BingAds.广告商.AdInsight.Api.DataContract.V12.Entity

对 SOAP 信封进行编码的客户端e.g. PHP为 DateRangeSearchParameter 编码SoapVar的客户端，需要更新到 Ad Insight Version 13 目标命名空间，即 https://bingads.microsoft.com/AdInsight/v13。

必应广告 Python SDK 客户端将需要为 SUDS 客户端工厂对象更新多个命名空间前缀，例如，如果在必应广告 API 版本 12 中使用 ns4：DateRangeSearchParameter ，则将使用 DateRangeSearchParameter (版本 13 中没有“ns4”前缀) 。 有关如何确定命名空间前缀的详细信息，请参阅 使用 SUDS 。

批量邮件

有关全面的版本 13 服务参考文档，请参阅 批量。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/CampaignManagement/v13。

生产终结点为 https://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc。

沙盒终结点为 https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc。

响应式广告图像资产

横向图像媒体 ID、横向徽标媒体 ID、方形图像媒体 ID 和方形徽标媒体 ID 列已从 响应式广告 记录中弃用。 它们仍将在下载文件中可见，不过由于它们将在将来的版本中删除，因此不应对这些列使用任何依赖项。 请改用 “图像” 列。

实体性能数据

性能数据的批量下载以前在版本 12 中是落定。 现在，在版本 13 中， DataScope 值集的 EntityPerformanceData 值将从服务协定中删除。 此外，还将删除 Date 和 PerformanceStatsDateRange 对象和 ReportTimePeriod 值设置如果希望按天、周或月聚合数据，可以使用报告 API。 有关详细信息，请参阅 报告 API 指南。

市场活动管理

有关全面的版本 13 服务参考文档，请参阅 市场活动管理。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/CampaignManagement/v13。

生产终结点为 https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc。

沙盒终结点为 https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc。

响应式广告图像资产

从 ResponsiveAd 对象中删除 LandscapeImageMediaId、LandscapeLogoMediaId、SquareImageMediaId 和 SquareLogoMediaId 元素。 必须改用 Images 元素。

响应式广告文本资产

如果在版本 12 中使用 了 LongHeadline 字符串元素，则应在版本 13 中使用 LongHeadlineString (字符串) 元素。 LongHeadline 的数据类型已从字符串更新为 AssetLink。 此资产链接保留供将来使用。

添加了 “标题” 和 “说明” 资产链接列表，供将来使用。

GetMediaMetaDataByAccountId 的默认分页

如果在调用 GetMediaMetaDataByAccountId 操作时未设置 PageInfo 元素，则 defaut 页 Index 将为 0，默认大小将为 1,000。 在版本 12 中，如果未设置 PageInfo，则会返回帐户中的所有媒体元数据。

无效数据类型忽略的条件出价

对于添加和更新 BiddableCampaignCriterion 时的版本 12 和 13，派生 的 CriterionBid 对象类型要求因与之配对的派生 Criterion 对象类型的上下文而异。 例如，如果继承的 Criterion 是 ProductScope 条件，则应使用 FixedBid 对象 (而不是 BidMultiplier) 。

在版本 13 中，如果不使用正确的 Criterion 对象，则将忽略所请求的出价：如果需要出价，操作将失败;如果出价是可选的，将使用默认出价。

在版本 12 中，如果未使用正确的 Criterion 对象，则请求的出价将得到接受;但是，在以后检索对象时，将返回正确的类型。 换句话说，设置的数据类型与检索到的数据类型不同。

从版本 12 到版本 13 的此更改仅适用于市场活动级别的可出价标准。 对于版本 12 和 13 可出价广告组标准，如果不使用正确的 Criterion 对象，则请求的出价将被忽略：如果需要出价，操作将失败;如果出价是可选的，将使用默认出价。

可选关键字出价

调用 AddKeywords 操作时，Keyword 的 Bid 元素是可选的。 以前在版本 12 中，需要出价才能添加关键字。 如果要继承关键字和匹配类型的默认广告组出价，可以将关键字出价留空。

负关键字匹配类型

NegativeKeyword 的 MatchType 元素是 nillable 的。 如果以前依赖于版本 12 中的默认 MatchType 值（即 Exact），则必须在版本 13 中显式设置此必需元素。

动态搜索广告源

DynamicSearchAdsSetting 的 Source 元素是 nillable 的。 将从 AddCampaigns 和 UpdateCampaigns 请求消息中删除 IncludeDynamicSearchAdsSource 元素。 如果启用了页面源，则可以在版本 13 中设置源。

市场活动说明

从 Campaign 对象中删除 Description 元素。 仍可使用 Name 元素提供唯一的市场活动名称。

返回其他字段

从 GetAdExtensionsAssociations 中删除 ReturnAdAdditionalFields 元素， GetAdExtensionsByIds、GetAdGroupCriterionsByIds、GetAdGroupsByCampaignId、GetAdGroupsByIds、GetAdsByAdGroupId、GetAdsByEditorialStatus、GetAdsByIds、GetCampaignsByAccountId、GetCampaignsByIds、GetKeywordsByAdGroupId、GetKeywordsByEditorialStatus 和GetKeywordsByIds 请求消息。 默认情况下，将返回每个广告、广告扩展、广告组、可出价广告组条件、市场活动以及关键字的所有元素。

同时删除相关的 AdAdAdditionalField、AdExtensionAdditionalField、AdGroupCriterionAdditionalField、CampaignAdditionalField 和 KeywordAdditionalField 值集。

目标迁移已完成

以前已完成从共享目标到独占市场活动及广告组目标条件的迁移。 IsMigrated 元素现已从 AddAdGroupCriterions、 UpdateAdGroupCriterions、 AddCampaignCriterions 和 UpdateCampaignCriterions 操作的 响应中删除。

新功能

新的出价策略类型

已添加 MaxRoasBiddingScheme 和 TargetRoasBiddingScheme 出价策略类型，以供将来在版本 13 中使用。

Customer Share

CustomerShare 元素将添加到 Audience 和 UetTag 对象。 此元素保留供将来使用。

转换目标从出价中排除

ExcludeFromBidding 元素将添加到 ConversionGoal 对象。 此元素保留供将来使用。

客户计费

有关全面的版本 13 服务参考文档，请参阅 客户计费。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/Billing/v13。

生产终结点为 https://clientcenter.api.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc。

沙盒终结点为 https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc。

插入顺序对象

将多个属性添加到 InsertionOrder 对象。

BalanceAmount 元素将被删除，并替换为 BudgetRemaining 元素。

已删除 GetInsertionOrdersByAccount

已删除 GetInsertionOrdersByAccount 操作。 可以在版本 13 中使用 SearchInsertionOrders 。

客户管理

有关全面的版本 13 服务参考文档，请参阅 客户管理。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/Customer/v13。

生产终结点为 https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc。

沙盒终结点为 https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc。

对 ClientLink 对象进行了多项更改。

客户地址

在版本 13 中，CustomerAddress 元素默认包含在所有返回的 Customer 对象中。 无需显式请求此元素。 将从 GetCustomer 和 SearchCustomers 请求消息中删除 IncludeCustomerAddress 元素。

链接帐户 ID

在版本 13 中，LinkedAccountIds 元素默认包含在所有返回的 CustomerRole 对象中。 无需显式请求此元素。 IncludeLinkedAccountIds 元素将从 GetUser 请求消息中删除。

澳大利亚和巴西的税务信息

为澳大利亚和巴西设置帐户 TaxInformation 时，TaxId 和 TaxType 密钥不再可用。 对于澳大利亚，请使用 AUGSTNumber 作为键，并将值设置为税务标识符。 对于巴西，可能的密钥是 CCM、CPF 和 CNPJ。

说明 版本 12 版本 13
澳大利亚的帐户 TaxId=YourTaxId AUGSTNumber=YourTaxId
巴西的业务帐户 TaxId=YourTaxId;TaxType=Business CPNJ=YourTaxId
巴西的个人帐户 TaxId=YourTaxId;TaxType=Personal CPF=YourTaxId

对于巴西圣保罗市的商业帐户，CCM 密钥在版本 12 和版本 13 之间没有变化。

新功能

客户角色链接权限

CustomerLinkPermission 元素将添加到 CustomerRole 对象。 此元素保留供将来使用。

Reporting

有关全面的版本 13 服务参考文档，请参阅 报告。

中断性变更

代理客户端

更新代理客户端以使用新的终结点地址和命名空间。

目标命名空间为 https://bingads.microsoft.com/Reporting/v13。

生产终结点为 https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc。

沙盒终结点为 https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc。

ProductMatchCountReportRequest 的必需列

提交 ProductMatchCountReportRequest 时，将更新所需的列。 在版本 13 中，需要 AccountName、CampaignName、MatchedProductsAtProductGroup 和 ProductGroup 列。

在版本 12 中，除了 AccountName 和 CampaignName 要求之外，还需要一个或多个 MatchedProductsAtAdGroup、MatchedProductsAtCampaign 或 MatchedProductsAtProductGroup 性能统计信息列。

语言报表筛选器

将添加 LanguageReportFilter 值集。 以下报表筛选器中的 LanguageCode (字符串) 元素替换为 Language (LanguageReportFilter) 元素。

目标的所有转换和收入报表

GoalsAndFunnelsReportColumn 中的“转换”和“收入”列分别重命名为 AllConversions 和 AllRevenue。 数据的含义尚未从版本 12 更改为 13。

法语报表标题

已删除对下载具有法语标题的报表的支持。 版本 13 中仅支持英文标头。 从 ReportRequest 对象中删除 Language 元素，并删除 ReportLanguage 值集。

已删除 AgeGenderDemographicReportRequest

已删除 AgeGenderDemographicReportRequest。 相反，可以使用 AgeGenderAudienceReportRequest。

搜索市场活动类型

对于搜索市场活动， 在 CampaignType 列中返回的数据为“搜索”。 在版本 12 中，返回的值为“搜索 & 内容”。 CampaignType 列可通过 AdGroupPerformanceReportColumn、AdPerformanceReportColumn、CampaignPerformanceReportColumn 和 SearchQueryPerformanceReportColumn 值集获得。

产品组数据格式

更新 ProductGroup 列中返回的数据的格式。

版本 说明 示例
12 使用“\” (反斜杠) 来分隔级别。

属性值不由“” (双引号) 括起来。

类别级别将追加到属性值（如果适用），例如“ (1st Level) ”、“ (2nd Level) ”等。		 * \ Category=动物 & 宠物用品 (第一级) \ Category=宠物用品 (二级) \ Category=鸟用品 (三级)
13 使用“/” (正斜杠) 来分隔级别。

属性值由“” (双引号) 括起来。

不指示类别级别，例如删除“ (第一级) ”。		 * / Category=“动物 & 宠物用品” / Category=“宠物用品” / Category=“鸟类用品”

此更改通过以下值集应用于 ProductGroup 列。

不可用质量分数的短划线

在版本 13 中，如果未计算质量分数，则返回的数据将为 (AdRelevance、ExpectedCtr、HistoricalAdRelevance、HistoricalExpectedCtr、HistoricalLandingPageExperience、HistoricalQualityScore、LandingPageExperience 和 QualityScore 列中的双短划线) 。 在版本 12 中，已返回“0” (零) 。 AdGroupPerformanceReportColumn、CampaignPerformanceReportColumn、KeywordPerformanceReportColumn 和 ShareOfVoiceReportColumn 值集中提供了这些列。

已替换某些印象共享列

从 AccountPerformanceReportColumn、AdGroupPerformanceReportColumn、CampaignPerformanceReportColumn、CampaignPerformanceReportColumn、CampaignPerformanceReportColumn 和 ShareOfVoiceReportColumn 值集中删除了 ImpressionLostToAdRelevancePercent、ImpressionLostToAdRelevancePercent、ImpressionLostToExpectedCtrPercent、ImpressionLostToRelevancePercent 和 ImpressionLostToRankPercent 列。

在版本 13 中，已在版本 12 列之间拆分的数据通过 ImpressionLostToRankAggPercent 列进行聚合和提供，该列在计算因排名百分比而丢失的印象时会考虑所有这些因素。

删除了 AverageCpp、ClickCalls 和 ManualCalls 列

从 AccountPerformanceReportColumn、 AdGroupPerformanceReportColumn 和 CampaignPerformanceReportColumn 值集中删除 AverageCpp、 ClickCalls 和 ManualCalls 列。

删除了 CallStatus 和 CallTypeName 列

CallStatus 和 CallTypeName 列将从 CallDetailReportColumn 值集中删除。 Microsoft广告于 2014 年 3 月 12 日停止对跟踪号码的手动呼叫收费。

需要帐户、市场活动或广告组范围

在版本 13 中，必须将请求范围限定为特定帐户、市场活动或广告组。 例如，可以通过 AccountThroughAdGroupReportScope 包含最多 1,000 个帐户、300 个市场活动或 300 个广告组。 以前在版本 12 中，对于某些报表类型，可以将报表范围保留为 null，并且将针对可以访问的所有帐户返回数据。