Introdução à API de Anúncios do Bing

  • Artigo

Qualquer utilizador do Microsoft Advertising com um token de programador pode começar a utilizar a API de Anúncios do Bing. Para anunciantes que colocam um grande número de anúncios ou programadores a criar ferramentas de publicidade, a API de Anúncios do Bing fornece uma interface programática para o Microsoft Advertising.

Pode desenvolver a sua aplicação de API de Anúncios do Bing em qualquer idioma que suporte serviços Web. Para começar a utilizar um SDK específico, veja Get Started in C#JavaPHP Python (Introdução aoPythonPHP | em C# | Java | ).

Obter um token de acesso de utilizador

Considere o utilizador que pretende iniciar sessão, por exemplo, example@contoso.com. A API de Anúncios do Bing não aceitará esse endereço de e-mail e palavra-passe. Em vez disso, tem de definir o elemento de cabeçalho AuthenticationToken que contém um token de acesso de utilizador. Pode considerar um token de acesso como representando um nome de utilizador e palavra-passe.

Como pode obter um token de acesso para um utilizador? Enquanto programador de aplicações, irá utilizar um URL de autorização da Microsoft para pedir consentimento ao utilizador do Microsoft Advertising. Assim que um utilizador der consentimento, pode obter um token de acesso e agir em nome do utilizador. O token de acesso representa as credenciais de utilizador que têm acesso a uma ou mais contas do Microsoft Advertising.

  1. Registar uma aplicação

  2. Pedir o consentimento do utilizador para que a sua aplicação faça a gestão das respetivas contas do Microsoft Advertising

  3. Obter tokens de acesso e atualização

  4. Fazer a sua primeira chamada à API

Sugestão

Para obter detalhes sobre como obter tokens de acesso e atualização com os SDKs de Anúncios do Bing, veja Authentication With the SDKs (Autenticação com os SDKs).

Obter um Token de Programador

Para utilizar as APIs de Anúncios do Bing, tem de ter um token de programador e credenciais de utilizador válidas. Se ainda não tiver uma conta do Microsoft Advertising, pode inscrever-se através da aplicação Web Microsoft Advertising.

Nota

O sandbox e os ambientes de produção utilizam credenciais separadas. Pode inscrever-se numa conta do Sandboxaqui. Todos podem utilizar o token de programador de sandbox universal, ou seja, BBD37VB98.

Pode seguir estes passos para obter um token de programador para produção.

  1. Inicie sessão com as credenciais do Super Administração no separador Conta do Portal do Programador do Microsoft Advertising.
  2. Escolha o utilizador que pretende associar ao token de programador. Normalmente, uma aplicação só precisa de um token universal, independentemente do número de utilizadores que serão suportados.
  3. Clique no botão Token de Pedido .

O token de programador universal pode ser utilizado para autenticar com quaisquer credenciais de utilizador do Microsoft Advertising. Pode utilizar o mesmo token de programador universal se a sua aplicação será utilizada por um ou vários utilizadores do Microsoft Advertising. A partir de julho de 2019, este é o tipo de token predefinido.

O token de programador de utilizador único só pode ser utilizado para autenticar um utilizador para aceder a um cliente. Este tipo de token foi preterido a favor do token universal. Se continuar a ver que um único token de utilizador está atribuído a um dos seus utilizadores, pode selecionar "Atualizar para Universal".

Um token de programador permite o acesso programático às contas permitidas para um utilizador. A obtenção de um token de programador para acesso à API não concede permissões adicionais a quaisquer contas do Microsoft Advertising. A cada utilizador do Microsoft Advertising é atribuída uma função, por exemplo, Super Administração ou Gestor de Campanha de Anunciantes para cada cliente a que possa aceder. Com um token de programador, as mesmas contas disponíveis na aplicação Web Microsoft Advertising estão disponíveis para o utilizador através de programação através da API.

Onde Utilizar as Credenciais da API

Quando chama uma operação de serviço como GetCampaignsByAccountId, tem de especificar os elementos do cabeçalho do pedido , como 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 estiver a utilizar um dos SDKs de Publicidade da Microsoft, os elementos do cabeçalho do pedido são definidos com AuthorizationData. Para obter mais detalhes sobre a biblioteca de autenticação do SDK, veja Authentication With the SDKs (Autenticação com os SDKs).

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>'
)

Obter os IDs da Conta e do Cliente

Para obter o ID de cliente e o ID de conta de um utilizador, pode iniciar sessão na aplicação Web Microsoft Advertising e clicar no separador Campanhas . O URL irá conter um par chave/valor cid na cadeia de consulta que identifica o ID do cliente e um par chave/valor de ajuda que identifica o ID da conta. Por exemplo, https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere& aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.

Sugestão

Não confunda o número da conta do identificador da conta. O número da conta é o número de conta gerado pelo sistema que é utilizado para identificar a conta na aplicação Web Microsoft Advertising. O número da conta tem o formulário xxxxxxxx, em que xxxxxxxx é uma série de oito carateres alfanuméricos. Os pedidos do serviço de API utilizam apenas o identificador da conta e nunca utilizam o número da conta.

Com a API de Gestão de Clientes, pode obter os identificadores do cliente e da conta para cada utilizador autenticado.

Chame GetUser com as suas credenciais de Publicidade da Microsoft e DeveloperToken. No Corpo, defina userId nil. A resposta incluirá um objeto Utilizador que contém o 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>

Em seguida, chame SearchAccounts com o UserId devolvido através do passo anterior. A conta do anunciante devolvido (ou contas) incluirá identificadores de conta e 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>

Sugestão

Veja Pesquisar Código de Contas de Utilizador Exemplo de um exemplo de código que devolve contas para o utilizador autenticado atual.

Referência de elementos de cabeçalho

As operações de serviço da API de Anúncios do Bing utilizam o Protocolo SOAP (Simple Object Access Protocol) para trocar as mensagens de pedido e resposta com a operação de serviço. Para obter mais informações, veja Protocolo dos Serviços de API de Anúncios do Bing.

Cada pedido SOAP tem de incluir os seguintes cabeçalhos SOAP, que contêm as credenciais do utilizador.

Nota

Os elementos CustomerAccountId e CustomerId não são aplicáveis aos serviços de Faturação e Gestão de Clientes.

Elemento Descrição Tipo de Dados
ApplicationToken Este elemento de cabeçalho não é utilizado e deve ser ignorado. cadeia
AuthenticationToken O token de acesso OAuth que representa um utilizador da Conta Microsoft que tem permissões para contas do Microsoft Advertising. Para obter mais informações, veja Authentication with OAuth (Autenticação com OAuth). cadeia
CustomerAccountId O identificador da conta que detém as entidades no pedido. Este elemento de cabeçalho tem de ter o mesmo valor que o elemento do corpo AccountId quando ambos são necessários. Este elemento é necessário para a maioria das operações de serviço e, como melhor prática, deve sempre defini-lo. cadeia
CustomerId O identificador do cliente que contém e é o proprietário da conta. Se gerir uma conta de outro cliente, deve utilizar esse ID de cliente em vez do seu próprio ID de cliente. Este elemento é necessário para a maioria das operações de serviço e, como melhor prática, deve sempre defini-lo. cadeia
DeveloperToken O token de programador utilizado para aceder à API de Anúncios do Bing. cadeia
Palavra-passe Este elemento está reservado para utilização interna e será removido de uma versão futura da API. Tem de utilizar o elemento AuthenticationToken para definir credenciais de utilizador. cadeia
Nome de Utilizador Este elemento está reservado para utilização interna e será removido de uma versão futura da API. Tem de utilizar o elemento AuthenticationToken para definir credenciais de utilizador. cadeia

Precisa de Ajuda?

Para obter sugestões de resolução de problemas, veja Handling Service Errors and Exceptions (Processar Erros e Exceções do Serviço).

O fórum Microsoft Q&A está disponível para a comunidade de programadores fazer e responder a perguntas sobre as APIs de Anúncios do Bing e os Scripts de Publicidade da Microsoft. A Microsoft monitoriza os fóruns e responde a perguntas que a comunidade ainda não respondeu.

Importante

Para garantir que vemos a sua pergunta, identifique-a com "advertising-api".

Se a investigação envolver uma conta confidencial ou detalhes pessoais ou se não encontrar as informações necessárias para resolver o problema através do Microsoft Q&A, contacte o Suporte publicitário da Microsoft. Para resolver o problema de forma eficiente, forneça suporte com os detalhes pedidos em Contactar o Suporte.

See Also

Descrição Geral da API de Anúncios do Bing
Conceitos da API de Anúncios do Bing