BI 仪表板 API

按从旧到新的顺序列出项目的 BI 连接，每页 200 个；把 next_cursor 作为 cursor 传回即可获取下一页。密钥绝不会返回：secret 仅显示是否已设置及其最后 4 个字符。

为项目拥有的 BI 系统添加一个连接。对于 Grafana：其地址（公共主机上的 http 或 https，可带路径前缀）以及具有 Viewer 角色的服务账户令牌。令牌会被加密封存，绝不会返回。

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.

Power BI 管理员必须为该应用启用开发者设置 Embed content in apps 和 Service principals can call Fabric public APIs（管理门户，租户设置）；该应用必须是其所显示的每个工作区的成员或管理员；生产环境中的报表需要 Embedded、Fabric 或 Premium 容量。

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.

把响应中的 embed_origin 加入已连接应用的域名允许列表，并启用密钥。持有屏幕票据的人可以嵌入该用户能看到的任何视图，因此请使用只能看到屏幕仪表板的用户。Tableau Cloud，或 Tableau Server 2023.3 及更高版本。

适用于需要登录的网页（kind web）：显示登录后仪表板的网站的服务账号。config.login_mode 为 auto（config.login_url、config.username 和作为 secret 的密码：渲染器打开登录页面并填写表单）、steps（config.login_url 和 config.steps，由 goto、fill、click、press、wait_for 和 wait_ms 步骤组成的脚本，其值可包含 {{username}}、{{password}} 和 {{otp}}）或 none（不登录：连接用您提供的 Cookie 显示页面）。totp_secret 是账号身份验证器应用的 base32 密钥或 otpauth:// 地址：服务器计算一次性验证码（RFC 6238），只向渲染器发送验证码。cookies 是从已登录浏览器导出的 Cookie 集，适用于登录无法用脚本完成的网站（在手机上批准的单点登录、设备检查）；服务器保留该 Cookie 集，并用每次截图返回的 Cookie 续期，因此很少需要登录。

密码、种子和 Cookie 都加密封存，绝不会返回。请使用只读的服务账号。密码只会在 config.login_url 和 goto 步骤中输入，因此把它们换到另一个来源需要重新提供 secret。连续五次登录被拒绝后，连接会停止登录，直到其凭据发生变化。

没有页面渲染器的服务器会返回 bi_web_unavailable。追加 bi_connection.created。使用相同 Idempotency-Key 的完全相同的重试会返回同一个响应。

一个连接及其最近一次测试。

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.

更改地址或密钥会清除 last_test，并废弃其视图所缓存的全部渲染结果。追加 bi_connection.updated。If-Match 用于保护修订号。

删除没有任何视图使用的连接；仍有视图使用时，返回 resource_conflict 并列出这些视图的 id。追加 bi_connection.deleted。If-Match 用于保护修订号。

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

它不判定各仪表板的权限、数据源的健康状况或远程渲染器是否可达：请测试视图以真正渲染。Grafana 的拒绝只是检查失败，不是错误。

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.

列出该连接的令牌可展示的内容。Grafana：其仪表板（query 搜索标题；next_cursor 用于翻页）；设置 dashboard 后，则在 dashboard 下返回该仪表板的面板（行已展平）。

Power BI：应用能看到的工作区（id、name；query 保留名称中包含它的项）；设置 workspace 后，则在 workspace 下返回该工作区的报表（id、name、embed_url）。

Tableau：连接用户能看到的视图（路径形如 Workbook/View，name），每读取一页 100 个；query 保留名称或路径包含它的视图，最多读取十页来查找，next_cursor 是下一页要读取的页。Web 连接不列出任何内容。

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.

添加连接的 Grafana 仪表板或其中某一个面板的视图（url：连接主机上的 /d/{uid}/... 地址，或 target），或 Grafana 公开仪表板链接的视图（kind grafana 和 target.public_url，无需连接）。

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.

嵌入页面只显示屏幕清单所携带的票据，因此视图只会在其所属项目的屏幕上播放。

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.

Tableau Public 可视化是不带连接的视图（kind tableau、target.public_url，重建为 https://public.tableau.com/views/WORKBOOK/VIEW），同样接受 rotate_sheets。对于网页（kind web）：Web 连接所属网站的一个页面（url：公共主机上的 https 地址，不带 target）。

边缘的浏览器以已登录状态打开它，如果设置了 wait_for 就等待该元素，并等待 wait_ms 毫秒（最多 10000），然后绘制 clip（一个 CSS 选择器）所指的部分（如果设置了），否则绘制整个页面。

图片每 refresh_s（60 到 86400，默认 300）重新绘制一次，由所有尺寸相同的屏幕共享，并且只在有屏幕显示该视图时才绘制；截图失败时，最后一张图片会留在屏幕上。把 wait_for 设为只有页面已登录时才存在的元素，这样就绝不会显示登录页面。追加 bi_view.created。

一个视图，含 embed_url 及其上次在屏幕上的表现（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.

删除视图。仍显示其 embed_url 的屏幕在其播放列表更改前，会在屏幕上返回 not_found。追加 bi_view.deleted。If-Match 用于保护修订号。

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.

Power BI 连接视图会为其报表生成真实的嵌入令牌（检查 report 和 embed_token）；它不判定所指定的页面、容量或报表所显示的内容，带行级安全的数据集会被 Power BI 以其自身的消息拒绝，并显示在检查结果中。Power BI 公开链接会被获取，并读取其嵌入框架相关的响应头。

Tableau 连接视图会以连接用户身份登录并查找该视图（检查 signin 和 view）；它不判定域名允许列表、嵌入权限或视图所显示的内容。Tableau Public 视图会向 Tableau Public 询问工作簿是否存在，不判定视图名称。

立即把 Grafana 或 Web 视图绘制成 PNG（Power BI 或 Tableau 视图返回 not_found），不经过共享缓存，因此测试能准确显示 Grafana 或浏览器在该尺寸下渲染的内容。嵌入页面本身使用共享渲染。