API数据源

BaskServer 支持基于 RESTful 接口定义 API 数据源，这样我们在一个项目里可以很容易地去访问第三方应用的数据服务，并引入到 BaskServer 中，为 BaskReport、BaskAdapt 等模块提供数据服务。

创建API数据源

菜单入口：数据源管理

下面我们使用 JSONPlaceholder 提供的 RESTful 服务搭建 API 数据源：

项目地址：https://jsonplaceholder.typicode.com/

选择 API 数据源类型，设置如下：

单击确定保存后，数据源列表就能看到上面添加的 API 数据源对象：

配置API数据集

单击上面配置好的 API 数据源，进入数据集配置界面：

单击新增API数据集：

• 请求类型：GET
• 请求地址：https://jsonplaceholder.typicode.com/posts

单击初始化字段，完成字段的初始化工作，最后保存。

用相同的办法配置以下数据集：

配置完成后的数据集列表如下：

使用API数据集

在报表设计器中，我们可以添加服务器数据源：

然后在数据集标签页上选择对应的数据集：

这样就可以开始进行报表的设计和开发了。

预览返回的JSON数据

我们可以通过测试按钮查看返回的 JSON 数据：

指定JSON对象

有时候 API 返回的数据是一个复杂结构的 JSON 对象，而我们的数据集只需要获取其中的一个节点对象，那么可以通过指定对象按钮确认：

该按钮会弹出一个 JSON 对象选择对话框：

选择你希望解析的 JSON 对象即可。

鉴权配置

在很多情况下 API 数据请求都会存在用户鉴权的问题，API 数据集支持以下鉴权模式：

No Auth

表示不需要鉴权，直接访问 API。

HTTP Auth

HTTP Auth 是指在请求访问的时候，将客户端的参数或 Header 中的信息转发到 API 数据请求对应的参数或 Header 中。

示例1：URL参数转发

如果你希望从前端的 URL 请求中获取参数，并转发到 RESTful 请求中，例如 URL 为：

http://localhost:8080/baskserver/baskreport/designer?tenantId=basksoft&file=24501&$parameters=${decodeURIComponent(JSON.stringify({username:'anline'}))}

配置步骤：

1. 首先在 Report 中添加参数 username：

   

2. 然后为 API 数据集添加参数接收报表参数：

   

3. 配置鉴权参数，将 username 参数取出并放到 RESTful 请求的 URL 中，参数名修改为 userid：

   

示例2：Header参数转发

如果你希望从前端的 URL 请求中获取参数，并转发到 RESTful 请求的 Header 中，例如 URL 为：

http://localhost:8080/baskserver/baskreport/designer?tenantId=basksoft&file=24501&parameters=${decodeURIComponent(JSON.stringify({accessToken:'MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3'}))}

配置步骤：

1. 首先在 Report 中添加参数 accessToken：

   

2. 然后为 API 数据集添加参数接收报表参数：

   

3. 最后配置鉴权参数：

   

Bearer Token

Bearer Token 是 HTTP Auth 的一个简化配置版本，它会从 Cookie 和数据集参数中读取 accessToken 的值，并直接写入到 Header 中，对应 Header 中的 key 为 Authorization。

读取顺序：

1. 从 Cookie 中读取 accessToken 的值
2. 从 Dataset 的参数中读取 accessToken 的值（会覆盖 Cookie 的值）

Cookie 中 accessToken 的 key 值可以自定义，默认值为 access_token，Dataset 中 accessToken 对应的 key 值同此规则。

如何初始化 Cookie 中的 accessToken 值，请参考：accessToken初始化

OAuth 2.0

对于一些有后台定时任务的数据请求，如果该 RESTful 请求不是前端发起的，此时无法从前端的 URL 或 Header 中读取权限信息。这种情况下可以利用 OAuth 的客户端授权模式，只要配置好获取 accessToken 的 URL，以及对应的 Client ID 和密码，系统就会利用该配置自动获取 accessToken 的值，并将该值在 RESTful 请求的时候放在 Header 中，从而避免权限验证无法通过的问题。

鉴权继承

如果一个 API 数据源下的所有 API 数据集的鉴权配置都一样，则可以将鉴权配置放在 API 数据源中，并在 API 数据集的鉴权配置中选择继承数据源权限设置，这样可以大大加快 API 数据集定义的时间，提升开发效率。

API数据集参数

API 数据集可以设定请求参数，具体参数的值由使用数据集的发起方决定。例如，如果 BaskReport 添加了 API 数据集，则报表的系统参数会覆盖 API 数据集的参数值。

参数传递机制

如预览报表时，请求的 URL 为：

http://localhost:8080/baskserver/baskreport/designer?tenantId=basksoft&file=24501&$parameters=${decodeURIComponent(JSON.stringify({dept:'10000',branch:'100000'}))}

配置步骤：

1. 在报表中添加参数 dept 和 branch：

   

2. 在 API 数据集中添加参数 dept 和 branch：

   

系统执行时如果发现有同名参数，就会将报表的参数值覆盖到 API 数据集的参数中。

注意：如果 API 数据集的请求是 GET，则参数会放在 URL 中；如果请求是 POST，则参数会通过 Form 表单的方式传递。

参数引用语法

参数在 API 数据集属性面板中有以下用法：

1. 在 URL 中使用参数：

https://example.com/api?param=${$paramName}

2. 在 Body 中使用参数：

{
  "p1": ${$paramName1},
  "p2": ${$paramName2}
}

3. 在 Header 中使用参数：

{
  "Authorization": "Bearer ${$accessToken}"
}

4. 在数据集参数中指定参数值：

API数据源类型

在某些场景下，RESTful 请求返回的数据是一个数据包，里面包含了当前报表开发需要的多个数据集，如下面的 JSON 结构：

如果按照上面的方法，需要定义多个 API 数据集，并配置相关的 URL 和请求参数。但这些数据集的 URL、请求参数和鉴权配置完全一致。

这种情况下，可以将 API 数据源的类型修改为数据集合：

这种类型的数据源允许像 API 数据集一样配置 URL 和参数等，并提供初始化数据集按钮，自动初始化内部的数据集，大大提高开发效率。