Confluence para data warehouse: sincronização automática de espaços, páginas e tarefas
Sincronize espaços, páginas, labels e tarefas do Confluence com BigQuery, Redshift ou PostgreSQL usando o novo conector da Erathos.
A Erathos lança um conector gerenciado para Confluence. Sessenta e três endpoints disponíveis, dez destinos suportados, zero código de pipeline para escrever ou manter.
O Confluence expõe uma REST API autenticada com um token de API da Atlassian, o que faz uma extração construída internamente parecer barata à primeira vista. Na prática, isso significa escrever e manter um pipeline customizado para lidar com paginação por cursor, rate limits que variam por método e corpos de página que chegam como JSON aninhado em Atlassian Document Format. A Erathos resolve essa integração como serviço gerenciado, sem código customizado para o seu time escrever ou manter.
Todo time de dados que sustenta uma operação que roda no Confluence esbarra na mesma parede: a documentação, as decisões e os action items que fazem o trabalho avançar ficam presos no wiki, o resto do stack analítico vive no warehouse, e juntar os dois se torna um projeto de engenharia que ninguém planejou. O que começa como um script Python num cron job se transforma, três meses depois, em um pipeline que ninguém entende, que falha em silêncio e que nenhum engenheiro quer herdar.
O problema dos pipelines de Confluence construídos à mão
A REST API do Confluence Cloud autentica com um token de API da Atlassian via Basic authentication, e os endpoints de listagem retornam resultados paginados por cursor, expostos nos links da resposta. O padrão é simples o suficiente para convencer qualquer engenheiro a construir uma integração em uma tarde. O custo real aparece depois, e é previsível.
Expansão que multiplica o volume de chamadas. Cada recurso filho vive atrás de uma chamada própria: um único registro de página exige buscar versões, labels, comentários de rodapé e inline, likes, propriedades e endpoints de hierarquia, um por um. Um erro na lógica de iteração não levanta exceção: o pipeline simplesmente para de buscar resultados antigos e continua reportando sucesso.
Recursos aninhados que nunca são sincronizados. Para materializar uma página por completo, é preciso ter a página, as versões e labels dela, os comentários de rodapé com respostas, likes e versões próprios, além dos attachments com labels e versões próprios. Um pipeline feito à mão tende a sincronizar as tabelas de nível superior e pular o resto em silêncio, e o warehouse acaba com páginas sem histórico de versões e comentários sem respostas.
Rate limits da Atlassian. O Confluence Cloud aplica rate limits por método, e um backfill histórico em muitos espaços rapidamente esbarra em respostas com throttle. Se a lógica de retry não respeitar os limites com backoff, janelas inteiras de dados são perdidas sem que nenhum erro apareça.
Conteúdo que nunca para de mudar. Páginas são editadas constantemente, comentários são adicionados e resolvidos, attachments são substituídos. Um sync baseado apenas no registro da página não revisita nada disso, então linhas desatualizadas se acumulam em silêncio ao lado das recentes, e o dashboard nunca sabe qual é qual.
Corpos como JSON aninhado. Os corpos de páginas e posts de blog chegam em Atlassian Document Format, um JSON aninhado cuja forma varia conforme o conteúdo: macros, tabelas, menções e painéis, cada um produz uma estrutura diferente. Achatar isso em colunas é um projeto à parte, e quando a Atlassian lança um novo tipo de conteúdo, o modelo dbt que rodava limpo começa a falhar em produção, ou pior, continua rodando com um null onde antes havia uma coluna.
Permissões atreladas a uma conta. O token de API herda as permissões da conta Atlassian que o gerou. Quando essa conta perde acesso a um espaço, o espaço simplesmente deixa de aparecer no próximo sync sem nenhum erro: o pipeline continua verde e o warehouse fica menor.
Observabilidade que não existe. Uma resposta 200 não significa que os dados chegaram completos. Sem contagem de registros por endpoint por execução, comparação com a janela anterior e alertas de queda de volume, você voa às cegas. O pipeline que rodou com sucesso pode ter trazido metade do site porque um espaço saiu do alcance do token.
O pior cenário não é o pipeline que quebra e dispara um alerta. É o pipeline que executa com sucesso e entrega dados errados, e a métrica de conteúdo desatualizado que sobe para o dashboard do time já foi calculada sobre uma base incompleta.
O que você pode fazer quando os dados do Confluence chegam ao seu warehouse
Antes de detalhar o conector, vale documentar o que você realmente ganha quando os espaços, páginas e tarefas que o seu time escreve todos os dias saem do SaaS e passam a ser modelados junto com o resto do seu stack.
Um inventário de conteúdo que responde qual documentação está desatualizada
Com spaces, pages, blogposts e pages_versions no warehouse, você mede páginas por espaço, páginas intocadas há meses, concentração de autoria e profundidade da árvore de páginas. A busca nativa do Confluence e os relatórios de espaço respondem onde uma página está; só as tabelas brutas no warehouse respondem quais espaços deixaram de ser mantidos no último trimestre e de quem são as páginas que ninguém atualizou.
Contribuição por time, cruzada com a organização
pages_versions carrega authorId e createdAt de cada edição. Cruzada no warehouse com uma base de colaboradores de RH ou com a sua product analytics, a documentação se torna mensurável: quais times escrevem, quem revisa, se novos autores passam a contribuir depois de uma mudança no onboarding e se a reescrita de um espaço de documentação coincidiu com um lançamento de produto. Esse join só existe quando o Confluence e os dados da organização compartilham o mesmo banco de dados.
Documentação cruzada com dados de suporte e produto
Runbooks e release notes vivem no Confluence; incidentes e tickets vivem nas suas ferramentas de suporte; o uso de funcionalidades vive na product analytics. Com tudo no mesmo warehouse, você pode testar, por exemplo, se páginas sobre uma funcionalidade são atualizadas depois do lançamento dela, ou se runbooks de incidentes foram alterados nas semanas anteriores a uma queda no tempo de resposta. A análise nativa do Confluence nunca cruza esses sistemas; o warehouse cruza.
Governança e histórico de acesso para auditorias
space_permissions, space_roles, space_permission_assignments, space_role_assignments e classification_levels materializados a cada execução acumulam um rastro histórico de quem podia acessar qual espaço e sob qual nível de classificação. Revisões de segurança e auditorias de compliance exigem um histórico point-in-time que consultas pontuais à API não preservam; um full refresh chegando ao warehouse todos os dias preserva.
Acompanhamento dos action items
Tasks são o único objeto do Confluence neste conector com sync incremental, cursor baseado em createdAt. Com tasks, comentários e likes no warehouse, você mede taxa de conclusão por responsável, itens atrasados por time e se decisões registradas em páginas realmente se tornam follow-ups concluídos. O Confluence nativo mostra cada task no contexto; o warehouse agrega todas em todos os espaços e cruza com dados de CRM ou de projetos.
Uma taxonomia de conhecimento que você consegue consultar de verdade
labels, label_pages, label_blogposts e label_attachments permitem auditar a taxonomia de labels como dados: quais labels concentram conteúdo, quais labels duplicados o fragmentam e quanto conteúdo não carrega label nenhum. Times que rodam enterprise search ou constroem assistentes internos de conhecimento precisam exatamente dessa tabela no próprio warehouse para sustentar o retrieval nos seus próprios termos, em vez de depender do grafo nativo do fornecedor.
O que está disponível no conector
O conector Confluence entrega sessenta e três endpoints prontos para serem materializados no seu warehouse de destino:
Endpoint | O que contém |
|---|---|
spaces | Todos os espaços do site, com chave, nome, tipo, status, autor, homepage, descrição e ícone |
space_detail | O registro completo de cada espaço, adicionando labels, propriedades, operações, permissões e atribuições de papéis aos campos base |
space_labels | Labels aplicados a cada espaço, com prefixo e nome |
space_operations | Operações permitidas em cada espaço e seus tipos de destino |
space_permission_assignments | Atribuições de permissão em cada espaço, com o principal detentor de cada uma |
space_properties | Propriedades customizadas armazenadas em cada espaço, com versão e links |
space_role_assignments | Atribuições de papéis em cada espaço, com o principal detentor de cada papel |
spaces_blogposts | Posts de blog publicados em cada espaço, com título, autor, proprietário, data de criação e versão |
spaces_content_labels | Labels aplicados ao conteúdo de cada espaço |
spaces_pages | Páginas que pertencem a cada espaço, com página pai, posição, autor, proprietário e data de criação |
pages | Todas as páginas do site, com espaço, página pai, posição, autor, proprietário, data de criação e versão |
pages_attachments | Arquivos anexados a cada página, com tipo de mídia, tamanho do arquivo, autor e comentário |
pages_footer_comments | Comentários de rodapé deixados em cada página, com corpo, autor e data de criação |
pages_inline_comments | Comentários inline feitos no conteúdo da página, com propriedades resolvidas |
pages_direct_children | Páginas filhas de primeiro nível de cada página |
pages_children | Páginas filhas de cada página |
pages_ancestors | A cadeia de ancestrais de cada página, até a raiz do espaço |
pages_descendants | Todas as páginas descendentes abaixo de cada página |
page_labels | Labels aplicados a cada página |
pages_versions | Histórico de versões de cada página, com número da versão, mensagem de edição e autor de cada versão |
page_likes_count | Contagem de likes de cada página |
page_likes_users | Usuários que deram like em cada página, com conta, e-mail e dados de perfil |
page_properties | Propriedades customizadas armazenadas em cada página, com versão |
page_operations | Operações permitidas em cada página e seus tipos de destino |
page_detail | O registro completo de cada página, adicionando corpo, labels, propriedades, operações, likes e versões aos campos base |
blogposts | Todos os posts de blog do site, com espaço, autor, proprietário, data de criação e versão |
blogposts_attachments | Arquivos anexados a cada post de blog, com tipo de mídia, tamanho do arquivo, autor e comentário |
blogposts_footer_comments | Comentários de rodapé deixados em cada post de blog, com corpo, autor e data de criação |
blogposts_inline_comments | Comentários inline feitos no conteúdo de posts de blog, com propriedades resolvidas |
blogpost_labels | Labels aplicados a cada post de blog |
blogpost_versions | Histórico de versões de cada post de blog, com número da versão, mensagem de edição e autor de cada versão |
blogpost_likes_count | Contagem de likes de cada post de blog |
blogpost_likes_users | Usuários que deram like em cada post de blog, com conta, e-mail e dados de perfil |
blogpost_properties | Propriedades customizadas armazenadas em cada post de blog, com versão |
blogpost_operations | Operações permitidas em cada post de blog e seus tipos de destino |
blogpost_detail | O registro completo de cada post de blog, adicionando corpo, labels, propriedades, operações, likes e versões aos campos base |
attachments | Todos os arquivos anexados a páginas e posts de blog, com tipo de mídia, tamanho do arquivo, autor e comentário |
attachments_labels | Labels aplicados a cada attachment |
attachment_versions | Histórico de versões de cada attachment, com número da versão e autor |
attachments_footer_comments | Comentários de rodapé deixados em cada attachment, com corpo e autor |
attachment_properties | Propriedades customizadas armazenadas em cada attachment, com versão |
attachment_operations | Operações permitidas em cada attachment e seus tipos de destino |
attachment_detail | O registro completo de cada attachment, adicionando labels, propriedades, operações, versões e colaboradores aos campos base |
labels | Todos os labels do site, com prefixo e nome |
label_pages | Páginas que carregam cada label |
label_blogposts | Posts de blog que carregam cada label |
label_attachments | Attachments que carregam cada label |
footer_comments | Todos os comentários de rodapé em páginas e posts de blog, com corpo, autor e data de criação |
footer_comment_children | Respostas aninhadas sob cada comentário de rodapé |
footer_comment_likes_users | Usuários que deram like em cada comentário de rodapé, com conta e dados de perfil |
footer_comment_likes_count | Contagem de likes de cada comentário de rodapé |
footer_comment_versions | Histórico de versões de cada comentário de rodapé, com número da versão e autor |
footer_comment_operations | Operações permitidas em cada comentário de rodapé e seus tipos de destino |
inline_comments | Todos os comentários inline em conteúdo de páginas e posts de blog, com corpo, autor e propriedades resolvidas |
inline_comment_children | Respostas aninhadas sob cada comentário inline |
inline_comment_likes_users | Usuários que deram like em cada comentário inline, com conta e dados de perfil |
inline_comment_likes_count | Contagem de likes de cada comentário inline |
inline_comment_versions | Histórico de versões de cada comentário inline, com número da versão e autor |
inline_comment_operations | Operações permitidas em cada comentário inline e seus tipos de destino |
classification_levels | Níveis de classificação de dados definidos para o site, com nome e descrição |
space_permissions | Permissões de espaço em todo o site, com principal e tipo de permissão |
space_roles | Papéis de espaço definidos no site, com chaves e permissões incluídas |
tasks | Tasks criadas em páginas, posts de blog e comentários inline, com status, corpo, responsável, data de vencimento e data de conclusão; o único endpoint com sync incremental, cursor baseado em createdAt |
Sessenta e dois endpoints operam em full refresh, o que se adequa às tabelas de conteúdo e configuração que são sempre relidas por completo. Tasks é o único endpoint com sync incremental, cursor baseado em createdAt. Os relacionamentos entre entidades chegam preservados no destino: spaces pai dos seus details, labels, permissions, pages e blog posts; pages pai de attachments, comentários, versões, likes e hierarquia; blog posts pai dos seus próprios attachments, comentários e engajamento; labels pai do conteúdo que os carrega; comentários de rodapé e inline pais de respostas, likes e versões.
Como autenticar
- Site: o subdomínio do seu site Confluence, por exemplo mycompany se você acessa o Confluence em mycompany.atlassian.net
- Token: o seu token de API da Atlassian, usado para autenticar todas as requisições à API do Confluence junto com o e-mail da sua conta Atlassian
- Onde encontrar o token: acesse id.atlassian.com/manage-profile/security/api-tokens, clique em Create API token, dê um nome como Erathos e copie o valor na hora, pois ele é exibido apenas uma vez
- Requisito de acesso: a conta Atlassian usada para gerar o token precisa ter acesso ao site do Confluence que você quer sincronizar, porque o token herda as permissões dessa conta
Na plataforma Erathos, preencha o campo Site com o seu subdomínio e cole o token no campo Token, depois clique em Save and close para concluir a configuração. O processo completo está documentado em https://docs.erathos.com/connectors/apis/confluence.
Por que terceirizar a ingestão com a Erathos
A premissa do conector é direta: a engenharia de manutenção da ingestão não deveria ser responsabilidade do seu time de dados. Paginação por cursor, busca por recursos aninhados, tratamento de rate limit, evolução de schema, alertas de falha, alertas de queda de volume, backfill. Tudo isso pertence a quem opera a plataforma de ingestão. Com o conector configurado, a plataforma entrega:
Visibilidade de ponta a ponta de cada execução
Tempo de extração por endpoint, contagem de registros por janela, quais janelas foram processadas, onde houve retry. Quando uma métrica muda em um dashboard e um time abre um ticket com o time de dados, você tem o rastro completo para encontrar a causa raiz.
Alertas configurados de fábrica
Falha de execução, queda de volume por endpoint e atraso de janela são detectados e roteados pelas integrações de alerta que o seu time já usa, como Slack e e-mail. Você não escreve esse código.
Reprocessamento como operação suportada
Quando você precisa reprocessar uma janela, por exemplo para recarregar um espaço depois de corrigir o modelo que achata os corpos das páginas, ou para recuperar um período afetado por uma mudança de permissão no token, isso é uma operação da plataforma, não uma sequência improvisada de DELETE e INSERT no warehouse.
Paginação correta, tratamento de recursos aninhados, gerenciamento de rate limit, evolução de schema e backfill são responsabilidade da plataforma. O time de dados foca no modelo, não no encanamento.
Pipelines disponíveis
- Confluence → Azure SQL Server: https://www.erathos.com/pipelines/confluence-azure-sql-server
- Confluence → Azure Synapse: https://www.erathos.com/pipelines/confluence-azure-synapse
- Confluence → BigQuery: https://www.erathos.com/pipelines/confluence-bigquery
- Confluence → ClickHouse: https://www.erathos.com/pipelines/confluence-clickhouse
- Confluence → Databricks: https://www.erathos.com/pipelines/confluence-databricks
- Confluence → PostgreSQL: https://www.erathos.com/pipelines/confluence-postgresql
- Confluence → Redshift: https://www.erathos.com/pipelines/confluence-redshift
- Confluence → S3 Iceberg: https://www.erathos.com/pipelines/confluence-amazon-s3
- Confluence → Snowflake: https://www.erathos.com/pipelines/confluence-snowflake
- Confluence → Supabase: https://www.erathos.com/pipelines/confluence-supabase
Comece agora
Crie a sua conta Erathos em https://app.erathos.com/signup?slug=blog&button=cta&utm_campaign=confluence_release e conecte o Confluence ao seu warehouse em minutos. Com o seu token de API da Atlassian, os primeiros dados chegam ao destino com zero código de pipeline para escrever, manter ou monitorar.
Documentação, decisões e action items escritos no Confluence todos os dias não deveriam ficar presos dentro de um SaaS, desconectados do resto do seu modelo analítico. Ou pior: travados em um pipeline caseiro que vai continuar custando a atenção do seu time todo mês, para sempre.
Veja a documentação completa do conector em https://docs.erathos.com/connectors/apis/confluence.