API de Painéis de BI

Lista as conexões de BI do projeto, da mais antiga para a mais recente, 200 por página; passe next_cursor de volta como cursor para a próxima. Um segredo nunca é retornado: secret mostra se está definido e seus últimos 4 caracteres.

Adiciona uma conexão a um sistema de BI que o projeto possui. Para o Grafana: o endereço dele (http ou https em um host público, com prefixo de caminho opcional) e um token de conta de serviço com a função Viewer. O token é selado e nunca é retornado.

Grafana renders dashboards for screens through its Image Renderer plugin or remote rendering service, so the customer installs one; run POST /api/bi-connections/{id}/test to check. For Power BI (kind powerbi): config.tenant_id and config.client_id of a Microsoft Entra app registration and its client secret value as secret.

Um administrador do Power BI deve ativar as configurações de desenvolvedor Embed content in apps e Service principals can call Fabric public APIs para o app (portal de administração, configurações do locatário), o app deve ser Membro ou Administrador de cada workspace que exibe, e os relatórios precisam de uma capacidade Embedded, Fabric ou Premium em produção.

For Tableau (kind tableau): config.url (the https address of Tableau Server, or of your Tableau Cloud pod such as https://10ay.online.tableau.com), config.site (the site content URL, empty for the default site), config.client_id and config.secret_id of a connected app with direct trust, config.username (the Tableau user the screens views are shown as) and the secret value as secret.

Adicione embed_origin da resposta à lista de domínios permitidos do aplicativo conectado e ative o segredo. Quem tem um ticket de tela pode incorporar qualquer visualização que esse usuário possa ver, então use um usuário que veja apenas os dashboards das telas. Tableau Cloud, ou Tableau Server 2023.3 ou posterior.

Para uma página web com login (kind web): a conta de serviço de um site que mostra o dashboard atrás de um login. config.login_mode é auto (config.login_url, config.username e a senha como secret: o renderizador abre a página de login e preenche o formulário), steps (config.login_url e config.steps, um script de passos goto, fill, click, press, wait_for e wait_ms cujos valores podem conter {{username}}, {{password}} e {{otp}}) ou none (sem login: a conexão mostra páginas com os cookies que você dá a ela). totp_secret é a chave base32, ou o endereço otpauth://, do aplicativo autenticador da conta: o servidor calcula o código de uso único (RFC 6238) e envia ao renderizador apenas o código. cookies é um conjunto de cookies exportado de um navegador logado, para um site cujo login não pode ser automatizado (login único aprovado no celular, uma verificação de dispositivo); o servidor guarda o conjunto e o renova com os cookies que cada captura devolve, então um login é raro.

A senha, a semente e os cookies são selados e nunca devolvidos. Use uma conta de serviço somente leitura. A senha é digitada apenas em config.login_url e nos passos goto, então movê-los para outra origem exige secret de novo. Depois de cinco logins recusados seguidos, a conexão para de fazer login até que suas credenciais mudem.

Um servidor sem renderizador de páginas responde bi_web_unavailable. Adiciona bi_connection.created. Uma nova tentativa exata com a mesma Idempotency-Key devolve esta mesma resposta.

Uma conexão, com o último teste.

Changes a connection's name, address, organization or secret (a sent secret replaces it; an omitted one is kept). Moving a Grafana or Tableau connection to another origin (scheme, host or port) needs the secret in the same request, answered invalid_request at secret otherwise: the stored secret is only sent to the address it was saved for.

Uma mudança de endereço ou de segredo limpa last_test e descarta todas as renderizações em cache das visualizações dela. Registra bi_connection.updated. If-Match protege a revisão.

Exclui uma conexão que nenhuma visualização usa; enquanto houver visualizações usando-a, a resposta é resource_conflict com os ids delas. Registra bi_connection.deleted. If-Match protege a revisão.

Calls the BI system with the connection's secret and stores the answer as last_test. For Grafana the checks are token (GET /api/search accepts it) and image_renderer (the plugin is listed; a missing plugin is a warning because a remote rendering service does not show as one).

Ela não julga permissões por painel, a saúde das fontes de dados nem a acessibilidade de um renderizador remoto: teste uma visualização para renderizar de verdade. Uma recusa do Grafana é uma verificação com falha, não um erro.

For Power BI the checks are token (Microsoft Entra accepts the app) and workspaces (the app can list workspaces; it counts them and none fails the check, naming the workspace access step). It does not judge capacity, row-level security or access to any one report: test a view, which generates a real embed token.

For Tableau the check is signin: Tableau accepts a content-read JWT signed with the connected app secret for the connection user, and the server signs out again. It does not judge the domain allowlist, which only a screen loading a view proves, or the permissions on any view: test a view, which looks the view up as the user.

Lista o que o token da conexão pode mostrar. Grafana: os painéis dele (query pesquisa nos títulos; next_cursor pagina) ou, com dashboard definido, os painéis internos desse painel (linhas achatadas) em dashboard.

Power BI: os workspaces que o app pode ver (id, name; query mantém os nomes que a contêm) ou, com workspace definido, os relatórios desse workspace (id, name, embed_url) em workspace.

Tableau: as visualizações que o usuário da conexão pode ver (caminho como Workbook/View, name), 100 por página lida; query mantém as visualizações cujo nome ou caminho o contém, lendo até dez páginas para encontrá-las, e next_cursor é a próxima página a ler. Uma conexão web não lista nada.

Lists the project's BI views, oldest first, 200 to a page; pass next_cursor back as cursor for the next. Each carries embed_url, the address an iframe primitive shows (content_fit fill); it is null where this server has no embed host.

Adiciona uma visualização de um painel do Grafana da conexão ou de um único painel interno dele (url: um endereço /d/{uid}/... no host da conexão, ou target), ou de um link de painel público do Grafana (kind grafana e target.public_url, sem conexão).

Put the answer's embed_url in an iframe primitive: the server renders the dashboard as a PNG through Grafana's /render API, refreshed every refresh_s (30 to 86400, default 300) and shared by every screen of the same size; the screen never talks to Grafana. A public dashboard plays live from Grafana, which must allow embedding.

A página de incorporação mostra apenas um ticket que o manifesto da tela traz, então uma visualização só é reproduzida nas telas do próprio projeto.

For Power BI (kind powerbi): a report of a workspace the connection's app is a member of (url: an app.powerbi.com /groups/{workspace}/reports/{report} address, or target with workspace_id and report_id), with pages to show and rotate_s to rotate through them (pages listing two or more, or rotate_all_pages, need rotate_s of 10 to 3600; one report page needs none), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a short-lived view-only embed token (GenerateToken, App owns data) and renews it before it expires; the screen never holds the client secret. A Power BI Publish to web link is a view without a connection (kind powerbi, target.public_url https://app.powerbi.com/view?r=...), framed as it is.

For Tableau (kind tableau): a view of the connection site (url: an address copied from Tableau, such as https://HOST/t/SITE/views/WORKBOOK/VIEW or Tableau Cloud https://HOST/#/site/SITE/views/WORKBOOK/VIEW, or Workbook/View; or target.view), optionally with target.rotate_sheets and rotate_s of 10 to 3600 to turn the workbook published sheets (rotate_s and rotate_sheets go together; rotate_sheets may be given as the whole target beside url), and refresh_s of 0 (no refresh) or 60 to 86400 (default 300).

The page asks the server for a five minute JWT with only the embed scope, signed with the connected app secret, and builds the Embedding API v3 tableau-viz from the Tableau host; the screen never holds the secret.

Uma visualização do Tableau Public é uma visualização sem conexão (kind tableau, target.public_url, reconstruída como https://public.tableau.com/views/WORKBOOK/VIEW) e também aceita rotate_sheets. Para uma página web (kind web): uma página do site da conexão web (url: um endereço https em um host público, sem target).

O navegador na borda a abre já logado, espera o elemento wait_for quando definido e wait_ms milissegundos (até 10000), e desenha clip, um seletor CSS, quando definido, ou então a página inteira.

A imagem é redesenhada a cada refresh_s (60 a 86400, 300 por padrão) e compartilhada por todas as telas do mesmo tamanho, e só enquanto uma tela mostra a visualização; quando uma captura falha, a última imagem continua na tela. Defina wait_for como um elemento que só existe quando a página está logada, para que uma página de login nunca seja mostrada. Adiciona bi_view.created.

Uma visualização, com embed_url e como se saiu na tela da última vez (status).

Changes a view's name, target (url or target replaces the whole target), cadence or fit. A new target clears status, and every render cached for the old one is retired. A view keeps its connection and kind. Appends bi_view.updated. If-Match guards the revision.

Exclui uma visualização. Uma tela que ainda exibe o embed_url dela responde not_found na tela até a playlist mudar. Registra bi_view.deleted. If-Match protege a revisão.

Renders a connection view for real (1920x1080, outside the shared cache and without touching status), or fetches a public dashboard link and checks that its page may be framed by the view's embed host (allow_embedding in Grafana). It does not judge what the picture shows. A Grafana failure is a failed check, not an error.

Uma visualização de conexão do Power BI gera um token de incorporação real para o relatório (verifica report e embed_token); ela não julga as páginas que nomeia, a capacidade nem o que o relatório mostra, e um conjunto de dados com segurança em nível de linha é recusado pelo Power BI com mensagem própria, exibida na verificação. Um link público do Power BI é buscado e seus cabeçalhos de enquadramento são lidos.

Uma visualização de conexão do Tableau entra como o usuário da conexão e procura a visualização (verifica signin e view); ela não julga a lista de domínios permitidos, a permissão de incorporação nem o que a visualização mostra. Uma visualização do Tableau Public pergunta ao Tableau Public se a pasta de trabalho existe e não julga o nome da visualização.

Desenha agora uma visualização do Grafana ou web como PNG (uma visualização do Power BI ou do Tableau responde not_found), fora do cache compartilhado, de modo que um teste mostra exatamente o que o Grafana ou o navegador renderiza nesse tamanho. A própria página de incorporação usa a renderização compartilhada.