API Dashboard BI

Elenca le connessioni BI del progetto, dalla meno recente, 200 per pagina; restituisci next_cursor come cursor per la successiva. Un segreto non viene mai restituito: secret indica se è impostato e i suoi ultimi 4 caratteri.

Aggiunge una connessione a un sistema BI di proprietà del progetto. Per Grafana: il suo indirizzo (http o https su un host pubblico, con un prefisso di percorso facoltativo) e un token di account di servizio con il ruolo Viewer. Il token viene sigillato e non viene mai restituito.

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.

Un amministratore Power BI deve attivare le impostazioni sviluppatore Embed content in apps e Service principals can call Fabric public APIs per l’app (portale di amministrazione, impostazioni del tenant), l’app deve essere Membro o Amministratore di ogni area di lavoro che mostra, e i report richiedono una capacità Embedded, Fabric o Premium in produzione.

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.

Aggiungi embed_origin della risposta all’elenco dei domini consentiti dell’app collegata e abilita il segreto. Chiunque abbia un ticket di schermo può incorporare qualsiasi vista che quell’utente possa vedere, quindi usa un utente che veda solo le dashboard degli schermi. Tableau Cloud, o Tableau Server 2023.3 o successivo.

Per una pagina web con accesso (kind web): l’account di servizio di un sito che mostra la sua dashboard dietro un accesso. config.login_mode è auto (config.login_url, config.username e la password come secret: il renderer apre la pagina di accesso e compila il modulo), steps (config.login_url e config.steps, uno script di passaggi goto, fill, click, press, wait_for e wait_ms i cui valori possono contenere {{username}}, {{password}} e {{otp}}) oppure none (nessun accesso: la connessione mostra pagine con i cookie che le dai). totp_secret è la chiave base32, o l’indirizzo otpauth://, dell’app di autenticazione dell’account: il server calcola il codice monouso (RFC 6238) e invia al renderer solo il codice. cookies è un set di cookie esportato da un browser connesso, per un sito il cui accesso non si può automatizzare (single sign-on approvato su un telefono, un controllo del dispositivo); il server conserva il set e lo rinnova con i cookie che ogni acquisizione restituisce, quindi un accesso è raro.

La password, il seed e i cookie sono sigillati e mai restituiti. Usa un account di servizio in sola lettura. La password viene digitata solo in config.login_url e nei passaggi goto, quindi spostarli su un altro origin richiede di nuovo secret. Dopo cinque accessi rifiutati di fila la connessione smette di accedere finché le sue credenziali non cambiano.

Un server senza renderer di pagine risponde bi_web_unavailable. Aggiunge bi_connection.created. Un nuovo tentativo identico con la stessa Idempotency-Key restituisce questa stessa risposta.

Una connessione, con l’ultimo test.

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.

Una modifica dell’indirizzo o del segreto cancella last_test e ritira tutti i render in cache delle sue viste. Aggiunge bi_connection.updated. If-Match protegge la revisione.

Elimina una connessione che nessuna vista usa; finché alcune viste la usano, la risposta è resource_conflict con i loro id. Aggiunge bi_connection.deleted. If-Match protegge la revisione.

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).

Non giudica i permessi per dashboard, lo stato delle origini dati né la raggiungibilità di un renderer remoto: testa una vista per renderizzare davvero. Un rifiuto di Grafana è un controllo fallito, non un errore.

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.

Elenca ciò che il token della connessione può mostrare. Grafana: le sue dashboard (query cerca nei titoli; next_cursor pagina) oppure, con dashboard impostato, i pannelli di quella dashboard (righe appiattite) sotto dashboard.

Power BI: le aree di lavoro che l’app può vedere (id, name; query mantiene i nomi che la contengono) oppure, con workspace impostato, i report di quell’area di lavoro (id, name, embed_url) sotto workspace.

Tableau: le viste che l’utente della connessione può vedere (percorso come Workbook/View, name), 100 per pagina letta; query mantiene le viste il cui nome o percorso lo contiene, leggendo fino a dieci pagine per trovarle, e next_cursor è la pagina successiva da leggere. Una connessione web non elenca nulla.

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.

Aggiunge una vista di una dashboard Grafana della connessione o di un solo suo pannello (url: un indirizzo /d/{uid}/... sull’host della connessione, oppure target), o di un link di dashboard pubblica Grafana (kind grafana e target.public_url, senza connessione).

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.

La pagina di incorporamento mostra solo un ticket che il manifest dello schermo contiene, quindi una vista viene riprodotta solo sugli schermi del proprio progetto.

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.

Una visualizzazione Tableau Public è una vista senza connessione (kind tableau, target.public_url, ricostruita come https://public.tableau.com/views/WORKBOOK/VIEW) e accetta anche rotate_sheets. Per una pagina web (kind web): una pagina del sito della connessione web (url: un indirizzo https su un host pubblico, senza target).

Il browser sul bordo la apre già connesso, attende l’elemento wait_for se impostato e wait_ms millisecondi (fino a 10000), e disegna clip, un selettore CSS, se impostato, altrimenti l’intera pagina.

L’immagine viene ridisegnata ogni refresh_s (da 60 a 86400, 300 per impostazione predefinita) e condivisa da tutti gli schermi della stessa dimensione, e solo mentre uno schermo mostra la vista; quando un’acquisizione fallisce, l’ultima immagine resta sullo schermo. Imposta wait_for su un elemento che esiste solo quando la pagina è connessa, così una pagina di accesso non viene mai mostrata. Aggiunge bi_view.created.

Una vista, con embed_url e com’è andata l’ultima volta sullo schermo (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.

Elimina una vista. Uno schermo che mostra ancora il suo embed_url risponde not_found sullo schermo finché la sua playlist non cambia. Aggiunge bi_view.deleted. If-Match protegge la revisione.

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.

Una vista di connessione Power BI genera un vero token di incorporamento per il suo report (controlla report e embed_token); non giudica le pagine che nomina, la capacità né ciò che il report mostra, e un dataset con sicurezza a livello di riga viene rifiutato da Power BI con un proprio messaggio, mostrato nel controllo. Un link pubblico Power BI viene scaricato e ne vengono letti gli header di framing.

Una vista di connessione Tableau accede come utente della connessione e cerca la vista (controlla signin e view); non giudica l’elenco dei domini consentiti, il permesso di incorporamento né ciò che la vista mostra. Una vista Tableau Public chiede a Tableau Public se la cartella di lavoro esiste e non giudica il nome della vista.

Disegna ora una vista Grafana o web come PNG (una vista Power BI o Tableau risponde not_found), fuori dalla cache condivisa, così un test mostra esattamente ciò che Grafana o il browser rende a quella dimensione. La pagina di incorporamento usa il rendering condiviso.