Importação automática de relatórios

O portal pode espelhar sozinho os relatórios de um ou mais workspaces do Power BI, em vez de você cadastrar cada dashboard à mão. Publicou um relatório no workspace, ele passa a aparecer na lista de dashboards da administração sem intervenção.

O recurso convive com o cadastro manual: a importação automática cobre o workspace de produção inteiro; o formulário “Novo Dashboard” continua servindo para relatórios avulsos de outros workspaces. Um relatório nunca entra duas vezes — ver Chave anti-duplicação.

A plataforma chama de dashboard o que o Power BI chama de relatório. Nesta página os dois termos se referem à mesma coisa.

Configurar os workspaces

Em Administração › Dashboards, no cartão Importação automática no topo da tela:

1. Cole um ou mais Workspace IDs, um por linha (também aceita separados por vírgula).
2. Se não souber os IDs de cor, clique em Ver workspaces disponíveis — o portal lista todos os workspaces que o Service Principal enxerga, com nome e ID. Clicar em um da lista acrescenta o ID ao campo.
3. Clique em Salvar workspaces.

O botão “Salvar workspaces” só fica habilitado quando o campo tem alteração pendente. Campo vazio e salvo = nada é importado automaticamente; só o cadastro manual funciona.

O Workspace ID também está na URL do relatório no Power BI Service, logo após /groups/ — ver Onde encontrar os identificadores.

Pré-requisitos

• Credenciais do Power BI configuradas em Administração › Power BI Embedded (Tenant ID, Client ID, Client Secret). Sem elas o sync não tem como autenticar.
• O Service Principal precisa ser Member ou Admin do workspace — o mesmo requisito de gerar token de embed. Qualquer workspace que já renderiza relatório no portal também funciona aqui, sem liberação nova no Azure. Ver Power BI e Azure.

O que é trazido de cada relatório

Campo do dashboard	De onde vem
Nome	Nome do relatório no Power BI
Descrição	Descrição do relatório no Power BI (vazia se não houver)
Workspace ID	O workspace configurado
Report ID	O relatório
Menu	Fica em branco — você atribui depois; ver Depois que um relatório entra
Modo de incorporação	Service Principal
Mostrar navegador de páginas	Ligado

O “navegador de páginas” entra ligado mesmo em relatório de página única — nesse caso a barra simplesmente não aparece, porque não há o que navegar. Não é preciso desligar manualmente.

Cada linha trazida pelo sync fica marcada como auto (um selo na lista de dashboards). Linhas cadastradas pelo formulário são manual. Essa marca decide o que o sync pode tocar.

Chave anti-duplicação

A identidade de um relatório é o par Workspace ID + Report ID. O sync nunca cria uma segunda linha para o mesmo par.

Se um relatório desse workspace já foi cadastrado manualmente, o sync respeita o cadastro manual e não importa uma cópia auto dele.

O que o sync faz a cada ciclo

Para cada workspace configurado, o sync compara a lista de relatórios do Power BI com o que já existe no portal e:

• Insere os relatórios que ainda não existem (como auto).
• Atualiza nome e descrição das linhas auto cujo relatório mudou de nome ou descrição no workspace.
• Remove as linhas auto cujo relatório saiu do workspace.

Só linhas auto são tocadas. Dashboards manuais nunca são alterados nem removidos pelo sync, mesmo que apontem para um relatório que não existe mais.

Apenas relatórios normais entram. Relatórios paginados (paginated reports) são ignorados por ora.

Anti-apagão

Se a API do Power BI falhar ao listar um workspace, o sync não mexe em nada daquele workspace naquele ciclo — não insere, não atualiza, não remove. Um erro transitório da Microsoft não zera a lista de dashboards. O erro fica registrado e a próxima execução tenta de novo.

Quando o sync roda

• Ao abrir a tela Administração › Dashboards — dispara em segundo plano, com uma trava de alguns minutos para não repetir à toa. Só administradores e quem tem organization.manage_settings abrem essa tela, então esse gatilho é dos administradores. Usuários comuns não disparam sync.
• Botão “Sincronizar agora” — força na hora, ignora a trava, e mostra quantos itens foram inseridos, atualizados e removidos.
• A cada 10 minutos — um agendamento no banco de dados (pg_cron) chama o endpoint de sync, para cobrir os períodos em que nenhum administrador abre o portal.

Efeito prático: um administrador publica no workspace e abre a tela de Dashboards — o relatório já entrou. Para os demais usuários, a diferença aparece no máximo no próximo ciclo de 10 minutos.

Depois que um relatório entra

A importação coloca o relatório na lista, mas ele ainda não está visível para ninguém navegar. Faltam dois passos, os mesmos de qualquer dashboard:

1. Atribuir um menu. Um dashboard sem menu não aparece na barra lateral — nem para administradores. Abra Editar no dashboard auto, escolha o menu e salve. O sync nunca mexe no menu depois que você define. Crie menus em menus da barra lateral.
2. Incluir num perfil de acesso. A visibilidade para usuários vem dos perfis de acesso — cada perfil marca os dashboards que enxerga, na aba Dashboards. Um dashboard fora de todos os perfis só é visto por administradores.

Enquanto esses dois passos não são feitos, o relatório importado fica só na lista da administração, com o selo auto.

Republicar um relatório

Publicar de novo pelo Power BI Desktop substituindo o relatório existente (mesmo nome, mesmo workspace) preserva o Report ID. Nesse caso o sync só percebe eventual mudança de nome ou descrição e atualiza a linha auto no lugar — o menu atribuído, os perfis e os dashboards fixados pelos usuários continuam valendo.

Se a republicação gerar um Report ID novo (acontece ao renomear o relatório, ou ao publicar num workspace diferente), o sync trata como dois eventos: o Report ID antigo sumiu → a linha auto dele é removida; o Report ID novo apareceu → entra uma linha auto nova.

A remoção da linha antiga tem dois efeitos que não se recuperam sozinhos:

• As liberações desse dashboard em todos os perfis de acesso são apagadas junto. É preciso reincluí-lo em cada perfil.
• Os usuários que tinham esse dashboard como padrão fixado perdem a fixação.

E a linha nova entra sem menu e fora de todos os perfis, como qualquer relatório recém-importado.

Ou seja: se o seu processo de publicação costuma trocar o Report ID, cada republicação custa reatribuir menu e perfis. Se ele substitui o relatório no lugar, não há esse custo.

Editar um dashboard auto

O botão Editar funciona nas linhas auto, mas nem tudo que você mudar permanece:

Campo	O sync respeita?
Menu	Sim — definido uma vez, fica
Mostrar navegador de páginas	Sim
Modo de incorporação	Sim
Nome, Descrição	Não — voltam ao valor do Power BI no próximo ciclo
Workspace ID, Report ID	Não altere — se deixarem de casar com o workspace, a linha é removida no próximo ciclo

O botão Excluir não aparece para linhas auto — elas saem sozinhas quando o relatório deixa o workspace. Para tirar um relatório do portal, tire-o do workspace ou remova o workspace da importação automática.

Quando algo não sincroniza

O cartão de importação automática mostra:

• Último sync — data e hora da última execução bem-sucedida.
• Avisos do último sync — se algum workspace falhou, a mensagem de erro aparece ali (ex.: credenciais incompletas, Service Principal sem acesso ao workspace, erro da API do Power BI).

Se “Último sync” está claramente velho (horas, um dia) e ninguém desativou o recurso, o agendamento no banco pode estar sem executar, ou o segredo que o pg_cron usa para chamar o endpoint pode ter sido rotacionado só de um lado. Nesse caso o botão Sincronizar agora ainda funciona (ele não depende desse segredo) e serve de contorno enquanto o agendamento é verificado.

Erros de credencial e de acesso ao workspace têm o diagnóstico detalhado em Power BI e Azure.

Como funciona por baixo

O sync é o endpoint /api/pbi/sync-workspace. Ele roda com privilégio de serviço (ignora RLS) e tem três formas de ser acionado:

• Ler/salvar os workspaces e “Sincronizar agora” exigem sessão com papel de administrador ou permissão organization.manage_settings.
• O pg_cron se autentica com um segredo compartilhado (cabeçalho x-sync-secret), guardado no banco e na Vercel. Esse caminho roda para todas as organizações com workspaces configurados.
• O disparo ao abrir a tela exige apenas sessão válida e respeita a trava de alguns minutos.

A listagem de workspaces e relatórios usa a mesma autenticação Service Principal do embed (client_credentials no Azure AD, escopo Power BI). Nenhuma credencial vai para o navegador.

Checklist

1. Credenciais do Power BI configuradas e testadas.
2. Service Principal é Member ou Admin do workspace.
3. Workspace ID colado no cartão de importação automática e salvo.
4. “Sincronizar agora” executado — os relatórios apareceram na lista com o selo auto.
5. Menu atribuído a cada dashboard importado (senão não aparece na barra lateral).
6. Dashboards incluídos nos perfis de acesso que devem enxergá-los.
7. Teste feito com um usuário não administrador.