连接API
在如何添加数据源中我们已经给大家介绍了添加数据源的步骤，本文主要介绍一下API 接口的具体设置。
（关于通过传递参数显示不同的数据，请参考教程：如何通过传递参数让大屏展示不同数据）
（关于API的预处理和后处理问题，请参考教程：API预处理和后处理说明）
目前，山海鲸可视化支持采用 JSON 返回的 API 形式，具体添加过程如下：
1. 选择数据类型
在数据源编辑窗口中，在左侧选择“添加数据”选项卡，然后在右侧点击接口分类中的“API”按钮：
2. 连接 API
2.1 步骤一：发送请求
2.1.1 发送
点击“API”按钮后会弹出输入“连接 API”的设置框，此处可以选择“GET”或“POST”请求，然后填入一个 API 地址。
在下方可以设置 API 请求参数、认证、请求头、请求体、脚本和变量。
| 配置项 | 说明 |
|---|---|
| 请求参数 | 用于在 URL 后添加“?key=value ” 形式的参数，向 API 指定数据请求的筛选条件或操作指令。可在此处设置 URL 中Query Params的“Key”“**Value**”**和“Description”。 Key：参数名称。 Value：参数的具体值。 Description：**备注，可用文字描述参数的作用。 |
| 认证 | 用于配置 API 的身份验证方式，可在此处选择认证类型（Auth Type），包括“Basic Auth”“Bearer Token”“JWT Bearer”和“OAuth1.0”，也可以选择“No Auth”无认证。 |
| 请求头 | 用于向 API 指定请求处理方式，可在此处根据**API 文档设置 HTTP 请求头（Headers）**，用于传递元数据。 |
| 请求体 | 仅用于 POST/PUT 请求，发送需要提交的数据。可选择“none”“form-data”“x-www-form-urlencoded”和“raw”四个选项。 none：不发送请求体。 form-data：提交表单+上传文件（如图片、文档） x-www-form-urlencoded：提交普通表单数据。 raw：发送自定义格式数据，可选择“Text”“JSON”“HTML”“XML”和“JavaScript”。 |
| 脚本 | 分为发送请求前（Pre-request）和获取响应后（Post-response）用于自动执行一些操作。 |
| 变量 | 配合脚本，能动态修改的值。可在此处设置“变量名”、“初始值”和“**当前值**”。 变量名：变量的唯一标识符。 初始值：变量在流程开始时或未更新前的默认值。 当前值：变量在运行过程中动态更新的实际值。 |
请求参数 设置示例，如下图所示：
认证 设置示例，如下图所示：
请求头 设置示例，如下图所示：
请求体 设置示例，如下图所示：
脚本 设置示例，如下图所示：
变量 设置示例，如下图所示：
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
1234567891011<?php$data = [ '字段1' => 1, '字段2' => '测试文本', '字段3' => 1.2, '字段4' => 0.5,];header("Content-Type:application/json;chartset=uft-8");echo json_encode($data);
对应的字段格式如下：
| 字段 1 | 字段 2 | 字段 3 | 字段 4 |
|---|---|---|---|
| 1 | 测试文本 | 1.2 | 0.5 |
添加完成后数据预览如下：
3.2 多条数据 API 示例
链接和代码如下：http://test.shanhaibi.com/demo2.php
12345678910111213141516171819202122<?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);
对应的字段格式如下所示：
| 字段 5 | 字段 6 | 字段 7 |
|---|---|---|
| 1 | 1.2 | 测试文本 |
| 2 | 2.2 | 测试文本 2 |
| 3 | 1.3 | 测试文本 3 |
添加完成后数据预览如下：
3.3 多组数据 API 示例
链接和代码如下：http://test.shanhaibi.com/demo.php
123456789101112131415161718192021222324252627282930313233<?phpdate_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 源数据中修改，修改完成之后请按照教程刷新数据进行操作。