连接API

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

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

目前，山海鲸可视化支持采用 JSON 返回的 API 形式，具体添加过程如下：

1. 选择数据类型

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

2. 连接 API

2.1 步骤一：发送请求

2.1.1 发送

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

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

请求参数 设置示例，如下图所示：

认证 设置示例，如下图所示：

请求头 设置示例，如下图所示：

请求体 设置示例，如下图所示：

脚本 设置示例，如下图所示：

变量 设置示例，如下图所示：

API 参数设置完成后，点击“发送”按钮发送请求，检测 API 是否可以正常访问。

2.1.2 响应

点击“发送”后可以在界面下方查看“响应”是否正常。

如果 API 可以正常访问，点击“下一步”即可完成步骤一的发送请求操作。

2.2 步骤二：数据解析

2.2.1 响应结果

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

2.2.2 数据解析

2.2.2.1 自动解析

山海鲸可视化的 API 接口默认使用自动解析方式进行数据解析，直接点击下一步就可以看到解析结果的数据预览。

如果结果不符合预期，我们可以点击上一步进行修改。

2.2.2.2 使用 JsonPath 解析

针对一些复杂的 API 数据结构，我们也可以使用JsonPath 解析进行手动的自定义数据解析。

勾选“使用 JsonPath 解析”后可以开启 JsonPath 进行解析。

开启后会默认添加一个空数据表，我们可以进行重命名和删除（仅剩一个表时不能删除）。

通常如果是多组数据放在一个 API 中 ，我们可以通过添加多个数据表进行拆分。（详见下方章节）

点击“选择 JSON 节点”可以打开节点设置窗口。

在设置窗口中可以通过点击来进行节点的选择，也可以通过选择下一级进行批量选择。

如果当前返回的数据结构并非完整的数据结构，也可以通过点击自定义进行手动修改。

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

选择完成后，点击“确定”即可完成数据节点设置，得到解析后的字段。

2.2.2.3 添加空字段

通过点击“添加空字段”可以通过自定义的方式添加新字段，添加后可以对字段名称、字段类型和解析路径进行手动操作。

2.2.2.4 添加数据表

通过添加多个数据表，也可以对数据进行分表管理，便于数据的使用。

点击“添加数据表”，可以新建一个空白数据表，然后继续通过“选择 JSON 节点”进行数据字段的添加。

每个数据表的名称都可以进行 编辑，也可以通过删除按钮进行表的删除。

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

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 数据格式可以参考下面的案例，以下示例仅展示数据格式要求，并不代表一定要用 PHP 写，您可以选择熟悉的语言来写。

3.1 单条数据 API 示例

链接和代码如下：http://test.shanhaibi.com/demo1.php

1
2
3
4
5
6
7
8
9
10
11

<?php

$data = [
    '字段1' => 1,
    '字段2' => '测试文本',
    '字段3' => 1.2,
    '字段4' => 0.5,
];

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

对应的字段格式如下：

添加完成后数据预览如下：

3.2 多条数据 API 示例

链接和代码如下：http://test.shanhaibi.com/demo2.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?php

$data = [
    [
        '字段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);

对应的字段格式如下所示：

添加完成后数据预览如下：

3.3 多组数据 API 示例

链接和代码如下：http://test.shanhaibi.com/demo.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<?php

date_default_timezone_set('PRC');

$data = [
    '示例表格1' => [
        '字段1' => 1,
        '字段2' => '测试文本',
        '字段3' => 1.2,
        '字段4' => 0.5,
        '字段5' => date('Y-m-d H:i:s'),
    ],
    '示例表格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;charset=utf-8");
echo json_encode($data);

这种 API 结构通过自动识别可能无法得到想要的结果，需要通过手动方式进行 JSONPath 解析，同时我们可以添加多个表，每个月对应一组数据。

添加完成后数据预览如下：

【温馨提示】

API 数据在山海鲸内仅支持查看，不支持在线修改，如需修改数据，请直接在 API 源数据中修改，修改完成之后请按照教程刷新数据进行操作。

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