Introduzione all'API Bing Ads

Qualsiasi utente di Microsoft Advertising con un token di sviluppo può iniziare a usare l'API Bing Ads. Per gli inserzionisti che posizionano un numero elevato di annunci o sviluppatori che creano strumenti pubblicitari, l'API Bing Ads offre un'interfaccia programmatica a 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 aPythonPHP | java C# | | .

Ottenere un token di accesso utente

Si consideri l'utente a cui si vuole accedere, example@contoso.comad esempio . L'API Bing Ads non accetterà l'indirizzo e-mail e la password. È invece necessario impostare l'elemento di intestazione AuthenticationToken che contiene un token di accesso utente. È possibile considerare un token di accesso come 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. Quando un utente fornisce il consenso, è possibile ottenere un token di accesso e agire per conto dell'utente. Il token di accesso rappresenta le credenziali utente che hanno accesso a uno o più account Microsoft Advertising.

1. Registrare un'applicazione

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

3. Ottenere i token di accesso e aggiornamento

4. Effettuare la prima chiamata API

Consiglio

Per informazioni dettagliate su come ottenere l'accesso e aggiornare i token usando gli SDK di Bing Ads, vedere Autenticazione con gli SDK.

Ottenere un token per sviluppatori

Per usare le API Bing Ads, è necessario disporre di un token per sviluppatori 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 separate. È possibile iscriversi per ottenere un account Sandboxqui. Tutti possono usare il token per sviluppatori sandbox universale, ad esempio BBD37VB98.

È possibile seguire questa procedura per ottenere un token di sviluppo per l'ambiente di produzione.

1. Accedere con le credenziali super Amministrazione nella scheda Account del portale per sviluppatori di Microsoft Advertising.
2. Scegliere l'utente che si vuole associare al token di sviluppo. In genere un'applicazione richiede un solo token universale indipendentemente dal numero di utenti supportati.
3. Fare clic sul pulsante Richiedi token .

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

Il token di sviluppo per singolo utente 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 si vede ancora che un singolo token utente è assegnato a uno degli utenti, è possibile selezionare "Aggiorna a universale".

Un token per sviluppatori consente l'accesso a livello di codice agli account consentiti per un utente. Il recupero di un token di sviluppo per l'accesso 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 Advertiser Campaign Manager 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 DELL'API

Quando si chiama un'operazione del 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 usa uno degli SDK di Microsoft Advertising, gli elementi dell'intestazione della richiesta vengono impostati tramite AuthorizationData. Per altre informazioni 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>'
)

Ottenere 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 dell'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 per l'identificatore dell'account. Il numero di account è il numero di account generato dal sistema usato per identificare l'account nell'applicazione Web Microsoft Advertising. Il numero di conto ha il formato xxxxxxxx, dove xxxxxxxx è una serie di otto caratteri alfanumerici. Le richieste del servizio API usano solo l'identificatore dell'account e non usano mai il numero di account.

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

Chiamare GetUser con le credenziali di Microsoft Advertising e DeveloperToken. All'interno di Body impostare UserId nil. La risposta includerà un oggetto User che contiene UserId.

<?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 dell'inserzionista restituito (o account) includerà 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

Vedere Search User Accounts Code Example per un esempio di codice che restituisce gli account per l'utente autenticato corrente.

Riferimento agli elementi di intestazione

Le operazioni del servizio API Bing Ads usano SOAP (Simple Object Access Protocol) per scambiare i messaggi di richiesta e risposta con l'operazione del servizio. Per altre informazioni, vedere Protocollo di Servizi API Ads Bing.

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

Nota

Gli elementi CustomerAccountId e CustomerId non sono applicabili ai servizi Di fatturazione e Gestione clienti.

Elemento	Descrizione	Tipo di dati
ApplicationToken	Questo elemento di intestazione non viene usato e deve essere ignorato.	Stringa
AuthenticationToken	Token di accesso OAuth che rappresenta un utente dell'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 del corpo AccountId quando sono necessari entrambi. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.	Stringa
Customerid	Identificatore del cliente che contiene e possiede l'account. Se si gestisce un account di un altro cliente, è consigliabile usare tale ID cliente anziché il proprio ID cliente. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre.	Stringa
DeveloperToken	Token di sviluppo usato per accedere all'API Bing Ads.	Stringa
Password	Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente.	Stringa
UserName	Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente.	Stringa

Servono altre informazioni?

Per suggerimenti per la risoluzione dei problemi, vedere Gestione di errori ed eccezioni del servizio.

Il forum microsoft Q&A è disponibile per la community di sviluppatori per porre e rispondere a domande sulle API 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 assicurarsi che venga visualizzata la domanda, contrassegnarla con "advertising-api".

Se l'indagine prevede dati personali o account sensibili o se non si trovano le informazioni necessarie per risolvere il problema tramite Microsoft Q&A, contattare il supporto tecnico microsoft per la pubblicità. Per risolvere il problema in modo efficiente, fornire supporto con i dettagli richiesti in Supporto coinvolgente.

Vedere anche

Panoramica dell'API Bing Ads
Concetti relativi all'API Bing Ads