Condividi tramite

Eseguire la migrazione alla versione 13

  • Articolo

Nota

L'API Bing Ads versione 12 tramonta a partire dal 31 ottobre 2019.

Le sezioni seguenti descrivono le modifiche apportate all'API Bing Ads dalla versione 12 alla versione 13.

Autenticazione per tutti i servizi

L'endpoint di Microsoft Identity Platform per sviluppatori è ora disponibile. L'endpoint Microsoft Identity Platform consente account aziendali o dell'istituto di istruzione da Azure AD e account Microsoft personali, ad esempio hotmail.com, outlook.com e msn.com. L'endpoint Live Connect consente l'autenticazione solo con account personali.

Anche se la migrazione dall'endpoint Live Connect all'endpoint di Microsoft Identity Platform è indipendente dalla migrazione dalla versione 12 alla versione 13, molti sviluppatori vorrebbero eseguire l'aggiornamento durante lo stesso sprint.

Importante

L'endpoint Live Connect non è più l'approccio consigliato per gli utenti di Microsoft Advertising. Eseguire l'aggiornamento all'endpoint di Microsoft Identity Platform per assicurarsi che l'applicazione possa supportare tutti gli utenti senza problemi o interruzioni del servizio. Solo l'endpoint di Microsoft Identity Platform (v2.0) consente di ottenere token di accesso per autenticare account aziendali e personali tramite l'API Bing Ads.

Informazioni dettagliate sugli annunci

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Ad Insight.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/AdInsight/v13.

L'endpoint di produzione è https://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

L'endpoint sandbox è https://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc.

Spazio dei nomi del contratto dati

In precedenza, nella versione 12, lo spazio dei nomi del contratto dati per alcune entità era diverso dallo spazio dei nomi di destinazione di Ad Insight. Se è stato usato uno degli spazi dei nomi della versione 12 seguenti, è necessario usare https://bingads.microsoft.com/AdInsight/v13 insteaed nella versione 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

I client che codificano la busta SOAP e.g. PHP client che codificano un SoapVar oggetto per DateRangeSearchParameter, sarà necessario eseguire l'aggiornamento allo spazio dei nomi di destinazione di Ad Insight Versione 13, https://bingads.microsoft.com/AdInsight/v13ad esempio .

I client Python SDK di Bing Ads dovranno aggiornare diversi prefissi dello spazio dei nomi per gli oggetti factory client SUDS , ad esempio se è stato usato ns4:DateRangeSearchParameter nell'API Bing Ads versione 12, si userà DateRangeSearchParameter (senza il prefisso 'ns4') nella versione 13. Per informazioni dettagliate su come determinare il prefisso dello spazio dei nomi, vedere Uso di SUDS .

Invio in blocco

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Bulk.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/CampaignManagement/v13.

L'endpoint di produzione è https://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

L'endpoint sandbox è https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc.

Asset di immagini degli annunci reattivi

Le colonne Id multimediale immagine orizzontale, ID multimediale logo orizzontale, ID supporto immagine quadra e ID supporto logo quadrato sono deprecate dal record di annunci reattivi . Saranno comunque visibili nel file di download, anche se poiché verranno rimossi in una versione futura, non è consigliabile accettare dipendenze da queste colonne. Usare invece la colonna Immagini .

Dati sulle prestazioni dell'entità

Il download bulk dei dati sulle prestazioni era in precedenza tramonto nella versione 12. Nella versione 13 il valore EntityPerformanceData del set di valori DataScope viene rimosso dal contratto di servizio. Anche gli oggetti Date e PerformanceStatsDateRange e il set di valori ReportTimePeriod vengono rimossi Se si desidera aggregare i dati per giorno, settimana o mese, è possibile usare l'API Reporting. Per altri dettagli, vedere Guide all'API di creazione report.

Gestione campagna

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Campaign Management.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/CampaignManagement/v13.

L'endpoint di produzione è https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

L'endpoint sandbox è https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc.

Asset di immagini degli annunci reattivi

Gli elementi LandscapeImageMediaId, LandscapeLogoMediaId, SquareImageMediaId e SquareLogoMediaId vengono rimossi dall'oggetto ResponsiveAd . È invece necessario usare l'elemento Images .

Asset di testo degli annunci reattivi

Se è stato usato l'elemento stringa LongHeadline nella versione 12, è consigliabile usare l'elemento LongHeadlineString (stringa) nella versione 13. Il tipo di dati longheadline viene aggiornato da string a AssetLink. Questo collegamento di asset è riservato per uso futuro.

Gli elenchi di collegamenti di asset Titoli e descrizioni vengono aggiunti per un uso futuro.

Paging predefinito per GetMediaMetaDataByAccountId

Se l'elemento PageInfo non viene impostato quando si chiama l'operazione GetMediaMetaDataByAccountId , la pagina defaut Index sarà 0 e la dimensione predefinita sarà 1.000. Nella versione 12 se PageInfo non è stato impostato, verranno restituiti tutti i metadati multimediali nell'account.

Offerta criterio ignorata per tipo di dati non valido

Per entrambe le versioni 12 e 13 durante l'aggiunta e l'aggiornamento di un oggetto BiddableCampaignCriterion, i requisiti del tipo di oggetto CriterionBid derivato variano a seconda del contesto del tipo di oggetto Criterion derivato a cui è associato. Ad esempio, se il criterio ereditato è un criterio ProductScope , è necessario usare un oggetto FixedBid (non un oggetto BidMultiplier).

Nella versione 13 se non si usa l'oggetto Criterion corretto, l'offerta richiesta verrà ignorata: se l'offerta è necessaria, l'operazione avrà esito negativo; Se l'offerta è facoltativa, verrà usata l'offerta predefinita.

Nella versione 12 se non si usa l'oggetto Criterion corretto, l'offerta richiesta sarebbe stata rispettata; tuttavia, quando si recupera l'oggetto in un secondo momento viene restituito il tipo corretto. In altre parole, il tipo di dati impostato non corrisponde al tipo di dati recuperato.

Questa modifica dalla versione 12 alla versione 13 si applica solo ai criteri disponibili a livello di campagna. Per i criteri del gruppo di annunci disponibili per entrambe le versioni 12 e 13, se non usi l'oggetto Criterion corretto, l'offerta richiesta verrà ignorata: se l'offerta è necessaria, l'operazione avrà esito negativo; Se l'offerta è facoltativa, verrà usata l'offerta predefinita.

Offerta parola chiave facoltativa

Quando si chiama l'operazione AddKeywords , l'elemento Bid della parola chiave è facoltativo. In precedenza, nella versione 12, l'offerta era necessaria per aggiungere parole chiave. Se vuoi ereditare l'offerta del gruppo di annunci predefinito per la parola chiave e il tipo di corrispondenza, puoi lasciare vuota la parola chiave bid.

Tipo di corrispondenza parola chiave negativa

L'elemento MatchType di NegativeKeyword è nillable. Se in precedenza si era presa una dipendenza dal valore MatchType predefinito nella versione 12, ad esempio Exact, è necessario impostare in modo esplicito questo elemento obbligatorio nella versione 13.

Origine annunci di ricerca dinamica

L'elemento Source di DynamicSearchAdsSetting è nillable. L'elemento IncludeDynamicSearchAdsSource viene rimosso dai messaggi di richiesta AddCampaigns e UpdateCampaigns . Se si è abilitati per i feed di pagine, nella versione 13 è possibile impostare l'origine.

Descrizione campagna

L'elemento Description viene rimosso dall'oggetto Campaign . È comunque possibile usare l'elemento Name per specificare un nome univoco della campagna.

Restituisce campi aggiuntivi

L'elemento ReturnAdditionalFields viene rimosso da GetAdExtensionsAssociations, GetAdExtensionsByIds, GetAdGroupCriterionsByIds, GetAdGroupsByCampaignId, GetAdGroupsByIds, GetAdsByAdGroupId, GetAdsByEditorialStatus, GetAdsByIds, GetCampaignsByAccountId, GetCampaignsByIds, GetKeywordsByAdGroupId, GetKeywordsByEditorialStatus e GetKeywordsByIds richiede messaggi . Tutti gli elementi di ogni annuncio, estensione dell'annuncio, gruppo di annunci, criterio del gruppo di annunci offerte, campagna e parola chiave vengono restituiti per impostazione predefinita.All elements of each ad, extension, ad group, biddable ad group criterion, campaign, and keyword are returned by default.

In parallelo vengono rimossi i set di valori AdAdditionalField, AdExtensionAdditionalField, AdGroupAdditionalField, AdGroupCriterionAdditionalField, CampaignAdditionalField e KeywordAdditionalField correlati.

Migrazione di destinazione completata

La migrazione da una destinazione condivisa a criteri di destinazione esclusivi per campagne e gruppi di annunci è stata completata in precedenza. L'elemento IsMigrated viene ora rimosso dalla risposta delle operazioni AddAdGroupCriterions, UpdateAdGroupCriterions, AddCampaignCriterions e UpdateCampaignCriterions .

Nuove funzionalità

Nuovi tipi di strategia di offerta

I tipi di strategia di offerta MaxRoasBiddingScheme e TargetRoasBiddingScheme vengono aggiunti per un uso futuro nella versione 13.

Condivisione cliente

L'elemento CustomerShare viene aggiunto agli oggetti Audience e UetTag . Questo elemento è riservato per un uso futuro.

Obiettivo di conversione escludere dall'offerta

L'elemento ExcludeFromBidding viene aggiunto all'oggetto ConversionGoal . Questo elemento è riservato per un uso futuro.

Fatturazione cliente

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Fatturazione del cliente.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/Billing/v13.

L'endpoint di produzione è https://clientcenter.api.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

L'endpoint sandbox è https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc.

Oggetto Insertion Order

All'oggetto InsertionOrder vengono aggiunte diverse proprietà.

L'elemento BalanceAmount viene rimosso e sostituito dall'elemento BudgetRemaining .

GetInsertionOrdersByAccount è stato rimosso

L'operazione GetInsertionOrdersByAccount viene rimossa. È possibile usare SearchInsertionOrders nella versione 13.

Gestione clienti

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Gestione dei clienti.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/Customer/v13.

L'endpoint di produzione è https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

L'endpoint sandbox è https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc.

Vengono apportate diverse modifiche all'oggetto ClientLink .

Indirizzo del cliente

Nella versione 13 l'elemento CustomerAddress verrà incluso in tutti gli oggetti Customer restituiti per impostazione predefinita. Non è necessario richiedere in modo esplicito questo elemento. L'elemento IncludeCustomerAddress viene rimosso dai messaggi di richiesta GetCustomer e SearchCustomers .

ID account collegato

Nella versione 13 l'elemento LinkedAccountIds verrà incluso in tutti gli oggetti CustomerRole restituiti per impostazione predefinita. Non è necessario richiedere in modo esplicito questo elemento. L'elemento IncludeLinkedAccountIds viene rimosso dal messaggio di richiesta GetUser .

Informazioni fiscali per Australia e Brasile

Le chiavi TaxId e TaxType non sono più disponibili quando si imposta l'account TaxInformation per Australia e Brasile. Per l'Australia usare AUGSTNumber come chiave e impostare il valore sull'identificatore fiscale. Per il Brasile le possibili chiavi sono CCM, CPF e CNPJ.

Descrizione Versione 12 Versione 13
Account in Australia TaxId=YourTaxId AUGSTNumber=YourTaxId
Account aziendali in Brasile TaxId=YourTaxId; TaxType=Business CPNJ=YourTaxId
Account personali in Brasile TaxId=YourTaxId; TaxType=Personal CPF=YourTaxId

Per gli account aziendali all'interno della città di San Paolo, brasile non c'è alcuna modifica alla chiave CCM tra le versioni 12 e 13.

Nuove funzionalità

Autorizzazione per il collegamento al ruolo del cliente

L'elemento CustomerLinkPermission viene aggiunto all'oggetto CustomerRole . Questo elemento è riservato per un uso futuro.

Creazione di report

Per la documentazione di riferimento completa sulla versione 13 del servizio, vedere Creazione di report.

Modifiche di rilievo

Proxy Client

Aggiornare il client proxy per usare il nuovo indirizzo e lo spazio dei nomi dell'endpoint.

Lo spazio dei nomi di destinazione è https://bingads.microsoft.com/Reporting/v13.

L'endpoint di produzione è https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

L'endpoint sandbox è https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc.

Colonne necessarie per ProductMatchCountReportRequest

Le colonne necessarie vengono aggiornate durante l'invio di ProductMatchCountReportRequest. Nella versione 13 sono necessarie le colonne AccountName, CampaignName, MatchedProductsAtProductGroup e ProductGroup.

In precedenza nella versione 12, oltre al requisito AccountName e CampaignName, erano necessarie una o più colonne delle statistiche sulle prestazioni MatchedProductsAtAdGroup, MatchedProductsAtCampaign o MatchedProductsAtProductGroup.

Filtro report lingua

Viene aggiunto il set di valori LanguageReportFilter . L'elemento LanguageCode (stringa) viene sostituito dall'elemento Languages (LanguageReportFilter) nei filtri del report seguenti.

Report Tutte le conversioni e i ricavi per gli obiettivi

Le colonne Conversions e Revenue in GoalsAndFunnelsReportColumn vengono rinominate rispettivamente AllConversions e AllRevenue . Il significato dei dati non è cambiato dalla versione 12 alla versione 13.

Intestazioni del report francese

Il supporto per il download di un report con intestazioni in francese viene rimosso. Solo le intestazioni in inglese sono supportate nella versione 13. L'elemento Language viene rimosso dall'oggetto ReportRequest e il set di valori ReportLanguage viene rimosso.

Rimozione di AgeGenderDemographicReportRequest

L'oggetto AgeGenderDemographicReportRequest viene rimosso. È invece possibile usare AgeGenderAudienceReportRequest.

Tipo di campagna di ricerca

Per le campagne di ricerca, i dati restituiti all'interno della colonna CampaignType sono "Search". Nella versione 12 il valore restituito era "Cerca contenuto &". La colonna CampaignType è disponibile tramite i set di valori AdGroupPerformanceReportColumn, AdPerformanceReportColumn, CampaignPerformanceReportColumn e SearchQueryPerformanceReportColumn .

Formato dei dati del gruppo di prodotti

Il formato dei dati restituiti nella colonna ProductGroup viene aggiornato.

Versione Descrizione Esempio
12 Usa "\" (barra all'indietro) per delimitare i livelli.

I valori dell'attributo non sono racchiusi tra "" (virgolette doppie).

Il livello di categoria viene aggiunto ai valori dell'attributo, se applicabile, ad esempio "(1st Level)", "(2nd Level)" e così via.		 * \ Category=Animals & Pet Supplies(1st Level) \ Category=Pet Supplies(2nd Level) \ Category=Bird Supplies(3rd Level)
13 Usa "/" (barra in avanti) per delimitare i livelli.

I valori dell'attributo sono racchiusi tra "" (virgolette doppie).

Non indica il livello di categoria, ad esempio "(1° livello)" è stato rimosso.		 * / Category="Animals & Pet Supplies" / Category="Pet Supplies" / Category="Bird Supplies"

Questa modifica si applica alla colonna ProductGroup tramite i set di valori seguenti.

Trattino per punteggio di qualità non disponibile

Nella versione 13 se il punteggio di qualità non è stato calcolato, i dati restituiti saranno "--" (doppio trattino) nelle colonne AdRelevance, ExpectedCtr, HistoricalAdRelevance, HistoricalExpectedCtr, HistoricalLandingPageExperience, HistoricalQualityScore, LandingPageExperience e QualityScore. Nella versione 12 era stato restituito il valore "0" (zero). Queste colonne sono disponibili nei set di valori AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, KeywordPerformanceReportColumn e ShareOfVoiceReportColumn .

Sostituito alcune colonne di condivisione impressioni

I set di valori ImpressionLostToAdRelevancePercent, ImpressionLostToBidPercent, ImpressionLostToExpectedCtrPercent, ImpressionLostToRelevancePercent e ImpressionLostToRankPercent vengono rimossi dai set di valori AccountPerformanceReportColumn, AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn e ShareOfVoiceReportColumn .

Nella versione 13 i dati divisi tra le colonne della versione 12 vengono aggregati e disponibili tramite la colonna ImpressionLostToRankAggPercent, che tiene conto di tutti questi fattori durante il calcolo dell'impressione persa nella percentuale di classificazione.

Rimosse le colonne AverageCpp, ClickCalls e ManualCalls

Le colonne AverageCpp, ClickCalls e ManualCalls vengono rimosse dai set di valori AccountPerformanceReportColumn, AdGroupPerformanceReportColumn e CampaignPerformanceReportColumn .

Colonne CallStatus e CallTypeName rimosse

Le colonne CallStatus e CallTypeName vengono rimosse dal set di valori CallDetailReportColumn . Microsoft Advertising ha interrotto l'addebito per le chiamate manuali a un numero tracciato il 12 marzo 2014.

Richiedi ambito account, campagna o gruppo di annunci

Nella versione 13 devi definire l'ambito della richiesta per account, campagne o gruppi di annunci specifici. Ad esempio, puoi includere fino a 1.000 account, 300 campagne o 300 gruppi di annunci tramite AccountThroughAdGroupReportScope. In precedenza nella versione 12 era possibile lasciare null l'ambito del report per alcuni tipi di report e i dati verrebbero restituiti per tutti gli account a cui è possibile accedere.