共用方式為

移轉至第13版

  • 發行項

注意事項

Bing Ads API 12 版自 2019 年 10 月 31 日終止。

下列各節說明從第 12 版到第 13 版的 Bing 廣告 API 變更。

所有服務的驗證

適用於開發人員 的Microsoft身分識別平臺端點 現已可供使用。 Microsoft身分識別平臺端點允許來自 Azure AD 的公司或學校帳戶，以及 MSA) (個人Microsoft帳戶，例如 hotmail.com、outlook.com 和 msn.com。 Live Connect 端點只允許使用個人帳戶進行驗證。

雖然從 Live Connect 端點移轉至 Microsoft身分識別平臺端點 與從 12 版移轉至 13 版無關，但我們瞭解許多開發人員都想要在相同的短期衝刺期間升級。

重要事項

Live Connect 端點不再是Microsoft廣告用戶的建議方法。 請升級至 Microsoft身分識別平臺端點 ，以確保您的應用程式可以支援所有使用者，而不會發生衝突或服務中斷。 只有 v2.0 (Microsoft身分識別平臺端點) 可讓您取得存取令牌，以透過 Bing 廣告 API 驗證公司和個人帳戶。

Ad Insight

如需完整的第 13 版服務參考檔，請參閱 Ad Insight。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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 命名空間，則必須在第 13 版中安裝使用 https://bingads.microsoft.com/AdInsight/v13 。

  • Microsoft.BingAds.Marketplace.AdInsight.Api.DataContract.V12.Entity.SearchParameters
  • Microsoft.BingAds.Anchor.AdInsight.Api.DataContract.V12.Entity.Common
  • Microsoft.BingAds.Anchor.AdInsight.Api.DataContract.V12.Entity.Criterions
  • Microsoft.BingAds.Anchor.AdInsight.Api.DataContract.V12.Entity

將 SOAP 信封編碼的用戶端e.g. PHP為 DateRangeSearchParameter 編碼 SoapVar 的用戶端，您必須更新為 Ad Insight 第 13 版目標命名空間，https://bingads.microsoft.com/AdInsight/v13也就是 。

Bing Ads Python SDK 用戶端必須更新 SUDS 用戶端 Factory 對象的數個命名空間前置詞，例如，如果您在 Bing 廣告 API 第 12 版中使用 ns4：DateRangeSearchParameter ，您將使用 DateRangeSearchParameter (，而在第 13 版中不使用 'ns4' 前置詞) 。 如需如何判斷命名空間前置詞的詳細資訊，請參閱 使用 SUDS 。

大量

如需完整的第 13 版服務參考檔，請 參閱大量。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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。

回應式廣告影像資產

橫向影像媒體標識碼、橫向標誌媒體標識碼、方形影像媒體標識碼和方形標誌媒體標識碼數據行已從 響應式廣告 記錄中淘汰。 它們仍會顯示在下載檔中，不過，因為在未來的版本中將會移除它們，您不應該對這些數據行採取任何相依性。 請改用 [ 影像] 資料行。

實體效能數據

效能數據的大量下載先前已在版本 12 中終止。 現在在第 13 版中， DataScope 值集的 EntityPerformanceData 值已從服務合約中移除。 此外， 也會 移除 Date 和 PerformanceStatsDateRange 物件和 ReportTimePeriod 值集如果您想要依日、周或月匯總數據，您可以使用報表 API。 如需詳細資訊，請 參閱報告 API 指南。

營銷活動管理

如需完整的第 13 版服務參考檔，請參閱 行銷活動管理。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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。

回應式廣告影像資產

LandscapeImageMediaId、LandscapeLogoMediaId、SquareImageMediaId 和 SquareLogoMediaId 元素會從 ResponsiveAd 物件中移除。 您必須改用 Images 元素。

回應式廣告文字資產

如果您在第 12 版中使用 LongHeadline 字串元素，您應該使用 LongHeadlineString (第 13 版中的字串) 元素。 LongHeadline 的數據類型會從字串更新為 AssetLink。 此資產連結會保留供日後使用。

[ 標題 ] 和 [描述] 資產鏈接清單會新增供日後使用。

GetMediaMetaDataByAccountId 的預設分頁

如果呼叫 GetMediaMetaDataByAccountId 作業時未設定 PageInfo 元素，則 Defaut 頁面 Index 會是 0，預設的 Size 會是 1,000。 如果未設定 PageInfo，則在第 12 版中，會傳回帳戶中的所有媒體中繼數據。

無效數據類型的準則比對已忽略

在新增和更新 BiddableCampaignCriterion 時，針對第 12 版和 13 版，衍生的 CriterionBid 物件類型需求會根據與其配對之衍生 之 Criterion 對象類型的內容而有所不同。 例如，如果繼承的 準則 是 ProductScope 準則，則您應該使用 FixedBid 物件 (而非 BidMultiplier) 。

在 13 版中，如果您未使用正確的 準則 物件，則會忽略您要求的參與：如果需要進行中標，作業將會失敗;如果是選擇性的，則會使用預設的中標。

在 12 版中，如果您未使用正確的 準則 物件，則會接受您要求的報價;不過，當您稍後擷取物件時，會傳回正確的類型。 換句話說，您設定的數據類型與擷取的數據類型不同。

從第 12 版到第 13 版的這項變更僅適用於營銷活動層級可申請的準則。 針對第 12 版和第 13 版的可標定廣告群組準則，如果您未使用正確的 準則 物件，則會忽略您要求的報價：如果需要進行約定，作業將會失敗;如果是選擇性的，則會使用預設的中標。

選擇性關鍵詞比對

當您呼叫 AddKeywords 作業時，Keyword 的 Bid 元素是選擇性的。 先前在第 12 版中，必須進行申請才能新增關鍵字。 如果您想要繼承關鍵詞和比對類型的默認廣告群組標示，則可以將關鍵詞 bid 保留空白。

負關鍵詞比對類型

NegativeKeyword 的 MatchType 元素是 nillable。 如果您先前已相依於第 12 版中的預設 MatchType 值，也就是 Exact，則您必須在第 13 版中明確設定此必要元素。

動態搜尋廣告來源

DynamicSearchAdsSetting 的 Source 元素是 nillable。 IncludeDynamicSearchAdsSource 元素會從 AddCampaigns 和 UpdateCampaigns 要求訊息中移除。 如果您已針對頁面摘要啟用，則在第 13 版中，您可以設定 Source。

營銷活動描述

Description 元素會從 Campaign 物件中移除。 您仍然可以使用 Name 元素來提供唯一的行銷活動名稱。

傳回其他欄位

ReturnAdditionalFields 元素會從 GetAdExtensionsAssociations 中移除， GetAdExtensionsByIds、GetAdGroupCriterionsByIds、GetAdGroupsByCampaignId、GetAdGroupsByIds、GetAdsByAdGroupId、GetAdsByEditorialStatus、GetAdsByIds、GetCampaignsByAccountId、GetCampaignsByIds、GetKeywordsByAdGroupId、GetKeywordsByEditorialStatus和GetKeywordsByIds 要求訊息。 默認會傳回每個廣告、廣告延伸模組、廣告群組、可標定廣告群組準則、營銷活動和關鍵詞的所有元素。

同時移除相關的 AdAdditionalField、AdExtensionAdditionalField、AdGroupAdditionalField、AdGroupCriterionAdditionalField、CampaignAdditionalField 和 KeywordAdditionalField 值集。

目標移轉已完成

先前已完成從共用目標移轉至專屬營銷活動和廣告群組目標準則。 IsMigrated 元素現在已從 AddAdGroupCriterions、 UpdateAdGroupCriterions、 AddCampaignCriterions 和 UpdateCampaignCriterions 作業的回應中移除。

新功能

新的中標策略類型

已新增 MaxRoasBiddingScheme 和 TargetRoasBiddingScheme 參與策略類型，以供未來在第 13 版中使用。

客戶共用

CustomerShare 元素會新增至 Audience 和 UetTag 物件。 此元素會保留供日後使用。

轉換目標排除在外

ExcludeFromBidding 元素會新增至 ConversionGoal 物件。 此元素會保留供日後使用。

客戶計費

如需完整的第 13 版服務參考檔，請 參閱客戶計費。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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。

Insertion Order 物件

InsertionOrder 物件中會加入數個屬性。

BalanceAmount 元素會移除，並由 BudgetRemaining 元素取代。

GetInsertionOrdersByAccount 已移除

GetInsertionOrdersByAccount 作業已移除。 您可以在第 13 版中使用 SearchInsertionOrders 。

客戶管理

如需完整的第 13 版服務參考檔，請 參閱客戶管理。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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 物件中。 您不需要明確要求此元素。 IncludeCustomerAddress 元素會從 GetCustomer 和 SearchCustomers 要求訊息中移除。

連結的帳戶標識碼

在第 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

對於巴西聖保羅市內的企業帳戶，12 到 13 版之間的 CCM 密鑰沒有任何變更。

新功能

客戶角色連結許可權

CustomerLinkPermission 元素會新增至 CustomerRole 物件。 此元素會保留供日後使用。

報告

如需完整的第 13 版服務參考檔，請 參閱報告。

重大變更

Proxy 用戶端

更新您的 Proxy 用戶端，以使用新的端點位址和命名空間。

目標命名空間為 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 數據行。

除了 AccountName 和 CampaignName 需求之外，先前在第 12 版中，還需要一或多個 MatchedProductsAtAdGroup、MatchedProductsAtCampaign 或 MatchedProductsAtProductGroup 效能統計數據行。

語言報表篩選

新增 LanguageReportFilter 值集。 LanguageCode (字串) 專案會由下列報表篩選中的 Languages (LanguageReportFilter) 元素取代。

目標報表的所有轉換和收益

GoalsAndFunnelsReportColumn 中的 [轉換] 和 [收益] 數據行會分別重新命名為 AllConversions 和 AllRevenue。 數據的意義尚未從 12 版變更為 13 版。

法文報表標頭

已移除以法文下載具有標頭之報表的支援。 第 13 版僅支援英文標頭。 Language 元素會從 ReportRequest 物件中移除，並移除 ReportLanguage 值集。

已移除 AgeGenderDemographicReportRequest

AgeGenderDemographicReportRequest 已移除。 您可以改用 AgeGenderAudienceReportRequest。

搜尋活動類型

若為搜尋活動， 在 CampaignType 數據行內傳回的數據為「搜尋」。 在第 12 版中，傳回的值是「搜尋 & 內容」。 CampaignType 數據行可透過 AdGroupPerformanceReportColumn、AdPerformanceReportColumn、CampaignPerformanceReportColumn 和 SearchQueryPerformanceReportColumn 值集取得。

產品群組數據格式

ProductGroup 數據行中傳回的數據格式會更新。

版本 描述 範例
12 使用 “\” (反斜線) 分隔層級。

屬性值不會以 「括住， (雙引號) 。

如果適用，類別層級會附加至屬性值，例如“ (第一層) 」、「 (第二層) 」等。		 * \ Category=Pet supplies & pet Supplies (1st Level) \ Category=Pet Supplies (2nd Level) \ Category=Bird Supplies (3rd Level)
13 使用 「/」 (正斜線) 分隔層級。

屬性值會以 「括住 (雙引號) 」。

不表示類別層級，例如「 (第一層) 」已移除。		 * / Category=“動物 & 寵物供應專案” / Category=“Pet Supplies” / Category=“Bird Supplies”

這項變更會透過下列值集套用至 ProductGroup 資料行。

Dash for Unavaililable Quality Score

在 13 版中，如果未計算品質分數，傳回的數據將會是 “--”， (AdRelevance、ExpectedCtr、HistoricalAdRelevance、HistoricalExpectedCtr、HistoricalLandingPageExperience、HistoricalQualityScore、LandingPageExperience 和 QualityScore 數據行中的雙虛線) 。 在第 12 版中，已傳回 「0」 (零) 值。 這些數據行位於 AdGroupPerformanceReportColumn、 CampaignPerformanceReportColumn、 KeywordPerformanceReportColumn 和 ShareOfVoiceReportColumn 值集。

已取代部分曝光共享數據行

ImpressionLostToAdRelevancePercent、ImpressionLostToBidPercent、ImpressionLostToExpectedCtrPercent、ImpressionLostToRelevancePercent 和 ImpressionLostToRankPercent 數據行會從 AccountPerformanceReportColumn、 AdGroupPerformanceReportColumn、 CampaignPerformanceReportColumn 和 ShareOfVoiceReportColumn 值集移除。

在第 13 版中，已在這些第 12 版數據行之間分割的數據會透過 ImpressionLostToRankAggPercent 數據行匯總並提供，該數據行會在計算失去印象的百分比時將所有這些因素納入考慮。

已移除 AverageCpp、ClickCalls 和 ManualCalls 數據行

AverageCpp、ClickCalls 和 ManualCalls 數據行會從 AccountPerformanceReportColumn、 AdGroupPerformanceReportColumn 和 CampaignPerformanceReportColumn 值集移除。

已移除 CallStatus 和 CallTypeName 數據行

CallStatus 和 CallTypeName 數據行會從 CallDetailReportColumn 值集移除。 Microsoft Advertising 在 2014 年 3 月 12 日停止對追蹤號碼的手動通話收費。

需要帳戶、營銷活動或廣告群組範圍

在第 13 版中，您必須將要求的範圍設定為特定帳戶、活動或廣告群組。 例如，您可以透過 AccountThroughAdGroupReportScope 包含最多 1,000 個帳戶、300 個行銷活動或 300 個廣告群組。 先前在第 12 版中，您可以將某些報表類型的報表範圍保留為 null，而且會針對您可以存取的所有帳戶傳回數據。