API 数据来源

API 数据来源，是指数字大屏支持通过 API 接口连接数据的方式进行数据的获取。由于数字大屏是基于浏览器的网页端应用，所以只能支持 HTTP 协议的网络请求访问。按照 API 请求参数填充请求方式、头、请求体、数据路径内容之后可以获取数据。

首先，在数据连接方式（也可称数据查询类型）中，选择API。按照 API 请求参数填充请求方式、头、请求体、数据路径内容。

（1）请求方式：支持 GET 与 POST 两种请求方式，请求方式为 GET 时请求体参数不生效，query参数应当手动拼接到路径内。

（2）请求头：API数据模式下前后端交互内容均为JSON，所以请求头至少包含

Content-Type: application/json

（3）请求体：需要保证是合法的JSON数据。

（4）数据路径：

数据路径意味着从返回对象身上访问到真正使用的数据的路径, 不填充则默认将整个返回体作为内容。举例来说，有个API接口返回值如下：

{
  "status":"ok",
  "errCode":0,
  "data":{
    "bugTrending":[{
      "date":"2021-12-21",
      "bugs": 30
    }, {
      "date":"2021-12-22",
      "bugs": 22
    }, {
      "date":"2021-12-23",
      "bugs": 13
    }, {
      "date":"2021-12-24",
      "bugs": 10
    }],
  }
}

此处希望通过此数据来在大屏展示“BUG数量趋势图”，则 transformer 函数中应该返回data.data.bugTrending。此时路径指向的数据会被当做目标数据进行解析，当前示例中的数据会被解析成如下的表格：

此表格会被解析成一个维度 date，一个指标 bugs,在分析区域分别拖拽date胶囊到“轴”，bugs胶囊到 值，此时一个bug数量关于日期的折线趋势图就在大屏中绘制出来了。

一个API接入的调试技巧：先使用接入功能模拟接口返回后值，分析完成确认数据符合预期后通过静态数据表格反推API返回值，因为API请求结果在大屏处理中的本质是将JSON转化为表格，然后通过静态数据逻辑解析出维度指标，从而进行数据分析。

如上配置完成后点击“获取数据”软件会进行网络请求，要求目标服务对当前发起请求的域允许跨资源访问(CORS)，查询成功后可以点击“查看数据”查看返回内容被解析成的表格结构。

请求出现错误时，错误会展示在底部；更多报错信息可以通过浏览器的开发者工具进行深入查看。

Transformer 是在数据返回后对其进行二次处理的方法，其中 data 参数即为返回的数据本身。

举例来说，演示网址的返回数据为 {data:{ sales:1212 }}，如果直接解析数据则会得到 data字段，值为一个对象，不满足使用需求，所以在 transformer中改为 return data.data，此时解析结构为 {sales:1212}，则可以被解析为 sales字段，值为 1212；
数据解析补充：数据的返回值会被转换成一个表格，转换策略如下：
（1）当目标数据为一个非数组JSON时，将其作为仅有一行的数据，并获取第一层字段作为表头，值作为第一行的值；

{"name":"John","age":12} 
// 被视为 [{"name":"John","age":12}]

转换效果如下：

（2）当目标元素为一个数组JSON时，将数组中每一项共同的属性作为表头，值作为相应每一行的值：

[
  {"name":"John","age":12},
  {"name":"Nancy","age":14}
]

转换效果如下：

然后以转换后的表格作为字段配置解析的对象结构。通常来说如果API返回数据存在复杂层级结构情况下，也需要通过转换器Tranformer将其转换为扁平的对象结构，最终作为表格进行分析消费。

以下面的URL为例，假设直接在页面上请求这个地址会有跨域问题，可以通过代理查询的方式得到结果。

https://my-cross-origin.com/demo

具体的配置方法为：

• 请求方式选择 POST

• URL 填https://console.volcengine.com/bi/datawind/aeolus/api/v3/largeScreen/proxyQuery

  • 该URL仅针对火山引擎的用户

  • 如果是私有化部署，需要把https://console.volcengine.com/bi/datawind换成私有化环境的地址。例如，当前环境是https://my-testing.com/bi#/vScreen?appId=12345，URL应该为https://my-testing.com/bi/aeolus/api/v3/largeScreen/proxyQuery，即把#部分前面的内容和/aeolus/api/v3/largeScreen/proxyQuery拼接

• 请求头填Accept: */* 和 Content-Type: application/json

• 请求体按下面格式填（‘#’后面的内容为注释说明，实际使用的时候需要去掉）

{
    # 项目id，当前页面的URL里面有appId=xxx的格式，其中xxx就是项目id
    "appId": "xxx",
    # proxyType固定为HttpApi
    "proxyType": "HttpApi",
    "queryParams": {
        # 需要代理请求的方法，支持GET和POST
        "method": "GET",
        # 代理请求的地址
        "url": "https://my-cross-origin.com/demo",
        # 代理请求需要用到的额外参数
        "params": {},
        "headers": {},
        "body": {}
    }
}