Idioma
Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Qualquer utilizador do Microsoft Advertising com um token de programador pode começar a utilizar a API Bing Ads. Para anunciantes que colocam um grande número de anúncios ou desenvolvedores que criam ferramentas de publicidade, a API Bing Ads fornece uma interface programática para o Microsoft Advertising.
Você pode desenvolver seu aplicativo da API Bing Ads em qualquer idioma que ofereça suporte a serviços Web. Para começar com um SDK específico, consulte Introdução ao C# | Java | PHP | Python.
Obter um token de acesso de utilizador
Considere o utilizador que pretende iniciar sessão, por exemplo. example@contoso.com A API Bing Ads não aceitará esse endereço de email e senha. Em vez disso, você precisa definir o elemento de cabeçalho AuthenticationToken que contém um token de acesso de usuário. Pode considerar que um token de acesso representa um nome de utilizador e uma palavra-passe.
Como você pode obter um token de acesso para um usuário? Como programador de aplicações, utilizará um URL de autorização da Microsoft para pedir o consentimento do utilizador do Microsoft Advertising. Assim que um utilizador der o seu consentimento, pode obter um token de acesso e agir em nome do utilizador. O token de acesso representa as credenciais do utilizador que tem acesso a uma ou mais contas do Microsoft Advertising.
Pedir o consentimento do utilizador para que a sua aplicação faça a gestão das contas do Microsoft Advertising
Sugestão
Para obter detalhes sobre como obter acesso e atualizar tokens usando os SDKs do Bing Ads, consulte Autenticação com os SDKs.
Obter um token de programador
Para usar as APIs do Bing Ads, você deve ter um token de desenvolvedor e credenciais de usuário válidas. Se ainda não tiver uma conta Microsoft Advertising, pode inscrever-se através da aplicação Web Microsoft Advertising.
Nota
Os ambientes de sandbox e produção usam credenciais separadas. Você pode se inscrever para uma conta Sandboxaqui. Todos podem usar o token de desenvolvedor do sandbox universal, ou seja, BBD37VB98.
Você pode seguir estas etapas para obter um token de desenvolvedor para produção.
Nota
A partir de 31 de maio de 2025, a página do Portal do Programador será preterida e substituída por uma nova versão aqui. Atualize os seus marcadores e comece a utilizar a nova página para evitar quaisquer interrupções. Para esclarecer qualquer dúvida ou obter ajuda, contacte o Suporte.
- Inicie sessão com as credenciais Super Administração no separador da conta do Portal do Programador do Microsoft Advertising.
- Selecione o utilizador que pretende associar ao token de programador. Normalmente, um aplicativo só precisa de um token universal, independentemente de quantos usuários serão suportados.
- Clique no botão Token de solicitação .
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 quer a sua aplicação seja utilizada por um ou múltiplos utilizadores do Microsoft Advertising. Desde julho de 2019, este é o tipo de token predefinido.
O token de desenvolvedor de usuário único só pode ser usado para autenticar um usuário para acesso a um cliente. Esse tipo de token foi preterido em favor do token universal. Se você ainda ver que um único token de usuário está atribuído a um de seus usuários, poderá selecionar "Atualizar para Universal".
Um token de programador permite o acesso programático às contas permitidas por 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 Campanhas do Anunciante, para cada cliente a que pode aceder. Com um token de programador, as mesmas contas disponíveis na aplicação Web do Microsoft Advertising estão disponíveis para o utilizador através de programação através da API.
Onde usar as credenciais da API
Ao chamar uma operação de serviço como GetCampaignsByAccountId, você deve especificar elementos de cabeçalho de solicitação , 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 do Microsoft Advertising, os elementos de cabeçalho do pedido são definidos através de AuthorizationData. Para obter mais detalhes sobre a biblioteca de autenticação do SDK , consulte 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 a sua conta e IDs de 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 de conta com o identificador da conta. O número de conta é o número de conta gerado pelo sistema que é utilizado para identificar a conta na aplicação Web Microsoft Advertising. O número de conta tem a forma xxxxxxxx, em que xxxxxxxx é uma série de oito carateres alfanuméricos. As solicitações de serviço de API usam apenas o identificador da conta e nunca usam o número da conta.
Com a API de Gestão de Clientes, pode obter os identificadores de cliente e de conta de cada utilizador autenticado.
Ligue para GetUser com suas credenciais do Microsoft Advertising e DeveloperToken. Dentro do corpo, defina o UserId nulo. A resposta incluirá um objeto User 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 retornado através da etapa anterior. A conta (ou contas) do anunciante devolvida incluirá os identificadores de conta e de 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
Consulte Pesquisar exemplo de código de contas de usuário para obter um exemplo de código que retorna contas para o usuário autenticado atual.
Referência de elementos de cabeçalho
As operações de serviço da API do Bing Ads usam o protocolo SOAP (Simple Object Access Protocol) para trocar as mensagens de solicitação e resposta com a operação do serviço. Para obter mais informações, consulte Protocolo de serviços de API do Bing Ads.
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 do Cliente.
| 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, consulte Autenticação com OAuth. | cadeia |
| CustomerAccountId | O identificador da conta proprietária das entidades no pedido. Esse elemento de cabeçalho deve ter o mesmo valor que o elemento de corpo AccountId quando ambos forem necessários. Este elemento é obrigatório para a maioria das operações de serviço e, como prática recomendada, deve defini-lo sempre. | cadeia |
| IDDoCliente | 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 é obrigatório para a maioria das operações de serviço e, como prática recomendada, deve defini-lo sempre. | cadeia |
| DeveloperToken | O token de desenvolvedor usado para acessar a API do Bing Ads. | cadeia |
Precisa de Ajuda?
Para obter dicas de solução de problemas, consulte Lidando com erros e exceções de serviço.
O fórum Microsoft Q&A está disponível para a comunidade de desenvolvedores fazer e responder perguntas sobre as APIs do Bing Ads e os Scripts do Microsoft Advertising. A Microsoft monitoriza os fóruns e responde a perguntas às quais a comunidade ainda não respondeu.
Importante
Para ter certeza de que vemos sua pergunta, marque-a com "advertising-api".
Se a investigação envolver detalhes pessoais ou de conta confidenciais, ou se não encontrar as informações necessárias para resolver o problema através das Perguntas e Respostas&da Microsoft, contacte o Suporte do Microsoft Advertising. Para resolver o problema de forma eficiente, forneça suporte com os detalhes solicitados em Contratar suporte.