Lingua

Introduzione all'API di Bing Ads

Qualsiasi utente di Microsoft Advertising con un token di sviluppo può iniziare a usare l'API di Bing Ads. Per gli inserzionisti che inseriscono un numero elevato di annunci o gli sviluppatori che creano strumenti pubblicitari, l'API di Bing Ads fornisce un'interfaccia programmatica per Microsoft Advertising.

È possibile sviluppare l'applicazione API Bing Ads in qualsiasi linguaggio che supporti i servizi Web. Per iniziare a usare un SDK specifico, vedere Introduzione a C# | Java | PHP | Python.

Ottenere un token di accesso utente

Considera l'utente a cui desideri accedere, example@contoso.comad esempio . L'API di Bing Ads non accetterà tale indirizzo e-mail e password. È invece necessario impostare l'elemento di intestazione AuthenticationToken che contiene un token di accesso utente. Un token di accesso rappresenta un nome utente e una password.

Come è possibile ottenere un token di accesso per un utente? Gli sviluppatori di applicazioni useranno un URL di autorizzazione Microsoft per richiedere il consenso all'utente di Microsoft Advertising. Una volta che un utente fornisce il consenso, è possibile ottenere un token di accesso e agire per conto dell'utente. Il token di accesso rappresenta le credenziali dell'utente che ha accesso a uno o più account Microsoft Advertising.

  1. Registrare un'applicazione

  2. Richiedere il consenso dell'utente per l'applicazione per gestire i propri account Microsoft Advertising

  3. Ottenere token di accesso e di aggiornamento

  4. Effettuare la prima chiamata API

Consiglio

Per informazioni dettagliate su come ottenere i token di accesso e di aggiornamento tramite gli SDK di Bing Ads, vedere Autenticazione con gli SDK.

Ottenere un token sviluppatore

Per usare le API di Bing Ads, è necessario disporre di un token sviluppatore e di credenziali utente valide. Se non si dispone ancora di un account Microsoft Advertising, è possibile iscriversi tramite l'applicazione Web Microsoft Advertising.

Nota

Gli ambienti sandbox e di produzione usano credenziali distinte. È possibile iscriversi per ottenere un account Sandboxqui. Tutti possono usare il token sviluppatore Universal Sandbox, ad esempio BBD37VB98.

È possibile seguire questa procedura per ottenere un token di sviluppo per la produzione.

Nota

A partire dal 31 maggio 2025, la pagina del portale per sviluppatori verrà deprecata e sostituita con una nuova versione qui. Aggiorna i segnalibri e inizia a usare la nuova pagina per evitare interruzioni. Per domande o assistenza, contatta il supporto tecnico.

  1. Accedere con le credenziali di Amministratore con privilegi avanzati nella scheda account del portale per sviluppatori di Microsoft Advertising.
  2. Scegliere l'utente che si desidera venga associato al token sviluppatore. In genere, un'applicazione necessita di un solo token universale, indipendentemente dal numero di utenti supportati.
  3. Fare clic sul pulsante Richiedi token .

Il token sviluppatore universale può essere usato per eseguire l'autenticazione con qualsiasi credenziale utente di Microsoft Advertising. È possibile utilizzare lo stesso token sviluppatore universale indipendentemente dal fatto che l'applicazione venga utilizzata da uno o più utenti di Microsoft Advertising. A partire da luglio 2019, questo è il tipo di token predefinito.

Il token sviluppatore per utente singolo può essere usato solo per autenticare un utente per l'accesso a un cliente. Questo tipo di token è stato deprecato a favore del token universale. Se a uno dei propri utenti viene ancora assegnato un token utente, è possibile selezionare "Aggiorna a Universale".

Un token sviluppatore abilita l'accesso programmatico agli account autorizzati per un utente. L'ottenimento di un token di sviluppo per l'accesso all'API non concede autorizzazioni aggiuntive ad alcun account Microsoft Advertising. A ogni utente di Microsoft Advertising viene assegnato un ruolo, ad esempio Super Amministrazione o Responsabile delle campagne pubblicitarie per ogni cliente a cui può accedere. Con un token di sviluppo, gli stessi account disponibili nell'applicazione Web Microsoft Advertising sono disponibili per l'utente a livello di codice tramite l'API.

Dove usare le credenziali API

Quando si chiama un'operazione di servizio, ad esempio GetCampaignsByAccountId, è necessario specificare gli elementi dell'intestazione della richiesta , ad esempio DeveloperToken, CustomerId e CustomerAccountId.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
    <Action mustUnderstand="1">GetCampaignsByAccountId</Action>
    <ApplicationToken i:nil="false">ValueHere</ApplicationToken>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
    <CustomerId i:nil="false">ValueHere</CustomerId>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
  </s:Header>
  <s:Body>
    <GetCampaignsByAccountIdRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
      <AccountId>ValueHere</AccountId>
      <CampaignType>ValueHere</CampaignType>
    </GetCampaignsByAccountIdRequest>
  </s:Body>
</s:Envelope>

Se si utilizza uno degli SDK di Microsoft Advertising, gli elementi dell'intestazione della richiesta vengono impostati utilizzando AuthorizationData. Per ulteriori dettagli sulla libreria di autenticazione SDK, vedere Autenticazione con gli SDK.

var authorizationData = new AuthorizationData
{
    Authentication = <AuthenticationGoesHere>, 
    CustomerId = <CustomerIdGoesHere>,
    AccountId = <AccountIdGoesHere>,
    DeveloperToken = "<DeveloperTokenGoesHere>"
};

static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");

$authorizationData = (new AuthorizationData())
    ->withAuthentication($AuthenticationGoesHere)
    ->withCustomerId($CustomerIdGoesHere)
    ->withAccountId($AccountIdGoesHere)
    ->withDeveloperToken($DeveloperTokenGoesHere);

authorization_data = AuthorizationData(
    authentication = <AuthenticationGoesHere>,
    customer_id = <CustomerIdGoesHere>,
    account_id = <AccountIdGoesHere>,
    developer_token = '<DeveloperTokenGoesHere>'
)

Recuperare l'account e gli ID cliente

Per ottenere l'ID cliente e l'ID account di un utente, è possibile accedere all'applicazione Web Microsoft Advertising e fare clic sulla scheda Campagne . L'URL conterrà una coppia chiave/ valore cid nella stringa di query che identifica l'ID cliente e una coppia chiave/valore di aiuto che identifica l'ID account. Ad esempio, https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere& aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.

Consiglio

Non confondere il numero di account con l'identificatore dell'account. Il numero di account è il numero di account generato dal sistema e utilizzato per identificare l'account nell'applicazione Web Microsoft Advertising. Il formato del numero account è xxxxxxxx, dove xxxxxxxx è costituito da una serie di otto caratteri alfanumerici. Le richieste del servizio API utilizzano solo l'identificatore dell'account e non utilizzano mai il numero dell'account.

Con l'API Customer Management è possibile ottenere gli identificatori del cliente e dell'account per ogni utente autenticato.

Chiama GetUser con le credenziali di Microsoft Advertising e DeveloperToken. All'interno del corpo impostare l'ID utente nil. La risposta includerà un oggetto User che contiene l'ID utente.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
  </s:Header>
  <s:Body>
    <GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
      <UserId i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    </GetUserRequest>
  </s:Body>
</s:Envelope>

Chiamare quindi SearchAccounts con l'ID utente restituito tramite il passaggio precedente. L'account o gli account dell'inserzionista restituiti includeranno gli identificatori dell'account e del cliente.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
  </s:Header>
  <s:Body>
    <SearchAccountsRequest xmlns="https://bingads.microsoft.com/Customer/v13">
      <Predicates xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Predicate>
          <a:Field>UserId</a:Field>
          <a:Operator>Equals</a:Operator>
          <a:Value>UserIdGoesHere</a:Value>
        </a:Predicate>
      </Predicates>
      <Ordering i:nil="true" xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
      <PageInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Index>0</a:Index>
        <a:Size>10</a:Size>
      </PageInfo>
    </SearchAccountsRequest>
  </s:Body>
</s:Envelope>

Consiglio

Per un esempio di codice che restituisce gli account per l'utente autenticato corrente, vedere Cerca nell'esempio di codice degli account utente.

Informazioni di riferimento sugli elementi dell'intestazione

Le operazioni del servizio API di Bing Ads utilizzano il protocollo SOAP (Simple Object Access Protocol) per scambiare i messaggi di richiesta e risposta con l'operazione del servizio. Per ulteriori informazioni, vedere Protocollo dei servizi API di Bing Ads.

Ogni richiesta SOAP deve includere le intestazioni SOAP seguenti, che contengono le credenziali dell'utente.

Nota

Gli elementi CustomerAccountId e CustomerId non sono applicabili per i servizi di fatturazione cliente e Gestione clienti.

Elemento Descrizione Tipo di dati
ApplicationToken Questo elemento di intestazione non viene usato e deve essere ignorato. stringa
AuthenticationToken Il token di accesso OAuth che rappresenta un utente di un account Microsoft che dispone delle autorizzazioni per gli account Microsoft Advertising. Per altre informazioni, vedere Autenticazione con OAuth. stringa
CustomerAccountId Identificatore dell'account proprietario delle entità nella richiesta. Questo elemento di intestazione deve avere lo stesso valore dell'elemento corpo AccountId quando sono necessari. Questo elemento è necessario per la maggior parte delle operazioni di servizio e come procedura consigliata è consigliabile impostarlo sempre. stringa
ID cliente Identificatore del cliente che contiene l'account e lo possiede. Se si gestisce l'account di un altro cliente, è consigliabile utilizzare tale ID cliente invece del proprio ID cliente. Questo elemento è necessario per la maggior parte delle operazioni di servizio e come procedura consigliata è consigliabile impostarlo sempre. stringa
DeveloperToken Token di sviluppo usato per accedere all'API di Bing Ads. stringa

Servono altre informazioni?

Per suggerimenti per la risoluzione dei problemi, vedere Gestione degli errori e delle eccezioni del servizio.

Il forum Microsoft Q&A è disponibile per la community di sviluppatori per porre e rispondere a domande sulle API di Bing Ads e sugli script di Microsoft Advertising. Microsoft monitora i forum e risponde alle domande a cui la community non ha ancora risposto.

Importante

Per assicurarti di visualizzare la tua domanda, contrassegnala con "advertising-api".

Se l'indagine riguarda account sensibili o dettagli personali o se non si trovano le informazioni necessarie per risolvere il problema tramite domande&e risposte Microsoft, contattare il supporto tecnico di Microsoft Advertising. Per risolvere il problema in modo efficiente, fornisci supporto con i dettagli richiesti in Supporto coinvolgente.

Vedere anche

Panoramica dell'API di Microsoft Advertising
Concetti relativi all'API di Microsoft Advertising

  • Ultimo aggiornamento: