Edit

Bagikan melalui

Migrate to Version 13

  • Artikel

Note

Bing Ads API version 12 sunset as of October 31, 2019.

The sections below describe Bing Ads API changes from version 12 to version 13.

Authentication for All Services

The Microsoft identity platform endpoint for developers is now available. The Microsoft identity platform endpoint allows both work or school accounts from Azure AD and personal Microsoft accounts (MSA), such as hotmail.com, outlook.com, and msn.com. The Live Connect endpoint only allows authentication with personal accounts.

Although migrating from the Live Connect endpoint to the Microsoft identity platform endpoint is independent of migration from version 12 to 13, we understand that many developers would like to upgrade during the same sprint.

Important

The Live Connect endpoint is no longer the recommended approach for Microsoft Advertising users. Please upgrade to the Microsoft identity platform endpoint to ensure that your application can support all users without friction or interruption of service. Only the Microsoft identity platform endpoint (v2.0) allows you to obtain access tokens to authenticate both work and personal accounts via the Bing Ads API.

Ad Insight

For comprehensive version 13 service reference documentation see Ad Insight.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/AdInsight/v13.

The production endpoint is https://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

The sandbox endpoint is https://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

Data Contract Namespace

Previously in version 12, the data contract namespace for some entities had varied from the Ad Insight target namespace. If you used any of the following version 12 namespaces, you must insteaed use https://bingads.microsoft.com/AdInsight/v13 in version 13.

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

Clients who encode the SOAP envelope e.g. PHP clients who encode a SoapVar for DateRangeSearchParameter, you'll need to update to the Ad Insight Version 13 target namespace i.e., https://bingads.microsoft.com/AdInsight/v13.

Bing Ads Python SDK clients will need to update several namespace prefixes for the SUDS client factory objects e.g., if you used ns4:DateRangeSearchParameter in Bing Ads API Version 12 you'll use DateRangeSearchParameter (without the 'ns4' prefix) in version 13. See Using SUDS for details about how to determine the namespace prefix.

Bulk

For comprehensive version 13 service reference documentation see Bulk.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/CampaignManagement/v13.

The production endpoint is https://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

The sandbox endpoint is https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

Responsive Ad Image Assets

The Landscape Image Media Id, Landscape Logo Media Id, Square Image Media Id, and Square Logo Media Id columns are deprecated from the Responsive Ad record. They will still be visible in the download file, although since they will be removed in a future version you should not take any dependencies on these columns. Please use the Images column instead.

Entity Performance Data

Bulk download of performance data was previously sunset in version 12. Now in version 13 the EntityPerformanceData value of the DataScope value set is removed from the service contract. Also the Date and PerformanceStatsDateRange objects and ReportTimePeriod value set are removed If you want data aggregated by day, week, or month, you can use the Reporting API. For more details see Reporting API Guides.

Campaign Management

For comprehensive version 13 service reference documentation see Campaign Management.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/CampaignManagement/v13.

The production endpoint is https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

The sandbox endpoint is https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

Responsive Ad Image Assets

The LandscapeImageMediaId, LandscapeLogoMediaId, SquareImageMediaId, and SquareLogoMediaId elements are removed from the ResponsiveAd object. You must use the Images element instead.

Responsive Ad Text Assets

If you used the LongHeadline string element in version 12 you should use the LongHeadlineString (string) element in version 13. The data type of LongHeadline is updated from string to AssetLink. This asset link is reserved for future use.

The Headlines and Descriptions asset link lists are added for future use.

Default Paging for GetMediaMetaDataByAccountId

If the PageInfo element is not set when you call the GetMediaMetaDataByAccountId operation, the defaut page Index will be 0 and the default Size will be 1,000. In version 12 if PageInfo was not set, all media meta data in the account would be returned.

Criterion Bid Ignored for Invalid Data Type

For both version 12 and 13 when adding and updating a BiddableCampaignCriterion, the derived CriterionBid object type requirements vary depending upon the context of the derived Criterion object type that it is paired with. For example, if the inherited Criterion is a ProductScope criterion, then you should use a FixedBid object (not a BidMultiplier).

In version 13 if you do not use the correct Criterion object, then your requested bid will be ignored: If the bid is required, the operation will fail; If the bid is optional, the default bid will be used.

In version 12 if you do not use the correct Criterion object, then your requested bid would have been honored; however, when you retrieve the object later the correct type is returned. In other words the data type that you set is not the same as the data type retrieved.

This change from version 12 to version 13 only applies to campaign level biddable criterions. For both version 12 and 13 biddable ad group criterions, if you do not use the correct Criterion object, then your requested bid will be ignored: If the bid is required, the operation will fail; If the bid is optional, the default bid will be used.

Optional Keyword Bid

When you call the AddKeywords operation, the Bid element of the Keyword is optional. Previously in version 12, the bid was required to add keywords. If you want to inherit the default ad group bid for the keyword and match type, then you can leave the keyword bid empty.

Negative Keyword Match Type

The MatchType element of the NegativeKeyword is nillable. If you had previously taken a dependency on the default MatchType value in version 12 i.e., Exact, then you must explicitly set this required element in version 13.

Dynamic Search Ads Source

The Source element of the DynamicSearchAdsSetting is nillable. The IncludeDynamicSearchAdsSource element is removed from the AddCampaigns and UpdateCampaigns request messages. If you are enabled for page feeds, then in version 13 you can set the Source.

Campaign Description

The Description element is removed from the Campaign object. You can still use the Name element to provide a unique campaign name.

Return Additional Fields

The ReturnAdditionalFields element is removed from the GetAdExtensionsAssociations, GetAdExtensionsByIds, GetAdGroupCriterionsByIds, GetAdGroupsByCampaignId, GetAdGroupsByIds, GetAdsByAdGroupId, GetAdsByEditorialStatus, GetAdsByIds, GetCampaignsByAccountId, GetCampaignsByIds, GetKeywordsByAdGroupId, GetKeywordsByEditorialStatus, and GetKeywordsByIds request messages. All elements of each ad, ad extension, ad group, biddable ad group criterion, campaign, and keyword are returned by default.

In parallel the related AdAdditionalField, AdExtensionAdditionalField, AdGroupAdditionalField, AdGroupCriterionAdditionalField, CampaignAdditionalField, and KeywordAdditionalField value sets are removed.

Target Migration Completed

The migration from a shared target to exclusive campaign and ad group target criteria was previously completed. The IsMigrated element is now removed from the response of the AddAdGroupCriterions, UpdateAdGroupCriterions, AddCampaignCriterions, and UpdateCampaignCriterions operations.

New Features

New Bid Strategy Types

The MaxRoasBiddingScheme and TargetRoasBiddingScheme bid strategy types are added for future use in version 13.

Customer Share

The CustomerShare element is added to the Audience and UetTag objects. This element is reserved for future use.

Conversion Goal Exclude From Bidding

The ExcludeFromBidding element is added to the ConversionGoal object. This element is reserved for future use.

Customer Billing

For comprehensive version 13 service reference documentation see Customer Billing.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/Billing/v13.

The production endpoint is https://clientcenter.api.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

The sandbox endpoint is https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

Insertion Order Object

Several properties are added to the InsertionOrder object.

The BalanceAmount element is removed and replaced by the The BudgetRemaining element.

GetInsertionOrdersByAccount is Removed

The GetInsertionOrdersByAccount operation is removed. You can use SearchInsertionOrders in version 13.

Customer Management

For comprehensive version 13 service reference documentation see Customer Management.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/Customer/v13.

The production endpoint is https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

The sandbox endpoint is https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

Several changes are made to the ClientLink object.

Customer Address

In version 13 the CustomerAddress element will be included in all returned Customer objects by default. You do not need to explicitly request this element. The IncludeCustomerAddress element is removed from the GetCustomer and SearchCustomers request messages.

Linked Account Ids

In version 13 the LinkedAccountIds element will be included in all returned CustomerRole objects by default. You do not need to explicitly request this element. The IncludeLinkedAccountIds element is removed from the GetUser request message.

Tax Information for Australia and Brazil

The TaxId and TaxType keys are no longer available when you set account TaxInformation for Australia and Brazil. For Australia use AUGSTNumber as the key and set the value to your tax identifier. For Brazil the possible keys are CCM, CPF, and CNPJ.

Description Version 12 Version 13
Accounts in Australia TaxId=YourTaxId AUGSTNumber=YourTaxId
Business Accounts in Brazil TaxId=YourTaxId;TaxType=Business CPNJ=YourTaxId
Personal Accounts in Brazil TaxId=YourTaxId;TaxType=Personal CPF=YourTaxId

For business accounts within the city of Sao Paulo, Brazil there is no change to the CCM key between versions 12 and 13.

New Features

Customer Role Link Permission

The CustomerLinkPermission element is added to the CustomerRole object. This element is reserved for future use.

Reporting

For comprehensive version 13 service reference documentation see Reporting.

Breaking Changes

Proxy Client

Update your proxy client to use the new endpoint address and namespace.

The target namespace is https://bingads.microsoft.com/Reporting/v13.

The production endpoint is https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

The sandbox endpoint is https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

Required Columns for ProductMatchCountReportRequest

The required columns are updated when submitting the ProductMatchCountReportRequest. In version 13 the AccountName, CampaignName, MatchedProductsAtProductGroup, and ProductGroup columns are required.

Previously in version 12 in addition to the AccountName and CampaignName requirement, one or more of the MatchedProductsAtAdGroup, MatchedProductsAtCampaign, or MatchedProductsAtProductGroup performance statistics columns were required.

Language Report Filter

The LanguageReportFilter value set is added. The LanguageCode (string) element is replaced by the Languages (LanguageReportFilter) element in the following report filters.

All Conversions and Revenue for Goals Report

The Conversions and Revenue columns in the GoalsAndFunnelsReportColumn are renamed AllConversions and AllRevenue respectively. The meaning of the data has not changed from version 12 to 13.

French Report Headers

Support for downloading a report with headers in French is removed. Only English headers are supported in version 13. The Language element is removed from the ReportRequest object, and the ReportLanguage value set is removed.

Removed AgeGenderDemographicReportRequest

The AgeGenderDemographicReportRequest is removed. Instead you can use the AgeGenderAudienceReportRequest.

Search Campaign Type

For Search campaigns, the data returned within the CampaignType column is "Search". In version 12 the value returned was "Search & content". The CampaignType column is available via the AdGroupPerformanceReportColumn, AdPerformanceReportColumn, CampaignPerformanceReportColumn, and SearchQueryPerformanceReportColumn value sets.

Product Group Data Format

The format of the data returned in the ProductGroup column is updated.

Version Description Example
12 Uses "\" (backward slash) to delimit levels.

The attribute values are not surrounded by "" (double quotes).

The category level is appended to the attribute values if applicable e.g., "(1st Level)", "(2nd Level)", etcetera.		 * \ Category=Animals & Pet Supplies(1st Level) \ Category=Pet Supplies(2nd Level) \ Category=Bird Supplies(3rd Level)
13 Uses "/" (forward slash) to delimit levels.

The attribute values are surrounded by "" (double quotes).

Does not indicate the category level e.g., "(1st Level)" is removed.		 * / Category="Animals & Pet Supplies" / Category="Pet Supplies" / Category="Bird Supplies"

This change applies to ProductGroup column via the following values sets.

Dash for Unavailable Quality Score

In version 13 if the quality score was not computed the data returned will be "--" (double dash) in the AdRelevance, ExpectedCtr, HistoricalAdRelevance, HistoricalExpectedCtr, HistoricalLandingPageExperience, HistoricalQualityScore, LandingPageExperience, and QualityScore columns. In version 12 the value of "0" (zero) had been returned. These columns are available in the AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, KeywordPerformanceReportColumn, and ShareOfVoiceReportColumn value sets.

Replaced Some Impression Share Columns

The ImpressionLostToAdRelevancePercent, ImpressionLostToBidPercent, ImpressionLostToExpectedCtrPercent, ImpressionLostToRelevancePercent, and ImpressionLostToRankPercent columns are removed from the AccountPerformanceReportColumn, AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, and ShareOfVoiceReportColumn value sets.

In version 13 the data that had been split between those version 12 columns is aggregated and available via the ImpressionLostToRankAggPercent column which takes all of those factors into account when calculating the impression lost to rank percent.

Removed AverageCpp, ClickCalls, and ManualCalls Columns

The AverageCpp, ClickCalls, and ManualCalls columns are removed from the AccountPerformanceReportColumn, AdGroupPerformanceReportColumn and CampaignPerformanceReportColumn value sets.

Removed CallStatus and CallTypeName Columns

The CallStatus and CallTypeName columns are removed from the CallDetailReportColumn value set. Microsoft Advertising stopped charging for manual calls to a tracked number on March 12, 2014.

Require Account, Campaign, or Ad Group Scope

In version 13 you must scope the request to specific accounts, campaigns, or ad groups. For example you can include up to 1,000 accounts, 300 campaigns, or 300 ad groups via AccountThroughAdGroupReportScope. Previously in version 12 you could leave the report scope null for some report types, and data would be returned for all accounts that you could access.