分析集成用于将 VeryReport 中的数据作品嵌入到第三方系统（OA、门户、业务 App 等），访客无需登录 VeryReport，通过短期 Ticket 即可安全查看。
适用角色：租户管理员、数据分析师、系统集成开发人员。
一、能嵌入哪些作品
分析集成支持以下作品类型（须在系统中已创建并具备相应权限）：
| 类型 | 说明 | 嵌入路径示例 |
|---|---|---|
| 仪表板 | 可视化看板 | /embed/dashboard/{作品ID} |
| 复杂报表 | 电子表格类复杂报表 | /embed/report/{作品ID} |
| 数据大屏 | 全屏数据展示 | /embed/screen/{作品ID} |
| 数据填报 | 在线表单填报 | /embed/form/{作品ID} |
| 数据门户 | 数据门户页面 | /embed/portal/{作品ID} |
| 自助取数 | 自助查询分析 | /embed/extract/{作品ID} |
不支持单独嵌入「数据集」「模版」等资源类型。
二、整体流程
① 在 VeryReport 开通分析集成（选定作品）
↓
② 配置展示项（是否显示标题、水印等）
↓
③ 生成 Ticket（调试：管理后台快捷生成；生产：服务端调开放 API）
↓
④ 拼装嵌入 URL 或 iframe，放入第三方页面
↓
⑤ 访客打开页面 → Ticket 校验 → 渲染作品核心概念
- 分析集成：声明「某租户下的某作品允许被嵌入」，相当于嵌入白名单。
- Ticket：短期访问凭证（JWT），可限制有效期、访问次数，并可绑定第三方用户 ID。
- 嵌入页：VeryReport 提供的免登预览页，校验 Ticket 后以内嵌组件渲染作品，不经过完整登录流程。
三、如何进入「分析集成」
- 使用具备开放平台权限的账号登录 VeryReport。
- 左侧菜单进入 「开放平台」。
- 在概览页点击 「分析集成」 卡片中的 「管理集成」，或直接访问
/open/embed。 - 进入 分析集成 列表，可按类型 Tab 筛选、按名称搜索。
若看不到「开放平台」菜单，请联系管理员为您的角色开通 open:* 相关权限。四、开通集成
4.1 新建
- 点击右上角 「新建集成」。
- 在抽屉中按类型、名称筛选可选作品（仅列出尚未开通的作品）。
- 勾选一条或多条，点击确认开通。
- 列表中出现对应记录，开通人为当前登录账号（用于后续签发嵌入访问身份）。
4.2 列表说明
| 列 | 含义 |
|---|---|
| 名称 | 作品类型标签 + 作品名称 |
| 开通人 | 创建集成的 Apollo 用户 |
| 开通时间 | 首次开通时间 |
同一租户下，同一作品只能开通一次；删除后可重新开通。
五、集成配置与生成嵌入代码
在列表中点击某行的 「集成配置」，打开配置弹窗。
5.1 展示型配置
| 配置项 | 说明 |
|---|---|
| 显示标题 / 不显示标题 | 嵌入页顶部是否展示作品名称栏 |
| 安全认证类型 | 固定为 Ticket 认证（免登） |
5.2 快捷生成 Ticket（调试 / 联调）
弹窗左侧用于调试与演示，生产环境请由业务服务端调用开放 API 签发 Ticket（见第七节）。
- 点击 「快捷生成」 展开右侧面板。
- 按需填写：
| 参数 | 说明 | 默认 |
|---|---|---|
| 绑定用户 ID | 第三方系统用户标识，用于审计与行级权限；留空不绑定 | 空 |
| 有效时长（分钟） | Ticket 有效期 | 30 分钟 |
| 水印文字 | 嵌入页叠加半透明重复水印，如姓名、部门 | 空 |
| 访问次数 | Ticket 最多可使用次数 | 1 次 |
- 点击 「生成 Ticket」。
- 左侧出现 URL 链接 或 Iframe 代码，可一键复制。
URL 形态示例
https://{您的VeryReport域名}/#/embed/report/338?ticket=eyJhbGciOi...Iframe 示例
<iframe src="https://{域名}/#/embed/report/338?ticket=..." width="100%" height="600" frameborder="0"></iframe>注意：ticket 为一次性或限次凭证时，每次新访客或刷新嵌入需重新生成。管理后台生成的 Ticket 仅供联调，勿直接用于生产流量。5.3 关闭嵌入
在配置弹窗点击 「关闭嵌入」，或列表中 「删除」：
- 该作品的集成记录被移除；
- 已签发的 Ticket / 嵌入链接随即失效；
- 需重新「新建集成」后才能再次嵌入。
六、嵌入页行为说明
访客打开带 ticket 的嵌入 URL 后，VeryReport 将：
- 调用
GET /api/embed/verify校验 Ticket（是否过期、次数是否用尽、作品是否仍开通集成）； - 校验通过后签发短期 embedToken，用于加载作品数据接口；
- 在独立嵌入布局中渲染对应预览组件（无左侧菜单、无登录页）；
- 若配置了水印，全屏叠加半透明文字层（不影响图表交互）。
可选 Query 参数
| 参数 | 说明 |
|---|---|
showTitle=0 | 强制不显示标题栏（覆盖集成配置） |
七、生产环境接入（开放 API）
管理后台「快捷生成」适合人工调试。正式上线时，应由贵方业务服务端调用开放 API 创建 Ticket，再把 URL 交给前端 iframe 加载。
7.1 前置条件
- 在开放平台 AccessKey 管理 中创建密钥（保存好 SecretKey，仅展示一次）；
- 目标作品已在 分析集成 中开通；
- 服务端实现 HMAC-SHA256 签名（详见 API 使用说明）。
7.2 创建 Ticket
POST /api/open/v1/ticket/create
Authorization: VR-HMAC-SHA256 AccessKeyId=...,Timestamp=...,Nonce=...,Signature=...请求体示例：
{
"worksType": "REPORT",
"worksId": "338",
"boundUserId": "u_001",
"ttlSeconds": 3600,
"ticketNum": 1,
"globalParam": { "region": ["华东"] },
"watermark": { "text": "张三 2026-07-03", "opacity": 0.15 }
}| 字段 | 说明 |
|---|---|
worksType | DASHBOARD / REPORT / SCREEN / FORM / PORTAL |
worksId | 作品物理 ID（与集成列表中一致） |
boundUserId | 可选，绑定第三方用户 |
ttlSeconds | 有效期（秒），默认 3600，最大 86400 |
ticketNum | 0=不限次，1=一次性（防转发） |
globalParam | 可选，报表参数过滤（千人千面） |
watermark | 可选，水印配置 |
返回 { "ticket": "...", "expireIn": 3600 } 后，拼入嵌入 URL 即可。接口明细请参阅 CreateTicket - 创建嵌入 Ticket。
7.3 其他 Ticket 接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/open/v1/ticket/{ticketId} | 查询 Ticket 详情 |
| DELETE | /api/open/v1/ticket/{ticketId} | 撤销 Ticket |
| PUT | /api/open/v1/ticket/{ticketId}/expire?ttlSeconds=N | 延长有效期 |
八、安全与权限
| 机制 | 说明 |
|---|---|
| 集成白名单 | 未开通集成的作品无法通过 Ticket 嵌入 |
| 租户隔离 | Ticket 与集成均绑定租户，不可跨租户访问 |
| 开通人身份 | 嵌入访问以集成开通人的数据权限执行（须对作品有查看权限） |
| Ticket 限次 / 限时 | 防止链接被无限转发 |
| 水印 | 降低截图泄密风险 |
| 域名白名单 | AccessKey 可配置 allowed_origins，校验嵌入来源 Referer |
| 绑定用户 | boundUserId 传入第三方用户 ID，便于审计与参数过滤 |
九、与「分享链接」的区别
| 能力 | 分析集成（Ticket） | 内部分享链接 |
|---|---|---|
| 使用场景 | 嵌入第三方系统 | Apollo 用户之间分享 |
| 访客登录 | 不需要 Apollo 账号 | 通常需要登录或有独立分享 Token |
| 凭证 | 短期 Ticket + 开放 API 签发 | 长期分享 Token |
| 千人千面 / 水印 | 支持 | 视分享能力而定 |
| 统计 | 纳入开放平台嵌入统计 | 独立分享逻辑 |
两套能力并存、互不替代，请按场景选择。
十、嵌入统计
开放平台提供 嵌入统计（/open/embed-stats 或嵌入相关统计 Tab），可查看已开通集成的 Ticket 调用量、成功率等，便于运维与容量评估。
十一、常见问题
Q：打开嵌入链接提示「Ticket 无效或已过期」？
A：Ticket 已过期、使用次数用尽、或集成已被关闭。请在管理后台或业务服务端重新生成 Ticket，并确认集成仍处于开通状态。
Q：提示「无法获取嵌入访问凭证」？
A：多为作品未开通分析集成，或集成记录异常。请重新「新建集成」并生成新 Ticket（不要用旧链接）。
Q：页面空白或报表加载 401 / 500？
A：请确认：① 集成已开通；② Ticket 未过期；③ 开通人对该作品有查看权限；④ 生产环境使用新生成的 Ticket（含正确租户信息）。仍失败请联系管理员查看服务端日志。
Q：快捷生成的链接能给所有用户长期使用吗？
A：不建议。调试 Ticket 默认限次、限时。生产应由服务端按用户/会话动态调用开放 API 签发。
Q：删除集成后能否恢复？
A：需重新「新建集成」。旧 Ticket 全部失效。
Q：一个作品可以嵌入多个第三方系统吗？
A：可以。同一集成可多次签发不同 Ticket；各系统 iframe 指向同一嵌入 URL 模式即可。
Q：复杂报表和仪表板嵌入方式有区别吗？
A：流程一致，仅 URL 中类型段不同（report / dashboard 等），均由对应预览组件渲染。