本文为您介绍如何以 API 接口连接数据的方式获取数据。

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

1. 在数据连接方式（也可称数据查询类型）中，选择 HTTP API。
   

2. 按照 API 请求参数填充请求方式、请求头、请求体、数据路径等内容。
   

   参数	配置说明
   请求方式	支持 GET 与 POST 两种请求方式。 GET：从服务器获取数据。包含请求方式、URL、请求头，无请求体。 POST：向服务器提交数据。包含请求方式、URL、请求头、请求体。
   URL	接口网址。 示例：https://api.example.com/users/123/profile 协议：https:// 域名：api.example.com 数据路径：/users/123/profile 注意 请求方式为 GET 时请求体参数不生效，如有 query 参数，参数应当手动拼接到数据路径内。
   请求头	API 数据模式下前后端交互内容均为JSON，所以请求头默认有 "Content-Type: application/json"，用户可点击「+ Add header」新增。
   请求体	仅 POST 请求方式支持该参数，需要保证是合法的JSON数据。

   注意

   • URL、请求头、请求体等均有格式约束，注意不要有引号、花括号等冗余格式。
   • 如果直接在页面上请求地址存在跨域问题，可以通过代理查询的方式得到结果，具体请参考跨域问题解决。

3. 配置 Transformer 参数内容。Transformer 是在数据返回后对其进行二次处理的方法，其中 data 参数即为返回的数据本身。
   
   使用示例：
   若返回数据为 {data:{ sales:1212 }}，直接解析数据则会得到 data字段，值为一个对象{ sales:1212 }，不满足使用需求。因此需要在 Transformer 中改为 return data.data，此时得到 {sales:1212}，则可以被解析为sales字段，值为 1212。
   数据解析说明：
   数据的返回值会被转换成一个表格，然后以转换后的表格列作为字段。通常来说如果 API 返回数据存在复杂层级结构情况下，需要通过转换器 Tranformer 将其转换为扁平的对象结构，然后再获取数据。转换策略如下：

   • 当目标数据为一个非数组 JSON 时，将其作为仅有一行的数据，并获取第一层字段作为表头，值作为第一行的值：

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

     转换效果如下：

     name	age
     John	12

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

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

     转换效果如下：

     name	age
     John	12
     Nancy	14

     说明

     数组中所有 JSON 对象的属性必须完全一致，不允许出现部分对象缺少属性、多增属性或属性名称不同的情况。即使没有对应的值也需要显式地把属性列出，不允许省略。

4. 如上配置完成后点击“获取数据”，软件会进行网络请求。查询成功后可以点击“查看数据”查看返回内容被解析成的表格结构，在字段区域可以查看获取的字段。接下来，即可利用获取的 API 数据进行大屏搭建。

   注意

   要求目标服务对当前发起请求的域允许跨资源访问(CORS)，具体请参考跨域问题解决。

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

跨域问题解决

以 URL "https://my-cross-origin.com/demo" 为例，假设直接在页面上请求这个地址会有跨域问题，可以通过代理查询的方式得到结果。
具体的配置方法为：

• 请求方式选择 POST
• URL 填 https://console.volcengine.com/bi/datawind/aeolus/api/v3/largeScreen/proxyQuery

  注意

  • 如果用户需要在大屏发布模式下支持跨域，接口改为使用 /proxyQueryV2。
  • 该 URL 仅针对火山引擎 SaaS 用户，如果是私有化部署，需要把 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": {}
      }
  }