Wyn嵌入式BI实战（一）：JSON API带参数接入，多租户数据源配置指南
系列导读：本系列带你打通 JSON API 带参数数据源的全链路——从数据接入、数据准备，到仪表板/报表的参数联动。
- 第 1 篇（接入篇）：配置带参数的 JSON API 数据源
- 第 2 篇（准备篇）：直连模型选型，参数为什么不生效？
- 第 3 篇（联动篇）：仪表板筛选器+报表查询面板，参数联动全闭环
为什么需要"带参数"的 JSON API 直连
如果你正在做一款 SaaS 产品，或者对接的是 IOT 物联网平台、数据中台，大概率会遇到这个局面：业务方说"想在 BI 大屏上看各租户的运营数据"，开发说"数据库不能直接暴露，数据都通过 API 提供"。
传统 BI 的思路是"连数据库 → 写 SQL→ 做报表"，到了 API 场景，这条路就断了。Wyn 的 JSON 数据源直连，就是为此准备的——直接对接业务系统返回的 JSON API，无需本地存储，每次查询实时获取。
但光能连还不够。多租户要按租户 ID 过滤、IOT 要按设备号过滤、业务系统要按时间范围过滤——你得让接口接受参数，并且参数能在 BI 运行时动态传入。
本篇带你完成三件事：
- 理清 JSON 数据源直连的四种接入方式和参数来源
- 用"基址 + 端点"方式配置一个带参数的 JSON 数据源
- 定义基址参数和端点参数，理解它们的作用域差异
示例使用公开测试 APIjsonplaceholder.typicode.com，你可以照着复现。
一、为什么需要"带参数"的 JSON API 直连
先说清楚 JSON 数据源直连的本质。
Wyn 的 JSON 数据源直连，包括本地、Web、嵌入型、文件系统四种方式，通过 API 接入的数据无需在本地存储，而是每次根据查询语法获取最新的数据用于分析、展示。
这句话有两个关键点：
- 不落地：数据不存到本地，不占存储，也不需要维护同步任务
- 实时：每次查询都调接口，拿到的是最新数据
这对 SaaS 多租户、IOT、数据中台这类场景特别合适，因为这些场景的数据本来就是通过 API 提供的，BI 直连 API 等于无缝衔接。
但"直连"只是基础，真正让 BI 能跟上业务节奏的是参数。
Wyn 在配置数据接入时支持参数过滤和 JSON 函数预处理，参数可以通过四种方式传入：
举个例子：对于 SaaS 多租户用户，不同的租户需要访问和查询不同的数据，可以把租户 ID 配置在数据源，最终在仪表板运行时通过 URL 动态传入，获取当前租户的数据，确保每个租户的数据隔离和数据安全。
参数是整条链路的"开关"，定义在数据源这一层，后面会被数据模型引用、被仪表板和报表使用。本篇先把数据源这层配好。
二、JSON 数据源的四种接入方式
Wyn 的 JSON 数据源支持四种接入方式，先知道有这几种，本篇实操用的是最常见的一种：
本篇示例用 Web 方式接入jsonplaceholder.typicode.com，这是一个公开的免费测试 API，返回 JSON 数据，读者可以照着操作复现完整流程。
三、实操："基址 + 端点"配置带参数数据源
这一节是本篇的核心。Wyn 在配置 Web API 的连接方式上做了一个增强设计，叫"基准 + 端点"，专门解决"一个数据源多张表、基准地址相同"的场景。
3.1 为什么要用"基准 + 端点"
假设你要接入三个接口：
https://jsonplaceholder.typicode.com/posts（文章）https://jsonplaceholder.typicode.com/users（用户）https://jsonplaceholder.typicode.com/albums（相册）
如果每个接口都单独配一个数据源，重复且难管理。Wyn 的做法是：把公共前缀https://jsonplaceholder.typicode.com抽成基准（类似公共地址），每个具体的接口路径（posts/users/albums）作为端点挂在基址下。
这样一个数据源就能连接多个基址相同的 JSON URL，一个端点对应一张数据表，方便统一管理。并且支持添加多个基址，把相关的数据都放到一个数据源里。
3.2 创建 JSON 数据源
新建数据源，选择 JSON 类型，源类型选择网络型，填入基准地址：
3.3 在基准地址中定义参数
这一步是"带参数"的关键。在基址地址下定义参数，这些参数是公共参数，作用范围较广，可以用到基址和所有引用该基址的端点中。
以多租户场景为例，在基址定义一个id参数：
这个id参数就相当于一个公共过滤条件，所有引用该基址的端点都能用它。多租户部署时，把租户 ID 配在这里，就能过滤出每个租户的数据。
3.4 添加端点地址，引用基准地址
基准地址配好后，添加端点。每个端点 = 一张数据表：
注意端点地址里用@id引用了基址定义的参数。这样请求Users端点时，实际发出的请求是：
参数被动态拼进了 URL，接口根据参数返回对应数据。
3.5 实时验证并预览每个端点数据
配置完成后，可以在数据源界面实时预览每个端点的数据，确认参数生效。预览 Posts 端点会看到文章列表，预览 Users 会看到用户信息，参数过滤的结果一目了然。
3.6 保存数据源
保存数据源后并预览数据源：
四、避坑指南
把这几件事记牢，能省掉不少排错时间。
- 基准地址参数 vs 端点地址参数，作用域不一样
基准地址参数是"公共参数"，所有引用该基准地址的端点都能用；端点地址参数是"表级参数"，只在当前端点生效。多租户这种全局过滤条件放基址，某个端点独有的过滤条件放端点。别搞反。
- 多值参数的分隔符
参数设为多值时，分隔符默认是逗号，但有些接口要求分号或其他分隔符。如果预览数据不对，先检查分隔符是否和后端接口的约定匹配。
- 认证方式按需选择
JSON 数据源支持 None、Basic、OAuth2 认证方式。公网测试 API 一般选 None。
五、本篇小结
本篇完成了全链路的第一步：把带参数的 JSON API 接进 Wyn。
回顾一下你拿到了什么：
- 一个 JSON 数据源，基址是
jsonplaceholder.typicode.com - 三个端点：posts、users、albums，各对应一张数据表
- 一个基址参数
id，支持多值，被 users 和 albums 端点引用
数据源配好了，参数也定义好了，但参数现在只是"存在"，还没真正"用起来"。下一步要进入数据准备层——把数据源变成可分析的数据模型，并让参数在模型层正确传递。
这就引出本系列的第二篇：直连模型与直连数据集怎么选，参数怎么用。
扩展链接
嵌入式分析体验