Skip to main content
O conector Microsoft Advertising (antigo Bing Ads) lê, pela API v13 do Microsoft Advertising, todas as contas de anúncio que uma credencial alcança. Ele traz o cadastro das contas, quem tem acesso a cada uma, as campanhas, grupos de anúncios, anúncios e palavras-chave, e o desempenho diário por conta, campanha, grupo e palavra-chave. Cada linha guarda quem pode vê-la, pela permissão da conta no Microsoft Advertising.

​
Capacidades

  • Lê, numa só conexão, todas as contas que a credencial lista.
  • Traz ao Data Catalog o cadastro de cada conta: campanhas, grupos de anúncios, anúncios de todos os tipos que o download em massa (Bulk) devolve e palavras-chave.
  • Traz, por dia, impressões, cliques, investimento (spend), conversões e receita, em quatro cortes: conta, campanha, grupo de anúncios e palavra-chave.
  • Traz os usuários de cada conta com o papel deles, e usa esses papéis para decidir quem vê cada linha no modo “Espelhar a fonte”.
  • Instala 10 tabelas clean prontas, uma por recurso, com status em minúsculas, horários de alteração em UTC, chaves que já incluem a conta e o dia de cada métrica no fuso da conta.
  • Alimenta o Memory com os nós Agent, AdAccount, AdCampaign, AdGroup, Ad e AdKeyword, ligados na hierarquia da conta, e com cada alteração de campanha como evento de linha do tempo. O Agent pode se unir, pelo e-mail, a pessoas do HubSpot, Slack, ClickUp e Jira. Os nós só entram no grafo depois que a ontologia unificada é aplicada.

​
Recursos disponíveis

As cinco métricas são impressions, clicks, spend, conversions e revenue. Taxas como CTR e CPC médio não entram, porque não se somam entre dias. Você escolhe no Data Catalog quais recursos carregar. O accounts fica sempre ligado, porque todos os outros recursos e a permissão dependem da conta. Os usuários são lidos a cada execução para calcular a permissão, mesmo com users desligado. A tabela só é gravada quando o recurso está ligado.

​
Como ler os dados

  • date é o dia do calendário no fuso da conta, o mesmo corte da interface do Microsoft Advertising. A data não é convertida para UTC. O fuso da conta está em account_time_zone, na tabela clean bing_ads_accounts.
  • spend e revenue ficam na moeda da conta, sem conversão. Toda linha de desempenho traz currency_code. Para somar contas diferentes, agrupe pela moeda.
  • conversions é a contagem de conversões qualificadas. A coluna antiga de conversões do Microsoft Advertising está descontinuada e devolve zero.
  • Dia sem tráfego não gera linha.
  • Na clean, as chaves campaign_key, ad_group_key, ad_key e keyword_key têm a forma <account_id>:<entidade>:<id>. O external_id é o id que a interface do Microsoft Advertising mostra.
  • Em ads, os títulos e as descrições ficam como texto, na lista serializada que a fonte entrega, porque a quantidade varia por tipo de anúncio.

​
Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos: No modo “Espelhar a fonte”, a Strattum reconhece cada pessoa pelo login dela no Microsoft Advertising, o endereço com que ela entra na Microsoft ou no Google. O conector não oferece Exigir login na fonte como prova de identidade. O login só vira acesso quando a instalação da Strattum libera, para esta conexão, a associação por e-mail e cadastra os domínios corporativos aceitos. Com essa liberação, quem entra na Strattum com o mesmo endereço do login vê as contas que esse login acessa no Microsoft Advertising.
Hoje essa liberação não tem tela no Console: quem administra a instalação da Strattum precisa ativá-la para esta conexão. Sem ela, no modo “Espelhar a fonte”, os registros do Microsoft Advertising não aparecem para nenhum usuário. Para liberar o conteúdo agora, use “Aberto” e limite o acesso em Quem pode usar este conector.
O assistente começa com “Espelhar a fonte” selecionado.

​
Como a fonte define acesso

No Microsoft Advertising, cada usuário tem um papel dentro de um cliente (customer). O papel vale para todas as contas do cliente ou para uma lista de contas, e uma agência pode alcançar contas de clientes vinculados. Não existe permissão por campanha, grupo ou anúncio.

​
Como a Strattum traduz o acesso

A permissão é calculada por conta. A cada execução, o conector lê os usuários de cada cliente e o papel de cada um, e monta a lista de logins que acessam cada conta. Toda linha daquela conta, em todos os recursos, recebe essa lista.
  • Um papel sem lista de contas concede todas as contas do cliente. Um papel com lista concede só as contas listadas.
  • As contas de clientes vinculados contam para quem tem acesso pelo vínculo.
  • Um papel restrito ao vínculo (LinkedEntityOnly, ou qualquer valor desconhecido) não concede o cliente inteiro, só as contas listadas e as vinculadas.
  • Só usuário com status Active concede acesso. Usuário pendente, inativo ou excluído continua na tabela users e não concede nada.
  • Papel que o conector não conhece aparece como unknown em users e não concede nada.
  • O conector usa o login (user_name), nunca o e-mail de contato. O e-mail de contato é um campo livre que o próprio usuário edita.

​
Quando a identidade não é encontrada

Login que não é um endereço de e-mail não concede acesso: a linha fica em users, e ninguém recebe a conta por ele. Login de um domínio fora da lista cadastrada para a conexão, como uma conta pessoal da Microsoft, não é associado a nenhum usuário da Strattum. Nos dois casos, as linhas continuam visíveis para os outros logins da conta. Se a credencial não consegue ler os usuários de um cliente, os usuários desse cliente não concedem nada. As contas dele mantêm só o acesso lido por outra via, como o vínculo de uma agência. O teste de conexão avisa quando isso acontece.

​
Quando a permissão é atualizada

A permissão é recalculada em toda execução, antes de qualquer gravação. Em accounts, users, campaigns, ad_groups, ads e keywords, ela sai junto com o dado, porque esses recursos são reescritos por inteiro. Nos quatro recursos de desempenho, o conector compara a permissão de cada conta com a da execução anterior. Quando ela mudou, as linhas da conta são atualizadas em todas as tabelas de desempenho ligadas, inclusive dias que não foram relidos. Uma conta que a credencial deixou de alcançar fica com as linhas de desempenho sem nenhum acesso. Entre duas execuções, vale a permissão da última. A associação entre o login e o usuário da Strattum roda à parte, depois de cada sincronização bem-sucedida e a cada 10 minutos.

​
Pré-requisitos

  • Um usuário do Microsoft Advertising com papel Standard User ou Super Admin nas contas que você quer ler. O papel Viewer basta para os dados, mas não lê os outros usuários, e no modo “Espelhar a fonte” as contas ficam restritas a quem tem acesso por vínculo de agência.
  • Um developer token de produção, gerado por um usuário Super Admin.
  • Um aplicativo OAuth do provedor com que o usuário entra no Microsoft Advertising: um aplicativo do Microsoft Entra, para login Microsoft, ou um cliente OAuth do Google Cloud, para login Google.
  • Uma só conexão Microsoft Advertising por instalação da Strattum. Ela lê todas as contas que a credencial alcança.

​
Autenticação e escopos

A autenticação é OAuth 2.0 delegado, com refresh token. A cada execução, o conector troca o refresh token por um token de acesso, no Microsoft Entra ou no Google, conforme o Provedor de login. Toda chamada à API leva o developer token.

​
Com login Microsoft

1

Registre o aplicativo

No Microsoft Entra, registre um aplicativo com o tipo de conta Any Entra ID Tenant + Personal Microsoft accounts, plataforma web, e crie um client secret. Use um redirect URI próprio: com client secret, a Microsoft recusa o redirect nativeclient.
2

Peça o consentimento

Abra no navegador o endereço de autorização que o assistente mostra, trocando CLIENT_ID e REDIRECT_URI. Entre com o usuário do Microsoft Advertising, aceite e copie o valor do parâmetro code do endereço de retorno.
3

Gere o refresh token

Envie um POST a https://login.microsoftonline.com/common/oauth2/v2.0/token com grant_type=authorization_code, o code, client_id, client_secret, o mesmo redirect_uri e o escopo. Guarde o refresh_token da resposta.
4

Gere o developer token

No Microsoft Advertising, com um usuário Super Admin, abra Configurações e depois Configurações de desenvolvedor, e gere o developer token.

​
Com login Google

1

Crie o cliente OAuth

No Google Cloud Console, crie um cliente OAuth do tipo Web application e cadastre o redirect URI.
2

Peça o consentimento

Abra no navegador o endereço de autorização que o assistente mostra, com os escopos profile e email e acesso offline. Entre com a conta Google usada no Microsoft Advertising, aceite e copie o valor do parâmetro code.
3

Gere o refresh token

Envie um POST a https://oauth2.googleapis.com/token com grant_type=authorization_code, o code, client_id, client_secret e o mesmo redirect_uri. Guarde o refresh_token da resposta.
4

Gere o developer token

No Microsoft Advertising, com um usuário Super Admin, abra Configurações e depois Configurações de desenvolvedor, e gere o developer token.

​
Configuração no Console

1

Abra o assistente

Em Conectores, clique em + Nova Conexão e selecione Microsoft Advertising, em Mídia paga.
2

Preencha a conexão

Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é Microsoft Advertising.Provedor de login (Obrigatório): Microsoft ou Google, conforme a conta com que o usuário entra no Microsoft Advertising. O padrão é Microsoft. O texto de ajuda muda conforme a escolha.Developer token (Obrigatório): o token gerado nas configurações de desenvolvedor.Client ID (Obrigatório): o Client ID do aplicativo do Entra ou do cliente OAuth do Google.Client secret (Obrigatório): o secret do mesmo aplicativo.Refresh token (Obrigatório): o token gerado no consentimento.
3

Teste a conexão

Clique em Testar Conexão. Você só avança depois de um teste com sucesso ou com aviso. O teste troca o refresh token, lista as contas, busca o cliente da primeira conta legível e lista os usuários desse cliente. Ele falha quando a credencial é recusada, quando não há conta acessível e quando a Microsoft não responde. Conecta com aviso quando a credencial só enxerga o próprio usuário, ou não consegue ler os usuários: nesse caso, a permissão fica restrita.
4

Escolha a frequência

Em Sincronização (Obrigatório), escolha uma frequência na lista ou informe um cron. Uma vez por dia basta: os relatórios são diários, e cada execução gasta um download em massa por conta e um relatório por conta e recurso.
5

Defina o acesso

Em Permissionamento, defina Quem pode usar este conector e o Comportamento dos dados. O assistente começa em “Espelhar a fonte”. Antes de mantê-lo, leia Permissões. Se a política de acesso não for salva junto com o conector, o Console avisa com “Política de acesso pendente”.
6

Revise e salve

Em Revisão, confira os dados e salve. O developer token, o client secret e o refresh token aparecem mascarados.
7

Ligue os recursos no Data Catalog

No Data Catalog, ligue os recursos e as tabelas clean que você quer carregar. Nos quatro recursos de desempenho, escolha o modo Incremental na aba Carga: o padrão é full refresh, e a cada execução ele relê 13 meses de relatório de cada conta. Em users, marque email, first_name e last_name como dados pessoais se quiser que virem token.

​
Renovar o refresh token

O conector usa sempre o refresh token que você colou. Quando a Microsoft devolve um token novo na renovação, o conector o descarta e não o salva. Por isso, o refresh token precisa ser colado de novo quando a sincronização acusar credencial inválida.
1

Gere um novo refresh token

Repita o consentimento com o mesmo aplicativo e o mesmo usuário, como em Autenticação e escopos.
2

Cole o token no conector

Em Conectores, abra o Microsoft Advertising e cole o valor em Refresh token. Os campos que você deixa em branco mantêm o valor guardado. Para testar na tela de edição, preencha os quatro campos.
3

Salve

Salve a configuração. A próxima execução já usa o novo token.

​
Como a sincronização funciona

A frequência vem do passo Sincronização. Cada execução segue esta ordem:
  1. Contas. O conector lista as contas da credencial e busca o detalhe de cada uma. Se a lista vier vazia, ou incompleta, a execução falha sem gravar nada.
  2. Permissão. Lê os usuários e os papéis de cada cliente. Qualquer erro nessa leitura falha a execução antes de gravar, para nunca publicar uma permissão incompleta.
  3. accounts e users. São reescritos por inteiro.
  4. Desempenho. Um relatório por conta e recurso ligado, um de cada vez. A Microsoft gera o relatório de forma assíncrona: o conector consulta o andamento a cada 10 segundos, por até uma hora, e baixa o arquivo.
  5. Atualização da permissão nas tabelas de desempenho, quando ela mudou.
  6. Cadastro. Um download em massa completo por conta, com campanhas, grupos, anúncios e palavras-chave, que serve aos quatro recursos. campaigns, ad_groups, ads e keywords são reescritos por inteiro.
  7. Tabelas clean. São recalculadas no fim.
Janela dos relatórios. O último dia pedido é o dia de hoje em UTC. Entre 00:00 e 08:00 UTC, é o dia anterior, porque a Microsoft recusa um fim de período que já é amanhã no fuso padrão dos relatórios dela. O dia mais recente pode vir parcial e é corrigido na execução seguinte.
  • Full refresh e primeira carga: os últimos 13 meses, para todas as contas, inclusive as encerradas.
  • Incremental: para cada conta, os 30 dias que terminam no último dia lido, até hoje. A releitura existe porque a Microsoft revisa números depois do dia, com ajustes de tráfego inválido e conversões tardias. Conta encerrada não recebe pedido novo. Conta sem cursor recebe os 13 meses.
  • Se a Microsoft recusar um período longo, o conector refaz o pedido em blocos de 90 dias.
  • Os dias lidos substituem por inteiro os mesmos dias da conta na tabela. Os outros dias ficam como estão, nos dois modos.
Falha numa conta. No desempenho, uma conta cujo relatório falha antes da primeira linha é pulada, e o cursor dela não avança. As outras seguem. No cadastro, uma conta com acesso negado de forma definitiva sai da gravação, e as linhas dela somem das tabelas. Uma falha passageira, como limite de chamadas ou download que não terminou, interrompe a execução antes de gravar o recurso, e a tabela anterior fica intacta. Como o cadastro é a última etapa, o desempenho já gravado fica na raw, mas as tabelas clean não são recalculadas nessa execução. Remoção. No cadastro, o que some do Microsoft Advertising some da tabela na execução seguinte. No desempenho, nenhum modo remove linhas: os dias já gravados de uma conta que saiu do alcance da credencial continuam na tabela, sem nenhum acesso no modo “Espelhar a fonte”.

​
API da fonte

Os hosts são https://clientcenter.api.bingads.microsoft.com (Customer Management), https://bulk.api.bingads.microsoft.com (Bulk) e https://reporting.api.bingads.microsoft.com (Reporting). Todas as chamadas são de leitura: o conector nunca cria, altera ou apaga nada no Microsoft Advertising. Rate limits. A Microsoft não publica os números. O código 117 (CallRateExceeded) limita as chamadas por cliente numa janela deslizante de 60 segundos, e a Microsoft orienta esperar 60 segundos. O código 4204 limita os pedidos de download em massa por período, e a Microsoft orienta esperar até 15 minutos. O código 207 (ConcurrentRequestOverLimit) limita os relatórios simultâneos, e a Microsoft orienta esperar os anteriores terminarem. O conector faz uma chamada por vez, com tempo limite de 60 segundos. Diante do 117, espera 60 segundos e tenta de novo até 5 vezes. Diante do 4204 ou do 207, espera 15 segundos, dobra a espera a cada tentativa até 2 minutos e desiste depois de 15 minutos de espera somada. Um HTTP 429 espera o Retry-After dentro do mesmo teto de 15 minutos. Erros 5xx têm até 5 tentativas, e falhas de rede até 3. Um token recusado (105, 109 ou 401) é renovado uma vez antes de nova tentativa. Quando o limite persiste, a conta é pulada no desempenho e a execução falha no cadastro, como em Como a sincronização funciona. A execução não tem novas tentativas automáticas. Referência oficial: Bing Ads API Services Protocol, Handle Throttling

​
Limitações conhecidas

  • Nos quatro recursos de desempenho, o padrão é full refresh, que relê 13 meses de cada conta a cada execução. Marque os quatro como Incremental no Data Catalog.
  • Em incremental, uma correção da Microsoft só é capturada enquanto o dia estiver na janela de 30 dias. Para dias mais antigos, rode um full refresh.
  • O conector não salva o refresh token novo que a Microsoft devolve. A Microsoft pode invalidar o refresh token a qualquer momento, por exemplo depois de uma troca de senha ou da retirada do consentimento. Quando a sincronização acusar credencial inválida, gere e cole um novo.
  • Em users, email, first_name e last_name só viram token se você marcar esses campos como dados pessoais no Data Catalog. O login (user_name) fica sempre em claro e travado, porque alimenta a permissão.
  • No modo “Espelhar a fonte”, nenhum registro aparece enquanto a associação por e-mail não for liberada para a conexão, e essa liberação ainda não tem tela no Console.
  • O login do Microsoft Advertising é a identidade da pessoa. Quem entra no Microsoft Advertising com uma conta pessoal, fora do domínio corporativo cadastrado, não é reconhecido na Strattum. Login que não é endereço de e-mail não concede acesso.
  • Não há vínculo de conta: o conector não oferece Exigir login na fonte como prova de identidade.
  • Com uma credencial Viewer, ou sem acesso aos usuários de um cliente, as contas desse cliente ficam visíveis no modo “Espelhar a fonte” só para quem tem acesso por vínculo de agência.
  • Uma conta com mais de 4 milhões de palavras-chave não cabe no download em massa (AccountTooBigToDownload). A execução falha na etapa de cadastro enquanto essa conta estiver no alcance da credencial, e as tabelas clean não são recalculadas. O conector não baixa a conta por campanha.
  • Uma conexão Microsoft Advertising por instalação. O conector lê todas as contas que a credencial alcança, e não há como escolher contas na Strattum.
  • Linhas de desempenho de uma conta que saiu do alcance da credencial continuam na tabela.
  • Uma conta adiantada em relação ao UTC pode ficar sem o dia local corrente até a execução seguinte.
  • Não há conversão de moeda.
  • Ficam de fora termos de pesquisa (search_query_performance), relatórios geográficos, de conversão, por hora, dispositivo ou rede, orçamentos compartilhados, rótulos, metas de conversão, extensões, públicos, Ad Insight e faturamento.
  • O conector usa só o ambiente de produção da Microsoft, não o sandbox.

​
Troubleshooting

​
Próximos passos

Data Catalog

Ligue os recursos e as tabelas clean do Microsoft Advertising e escolha o modo de carga dos relatórios.

Memory

Veja como contas, campanhas, grupos, anúncios, palavras-chave e as pessoas que os operam entram no grafo.
O conector não lê variáveis do .env. As credenciais são informadas no Console e ficam no cofre de segredos da plataforma, sob os nomes BING_ADS_DEVELOPER_TOKEN, BING_ADS_CLIENT_ID, BING_ADS_CLIENT_SECRET, BING_ADS_REFRESH_TOKEN e BING_ADS_IDENTITY_PROVIDER (microsoft ou google; sem ele, vale microsoft). Para testar localmente, crie a conexão pelo Console da stack local.