You need to enable JavaScript to run this app.
导航
API 数据来源
最近更新时间:2024.06.24 17:39:43首次发布时间:2022.07.01 19:57:18

1.概述

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

2.功能介绍

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

图片
(1)请求方式:支持 GETPOST 两种请求方式,请求方式为 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
    }],
  }
}

说明

如需通过大屏访问API数据的真实场景中,首先要确保该接口能够支持从大屏播放域发起跨域CORS请求。

  • SaaS上是https://console.volcengine.com/bi/datawind
  • 私有化部署则是当前部署环境的地址

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

date

bugs

2021-12-21

30

2021-12-22

22

2021-12-23

13

2021-12-24

10

此表格会被解析成一个维度 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}]

转换效果如下:

name

age

John

12

(2)当目标元素为一个数组JSON时,将数组中每一项共同的属性作为表头,值作为相应每一行的值:

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

转换效果如下:

name

age

John

12

Nancy

14

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

3. 跨域问题解决

以下面的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": {}
    }
}