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:

  1. Obtém cookies e tokens da página do dashboard Power BI
  2. Carrega o esquema conceitual (tabelas e colunas disponíveis)
library(vigiar)

# Conexão simples
vigiar_conectar()

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 FALSE

4.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 telemetrySessionId embutido 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

  1. Sempre verifique a sessão antes de baixar dados: vigiar_sessao_ativa()
  2. Use vigiar_status() periodicamente para detectar mudanças no esquema
  3. Trave o esquema com vigiar_esquema_lock() para garantir reprodutibilidade
  4. Desconecte ao final da sessão de trabalho: vigiar_desconectar()
  5. 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")