连接API

在如何添加数据源中我们已经给大家介绍了添加数据源的步骤，本文主要介绍一下API 接口的具体设置。

（关于通过传递参数显示不同的数据，请参考教程：如何通过传递参数让大屏展示不同数据）

目前，山海鲸可视化支持采用 JSON 返回的 API 形式，推荐大家一个 API 内只返回一组数据。如果返回多组数据，软件也会尝试进行自动识别，不过可能会有一定的误差。

1. 选择数据类型

在数据源编辑窗口中，在左侧选择“添加数据”选项卡，然后在右侧点击接口分类中的“API”按钮：

2. 连接 API

2.1 步骤一：发送请求

点击“API”按钮后会弹出输入“连接 API”的设置框，此处可以选择“GET”或“POST”请求，然后填入一个 API 地址，最后点击“发送”即可发送请求。

2.1.1 GET 请求

发送 GET 请求，如下图所示：

2.1.2 POST 请求

发送 POST 请求，如下图所示：

2.1.3 响应

在下方可以设置 API 请求参数、认证、请求头和请求体。

点击“发送”后可以查看“响应”，然后点击“下一步”即可完成发送请求。

2.2 步骤二：数据解析

2.2.1 响应结果

发送请求后，我们可以在“数据解析”中查看“响应结果”。

山海鲸可视化的 API 接口支持自动解析和使用 JsonPath 解析两种方式，勾选“使用 JsonPath 解析”后可以使用 JsonPath 进行解析。

2.2.2 数据解析

2.2.2.1 选择 JSON 节点

点击“选择 JSON 节点”可以选择数据中的 JSON 节点，

点击“重新获取数据”，可以刷新当前窗口内的 JSON 节点数据。

点击“自定义”按钮，可以调整 API 数据源的 JSON 数据结构，比如，我们需要额外增加一个节点，就可以在此处完成添加。

点击左侧字段名称可以选择 JSON 节点，然后点击“确定”即可。

JSON 节点解析后的字段名称、字段类型、解析路径会显示在下方，点击右侧“操作”列的按钮可以删除节点。

2.2.2.2 添加空字段

点击“添加空字段”新增一个空白字段，可以自定义字段名称、字段类型和解析路径。

2.2.2.3 添加数据表

点击“添加数据表”，可以新建一个空白数据表。

点击左侧按钮可以重命名当前数据表，点击右侧按钮可以删除当前选中的数据表。

设置完成后，点击“下一步”即可完成数据解析。

2.3 步骤三：数据预览

设置完成后，可以对数据进行预览，点击“确定”按钮即可完成 API 数据的连接。

在发出 API 请求的时候，山海鲸会自动拼上 GET 参数 ts 和 sign，其中 ts 为毫秒时间戳，sign 为使用密钥 key 签名后的字符串，sign 的签名算法如下：

sign = md5(ts + key)

比如 API 地址为http://test.shanhaibi.com/demo.php?a=1，key 设置为 abc123，发送 API 时的毫秒时间戳为 1613906185878，则 sign 为 md5(“1613906185878abc123”)=1873f8026797a3f310dd021e145718f0

最终发出的请求为：

http://test.shanhaibi.com/demo.php?a=1&ts=1613906185878&sign=1873f8026797a3f310dd021e145718f0

3. 添加完成

软件会自动加载 API 中的数据，确认后点击“确定”按钮，一个 API 的数据源便添加成功了。

【温馨提示】API 数据格式可以参考下面的案例，以下示例仅展示数据格式要求，并不代表一定要用 PHP 写，您可以选择熟悉的语言来写。

API 示例链接：http://test.shanhaibi.com/demo.php

该 API 使用 PHP 编写，代码如下，仅供参考：

<?php

$data = [
    '示例表格1' => [
        '字段1' => 1,
        '字段2' => '测试文本',
        '字段3' => 1.2,
        '字段4' => 0.5,
    ],
    '示例表格2' => [
        [
            '字段5' => 1,
            '字段6' => 1.2,
            '字段7' => "测试文本",
        ],
        [
            '字段5' => 2,
            '字段6' => 2.2,
            '字段7' => "测试文本2",
        ],
        [
            '字段5' => 5,
            '字段6' => 1.3,
            '字段7' => "测试文本3",
        ],
    ],
];

header("Content-Type:application/json;chartset=uft-8");
echo json_encode($data);

该示例 API 的返回结果，如下图所示：

API 数据和表单对应关系：

“示例表格 1”对应的字段格式，如下所示：

字段 1	字段 2	字段 3	字段 4
1	测试文本	1.2	0.5

“示例表格 2”对应的字段格式，如下所示：

字段 5	字段 6	字段 7
1	1.2	测试文本
2	2.2	测试文本 2
3	1.3	测试文本 3

添加到软件中格式，如下图所示：

“示例表格 2”对应的字段格式，如下所示：

字段 5	字段 6	字段 7
1	1.2	测试文本
2	2.2	测试文本 2
3	1.3	测试文本 3

添加到软件中格式，如下图所示：

【温馨提示】此处的数据仅支持查看，不支持在线修改，如需修改数据，请直接在 API 源数据中修改，修改完成之后请按照教程刷新数据进行操作。

此外，山海鲸 API 接口还可以连接通过山海鲸数据管家创建的API 应用和Hub 应用。