Protocollo di Servizi API Bing Ads

È possibile scrivere l'applicazione API Bing Ads in qualsiasi linguaggio che supporti i servizi Web. Per ogni servizio Web viene definito un documento WSDL (Web Services Description Language). WsDL definisce le operazioni offerte da un servizio Web e il formato dei messaggi di richiesta e risposta inviati e ricevuti dal client dalle operazioni. I messaggi di richiesta e risposta definiscono i nomi e i tipi di dati scambiati dal client con l'operazione. Per altre informazioni su WSDLs, vedere la specifica WSDL W3C.

API SOAP per Bing Ads

L'API Bing Ads supporta SOAP (Simple Object Access Protocol). Alcuni linguaggi, ad esempio C# e Java, forniscono strumenti che generano classi proxy da WSDL. Se il linguaggio scelto non fornisce uno strumento per generare classi proxy, sarà necessario generare classi proxy personalizzate o buste SOAP. Per generare le classi proxy, è necessario l'indirizzo Web del documento WSDL del servizio che si vuole usare. Gli ambienti sandbox e di produzione di Microsoft Advertising hanno ognuno un indirizzo univoco. Gli indirizzi includono anche il numero di versione di WSDL specifico di una versione principale dell'API Bing Ads. Per gli indirizzi WSDL del servizio sandbox e di produzione della versione più recente dell'API Bing Ads, vedere Indirizzi del servizio Web dell'API Bing Ads.

Ordine degli elementi XML SOAP

Quando si crea un messaggio di richiesta SOAP, l'ordine degli elementi all'interno del corpo SOAP è fondamentale. Gli elementi devono essere nello stesso ordine definito nel linguaggio di descrizione dei servizi Web (WSDL). Se gli elementi necessari non sono in ordine, la chiamata avrà esito negativo. Se gli elementi facoltativi non sono in ordine, la chiamata potrebbe non riuscire o gli elementi verranno ignorati. La sintassi WSDL, che mostra l'ordine corretto degli elementi, è inclusa in ogni messaggio di richiesta, messaggio di risposta e oggetto dati documentato nel contenuto di riferimento. Inoltre, ogni messaggio di richiesta e risposta mostra una busta SOAP di esempio.

Nota

Xml fa distinzione tra maiuscole e minuscole. È necessario usare il caso corretto per i nomi dei valori. I linguaggi di programmazione fortemente tipizzati, ad esempio C#, assicurano di disporre del caso corretto prima di poter essere compilati. Altri linguaggi potrebbero non generare un errore di compilazione se non viene usato il caso corretto; tuttavia, il codice ha esito negativo in fase di esecuzione.

Esito positivo parziale

L'API Bing Ads supporta i completamenti parziali per le operazioni di aggiunta, aggiornamento ed eliminazione; se uno degli oggetti nell'elenco di oggetti che si sta aggiungendo, aggiornando o eliminando ha esito negativo, l'operazione potrebbe avere esito positivo per altri utenti della raccolta. Quando si chiama un'operazione Get che accetta un elenco di identificatori, ad esempio l'operazione GetKeywordsByIds e uno degli identificatori nell'elenco non è valido, l'operazione avrà esito positivo e l'elemento di risposta che corrisponde all'identificatore di richiesta non valido sarà nil.

Aggiornamento parziale

Aggiornamento parziale della gestione della campagna

L'aggiornamento parziale è supportato per la maggior parte, ma non per tutti gli oggetti dati di gestione delle campagne. Ad esempio, quando si aggiorna la proprietà Text di un oggetto ExpandedTextAd , è necessario specificare solo gli elementi Id e Text . Gli elementi di sola lettura, ad esempio lo stato editoriale dell'annuncio, devono essere lasciati null o vuoti. Se non diversamente documentato in modo esplicito, gli elementi facoltativi possono essere lasciati vuoti e le impostazioni esistenti rimangono invariate.

L'aggiornamento parziale non è supportato per le estensioni degli annunci. Tutti gli elementi facoltativi che non vengono inviati con la richiesta di aggiornamento verranno eliminati dalla rispettiva estensione dell'annuncio.

Aggiornamento parziale della gestione dei clienti

Il servizio di gestione clienti esegue un aggiornamento completo delle entità, quindi oltre alle proprietà obbligatorie documentate è necessario fornire valori per tutte le proprietà facoltative che non si desidera essere nil o vuoto.

Nota

Un'eccezione a questa regola è l'elemento ForwardCompatibilityMap di qualsiasi oggetto. Ad esempio, se non fornisci l'elemento ForwardCompatibilityMap di AdvertiserAccount, il servizio non aggiornerà o nullficherà le proprietà che altrimenti sarebbero state rappresentate da coppie chiave-valore.

Archiviare gli identificatori di entità in locale

È consigliabile gestire un archivio locale delle entità dell'account e della campagna. In particolare, dovresti archiviare localmente gli identificatori dei tuoi account, clienti, campagne, gruppi di annunci e parole chiave. La maggior parte delle chiamate richiede l'identificatore dell'entità. Se si archivia l'identificatore, si elimina la chiamata necessaria per ottenere l'identificatore.

Ad esempio, molte delle chiamate di gestione della campagna richiedono un identificatore dell'account. Per ottenere l'identificatore dell'account, è possibile usare il servizio di gestione clienti. Tuttavia, invece di chiamare ripetutamente il servizio, archiviare l'identificatore dell'account in locale, in modo che sia possibile usarlo nelle chiamate successive.

Gestire il sovraccarico associato all'effettuarsi di chiamate al servizio Web

Di seguito sono riportati i costi generali, nel tempo di elaborazione, associati a ogni chiamata al servizio Web.

• Stabilire una connessione HTTPS al servizio Web.
• Autenticazione del nome utente e della password.
• Convalida del token per sviluppatori.

Questi costi si verificano se si elabora un singolo articolo o un set di elementi. Per ridurre al minimo il sovraccarico, in generale, è consigliabile provare a elaborare il numero più elevato possibile di elementi in una chiamata. Ad esempio, invece di chiamare UpdateCampaigns per ogni campagna che vuoi aggiornare, chiamala una sola volta per più campagne che vuoi aggiornare. Per gestire i dati su larga scala, soprattutto se devi aggiungere o aggiornare annunci e parole chiave in più gruppi di annunci o campagne in un account, dovresti usare il servizio Bulk. Il servizio bulk consente di scaricare i dati come file TSV o CSV, modificarli in base alle esigenze e quindi caricare le modifiche. Per altre informazioni sull'uso del servizio bulk, vedere Download e caricamento in blocco.

A causa dei costi associati alla definizione di una connessione a un servizio Web, è necessario mantenere la connessione per tutto il tempo necessario. Ad esempio, se è necessario richiedere più report, usare lo stesso oggetto client del servizio di report per tutte le chiamate alle operazioni del servizio di segnalazione. Chiudere in modo esplicito la connessione quando il servizio non è più necessario.

Gestire la limitazione

La limitazione dell'utilizzo di volumi estremamente elevati consente di mantenere un utilizzo equo per tutti i client Microsoft Advertising.

API Informazioni dettagliate sugli annunci

Per il servizio Ad Insight, la limitazione limita il numero di chiamate all'API che un utente può effettuare in un minuto.

A livello di cliente, il numero di chiamate che un cliente può effettuare ai dati del cliente è limitato tramite un protocollo scorrevole con una finestra di 60 secondi.

Se si supera il limite di chiamate al servizio, verrà visualizzato l'errore seguente:

• Codice errore numerico: 117
• Codice di errore simbolico: CallRateExceeded
• Messaggio: è stato superato il numero di chiamate che è possibile effettuare in un minuto. Ridurre il numero di chiamate effettuate al minuto.

Quando si osserva questo errore, è possibile inviare di nuovo la richiesta entro il limite dopo 60 secondi di attesa.

Bulk API

Il servizio bulk limita il numero di richieste che è possibile effettuare a DownloadCampaignsByAccountIds, DownloadCampaignsByCampaignIds e GetBulkUploadUrl. I dettagli dei limiti del servizio sono interni e soggetti a modifiche.

Se si raggiunge il limite di chiamate al servizio, verrà visualizzato l'errore seguente:

• Codice errore numerico: 4204
• Codice di errore simbolico: BulkServiceNoMoreCallsPermittedForTheTimePeriod
• Messaggio: non saranno consentite altre chiamate di caricamento o download in blocco per questo account per il periodo di tempo corrente. Se è stato raggiunto il limite di caricamento bulk, le operazioni di download bulk potrebbero essere ancora disponibili o viceversa.

Se si osserva questo errore, è possibile inviare di nuovo la richiesta dopo aver atteso fino a 15 minuti. Per altri dettagli, vedere Procedure consigliate per il download bulk e Procedure consigliate per il caricamento bulk.

Si noti anche che il limite di dimensioni per file per il caricamento bulk nell'ambiente di produzione è di 100 MB e fino a 4 milioni di righe. Per Sandbox il limite è di 20.000 righe.

API di gestione della campagna

Per il servizio Gestione campagne, la limitazione limita il numero di chiamate all'API che un utente può effettuare in un minuto.

A livello di cliente, il numero di chiamate che un cliente può effettuare ai dati del cliente è limitato tramite un protocollo scorrevole con una finestra di 60 secondi.

Se si raggiunge il limite di chiamate al servizio, verrà visualizzato l'errore seguente:

• Codice errore numerico: 117
• Codice di errore simbolico: CallRateExceeded
• Messaggio: è stato superato il numero di chiamate che è possibile effettuare in un minuto. Ridurre il numero di chiamate effettuate al minuto.

Quando si osserva questo errore, è possibile inviare di nuovo la richiesta entro il limite dopo 60 secondi di attesa.

API per la creazione di report

Il servizio di report limita il numero di richieste che è possibile effettuare a SubmitGenerateReportRequest. I dettagli dei limiti del servizio sono interni e soggetti a modifiche.

Se si raggiunge il limite di chiamate al servizio, verrà visualizzato l'errore seguente:

• Codice errore numerico: 207
• Codice di errore simbolico: ConcurrentRequestOverLimit
• Messaggio: è già stato raggiunto il numero massimo di richieste di report simultanee. Attendere il completamento dei report precedenti e quindi provare a inviare una nuova richiesta.

Se si osserva questo errore, attendere il completamento dei report precedenti e quindi provare a inviare una nuova richiesta.

Vedere anche

Indirizzi del servizio Web dell'API Bing Ads
Panoramica dell'API Bing Ads