Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
O que é#
Reads daily performance by campaign (impressions, clicks, cost, conversions) and the list of campaigns from the LinkedIn Marketing API and loads into the Bronze layer.
Supported ingestion modes:
- We pull — We pull the data from your source.
Para que serve#
Bring LinkedIn Ads data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural language question wizard.
Quando usar / quando não usar#
Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plano e permissões#
- Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
- Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
- Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.
Pré-requisitos#
- Uma conta LinkedIn Ads com acesso aos dados que você quer ingerir.
- No LinkedIn Developer Portal, crie um app com o produto Advertising API, autorize-o na conta de anúncios e gere um token OAuth com os escopos r_ads e r_ads_reporting (válido por 60 dias). Informe o ID numérico da conta de anúncios (Campaign Manager) e o token; ele é cifrado (AES-256-GCM) e nunca é exibido de novo.
Credenciais#
Forma de autenticação: Token de acesso colado por você. É cifrado (AES-256-GCM) e nunca é exibido de novo, nem aparece em logs ou mensagens de erro.
Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da connection, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta connection para o cofre externo de credenciais é uma escolha explícita, feita por connection depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.
- Token de acesso (OAuth) (
tokenAcesso) — Access token gerado no Developer Portal (OAuth 2.0 → Token Generator). Expira em 60 dias: gere outro e atualize a connection.
Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).
Campos do formulário#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
adAccountId | ID da conta de anúncios | texto | sim | Número da conta no Campaign Manager (vira urn:li:sponsoredAccount:<id>). |
anoInicio | Ano inicial | número | sim | Início da janela do relatório diário (sem data final = até hoje). |
mesInicio | Mês inicial | número | não | padrão: 1 |
diaInicio | Dia inicial | número | não | padrão: 1 |
tokenAcesso 🔒 | Token de acesso (OAuth) | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Access token gerado no Developer Portal (OAuth 2.0 → Token Generator). Expira em 60 dias: gere outro e atualize a connection. |
Passo a passo#
- No menu Dados → Conexões, use Nova conexão.
- Escolha LinkedIn Ads no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da connection, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a connection salva — a credencial não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Exemplo — teste de conexão#
Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):
# Exemplo sintético (valores fictícios — não são credenciais reais)
adAccountId = act_1234567890
anoInicio = 0
mesInicio = 1
diaInicio = 1
tokenAcesso = •••••• (cifrado — nunca exibido)Resultado esperado#
O Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.
Limites e custos#
- Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
- Carga SaaS: default
batchSize5.000,maxRows200.000 por recurso. - Volume estimado: ~0.2 GB/mês (estimativa de catálogo, não medição).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Segurança#
- Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (
<prefixo>_bronze/_silver/_gold); nunca há vazamento entre workspaces. - Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por connection; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
- Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
- Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).
Erros comuns#
- Credencial recusada (401/403) — o provedor não aceitou a credencial: expirada, revogada ou sem a permissão necessária. Reconecte a fonte (a fonte e o histórico são preservados; não recrie a fonte).
- Limite de requisições (429) — o provedor pediu para esperar. A extração respeita
Retry-Aftere retenta; se repetir, aguarde e reduza a frequência da agenda. - Recurso não encontrado — confira o identificador do recurso (conta, objeto, relatório) e as permissões concedidas.
- Cursor de paginação travado — a extração encerra quando o cursor da API não avança (guarda anti-loop). Se acontecer em runs seguidas, abra um chamado com o suporte informando o conector e o recurso.
- Caminho de registros vazio — a resposta chegou sem registros no lugar esperado. Confira o recurso selecionado e os filtros (período, conta, status) antes de assumir que não há dados.
Troubleshooting#
- Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
- Acompanhe as runs na observabilidade por conector (taxa de erro, p50/p95, freshness).
- Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).
Relacionados#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental por watermark, backfill e checkpoint../pipeline-medalhao.md— camadas Bronze/Silver/Gold e qualidade../agendamento-retry-dlq.md— agendamento, retry/backoff e DLQ../custo-limites-seguranca.md— custo, tetos e segurança por workspace
Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.