library(vigiar)
# Conexão simples
vigiar_conectar()4 Conexão ao Dashboard Power BI
Este capítulo explica como estabelecer uma sessão com o dashboard VIGIAR no Power BI, o primeiro passo para acessar os dados programaticamente.
4.1 Estabelecendo uma conexão
A função principal é vigiar_conectar(). Ela realiza duas operações:
- Obtém cookies e tokens da página do dashboard Power BI
- Carrega o esquema conceitual (tabelas e colunas disponíveis)
Saída esperada:
Sessao VIGIAR estabelecida. Carregando esquema de dados...
Sessao pronta! 28 tabelas disponiveis.
4.2 Parâmetros da conexão
vigiar_conectar(
refresh = FALSE, # Força renovação da sessão
timeout = 30, # Timeout em segundos
max_retries = 3 # Tentativas máximas em falhas
)4.2.1 Renovando a sessão
As sessões do Power BI expiram após algumas horas de inatividade. Para renovar:
# Força uma nova sessão
vigiar_conectar(refresh = TRUE)4.2.2 Aumentando o timeout
Se sua conexão for lenta ou instável:
vigiar_conectar(timeout = 60, max_retries = 5)4.3 Verificando o estado da sessão
# Verificar se existe sessão ativa
vigiar_sessao_ativa() # TRUE ou FALSE4.4 Status do dashboard
Para verificar se o dashboard VIGIAR está online e se o esquema de dados mudou:
status <- vigiar_status()Se o esquema mudou (novas tabelas, colunas removidas), você receberá um aviso:
Warning: Dashboard VIGIAR online, mas o esquema de dados mudou!
Execute vigiar_conectar(refresh = TRUE) para atualizar.
4.5 Cliente de sessão (vigiar_client())
Além da sessão global usada por vigiar_conectar(), o pacote oferece vigiar_client(), que devolve um objeto de sessão autocontido (sem estado global). É útil quando você quer controlar explicitamente o ciclo de vida da conexão ou manter mais de um cliente no mesmo processo.
cliente <- vigiar_client(timeout = 30, max_retries = 3)
print(cliente)
#> Cliente VIGIAR -- 28 tabelas
#> Criado em: 2026-01-01 00:00:00
#> Tabelas: df_anual, df_mensal, df_muni, pop, ...Internamente, vigiar_client() e vigiar_conectar() compartilham o mesmo handshake (token de sessão + cookies) e a mesma obtenção de esquema, de modo que o comportamento de extração do dashboard é único e testado.
vigiar_client() é classificado como experimental; consulte o status com vigiar_lifecycle("vigiar_client"). A sessão criada por vigiar_conectar() permanece a interface estável recomendada para uso geral.
4.6 Encerrando a sessão
4.7 O que acontece nos bastidores
4.7.1 Passo 1: Página inicial
O pacote faz uma requisição HTTP GET à URL pública do dashboard Power BI. O servidor retorna:
- Cookies de sessão (
WFESessionId,ARRAffinity) - Um token
telemetrySessionIdembutido no JavaScript da página
4.7.2 Passo 2: Esquema conceitual
Com os cookies obtidos, o pacote consulta o endpoint:
https://wabi-brazil-south-b-primary-api.analysis.windows.net/
public/reports/{resource_key}/conceptualschema
Este endpoint retorna um JSON com todas as tabelas (entidades), colunas e tipos de dados do modelo do Power BI.
4.7.3 Passo 3: Armazenamento
As informações da sessão e o esquema são armazenados no ambiente interno .vigiar_env e ficam disponíveis para todas as funções subsequentes do pacote.
4.8 Diagrama da Sessão
┌──────────────┐ GET dashboard ┌──────────────────┐
│ vigiar │ ──────────────────────→│ Power BI Server │
│ conectar() │ │ │
│ │←──── cookies + ────────│ │
│ │ telemetrySessionId │ │
└──────┬───────┘ └──────────────────┘
│
│ GET /conceptualschema
│ (com cookies)
↓
┌──────────────┐
│ .vigiar_env │
│ ├─ sessao │ → session_id, cookies, resource_key
│ └─ esquema │ → 28 tabelas com colunas e tipos
└──────────────┘
4.9 Tratamento de erros
4.9.1 Dashboard indisponível
Erro: Nao foi possivel extrair o telemetrySessionId do dashboard Power BI.
O dashboard pode estar temporariamente indisponivel.
Solução: Aguarde alguns minutos e tente novamente. O dashboard do Ministério da Saúde pode passar por manutenções.
4.9.2 Timeout
Solução: Aumente o parâmetro timeout ou verifique sua conexão com a Internet.
4.9.3 Sessão expirada (erro 403)
Warning: Sessao expirada. Execute vigiar_conectar(refresh = TRUE).
Solução: Execute vigiar_conectar(refresh = TRUE).
4.9.4 Geo-bloqueio
O Power BI pode restringir o acesso de algumas regiões geográficas. Se você estiver acessando de fora do Brasil e encontrar erros de acesso, considere usar uma VPN com IP brasileiro.
4.10 Boas práticas
-
Sempre verifique a sessão antes de baixar dados:
vigiar_sessao_ativa() -
Use
vigiar_status()periodicamente para detectar mudanças no esquema -
Trave o esquema com
vigiar_esquema_lock()para garantir reprodutibilidade -
Desconecte ao final da sessão de trabalho:
vigiar_desconectar() -
Monitore o log para diagnosticar problemas:
vigiar_log()
4.10.1 Pipelines não interativos
Em scripts executados via Rscript ou em CI/CD, o vigiar_baixar() exige que o esquema ao vivo tenha sido validado antes do download. Isso evita que uma mudança de schema do Power BI produza dados truncados sem erro visível:
vigiar_conectar()
status <- vigiar_status()
stopifnot(isTRUE(status$tables_ok)) # falha visível se o schema mudou
dados <- vigiar_baixar("df_anual", uf = "RJ")