IoT Studio 公开API 攻略

2022-04-11 16:17:53

IoT Studio创建公开API

开发内容

公开API由IoT Studio的服务编排创建，以HTTP请求与HTTP返回的方式提供调用端口。与直接创建的“HTTP请求/返回”对相比，公开API不需要鉴权的AppKey与AppSecret，支持公网访问。

开发过程

STEP1 使用模板创建

在IoT Studio的项目管理页面中，选择从模板新建业务服务，如图下图所示。

如下图所示，右上角单击展开更多模板，找到最后一个模板：公开API。

业务逻辑名称随意，模板信息中可以看到，使用该模板创建的业务服务包含三个节点：HTTP请求、脚本节点和HTTP返回。单击使用该模板新建。

STEP2 配置节点

创建完成后会自动跳转到服务编辑器页面。依次对节点进行配置。

HTTP请求节点：

节点配置如下图所示，配置Action参数为：public_api

Node.js脚本节点：

节点配置如下图所示，将返回的payload内容修改为："hello Saxon"

HTTP返回节点不需要进行修改，保持默认配置即可。
单击右上角的保存后部署并发布业务服务。

STEP3 获取API域名

在服务列表中右键单击新建的服务，选择服务调用帮助。

弹出服务详情页面如下图所示：

API Path即调用API的域名，单击行末的复制。

注意

在发布->域名管理页面下也可以找到一个域名地址，如下图所示。

显示为默认API访问域名，但这个域名并不是调用API的域名！

笔者就是误认为这个域名是调用API的域名，测试的请求结果为400，浪费了很久的时间。

STEP4 获取参数

在STEP2 配置节点中，我们没有对HTTP请求节点进行添加入参的操作，但这并不意味着对这个API的请求不需要参数。
向下滚动服务详情页面，找到请求示例，这里提供了调用的API的示例代码。切换比较直观的Python版本，如下图所示：

代码中bodyMap和Headers的声明，分别代表了请求主体信息和请求头信息。

bodyMap的内容如下：

{
    'id': str(uuid.uuid4()),
    'version': "1.0",
    'request': {
        'iotToken': "xxxx",
        'apiVer': "1.0.0"
    },
    'params': {
        # 接口参数
        
        'action':"public_api",
    }
}

其中uuid模块用于根据使用的网卡和时间信息生成一个随机的字符串。此处我们要根据样例代码获知需要提供的参数信息，所以可以以随机字符串代替。去除换行符与注释，整理如下：
{'id':'random_id','version': "1.0",'request': {'iotToken': "xxxx",'apiVer': "1.0.0"},'params': {'action':"public_api"}}

header的内容如下：

{
    'accept': 'application/json'
}

也就是说，我们要在头信息中添加一条这样的键值： 'accept': 'application/json'。

另一种参数

根据帮助文档：公开API，与貔阁同学提供的参考截图：

我们需要在HTTP请求的Body中加入参数如下：

{'params':{'action':'public_api'},'request':{'apiVer':'1.0.0'},'version':'1.0','id': 12}

并且要在请求头信息中注明主体信息的编码方式为application/json

STEP5 使用POSTMAN测试请求

一切准备就绪，下面可以使用POSTMAN来实际测试API了。
启动POSTMAN，新建HTTP请求如下图所示：

请求方式为POST，域名使用STEP3中获取的域名。由于貔阁提供的请求参数有成功的前车之鉴，先来测试他的方法：

貔阁的请求参数

在Header中添加body内容格式的信息，如下图所示：

由于application/json不属于POSTMAN预设的主体信息格式。body选项卡中，选择信息的格式为raw，并粘贴STEP4中获取的参数到主体信息中。如下图所示。

一切准备就绪，单击Send，返回结果如下图：

返回的数据为"hello Saxon"，与我们在服务开发中节点配置的内容一致。请求成功。

请求示例的参数

同样的步骤，新建一条请求如图：

这次Header中键名输入accept，键值不变。

填写body内容如图所示：

单击Send，返回成功信息如下图所示：

以上，两种参数填写方法都是可行的。

非公开API

前面的内容，我们基于公开API模板进行的服务创建。下面来探讨，如果是不使用模板，搭建完全相同的节点。会有什么不同。
项目下直接新建业务服务如图：

参考公开API模板，添加节点：HTTP请求、Node.js脚本、HTTP返回。将三者连接并配置HTTP请求如下图所示：

Action参数为：api_test

同理，复制模板中Node.js脚本的代码，配置节点如图：

HTTP返回节点不需要修改，保持默认。
保存，部署并发布服务。打开服务调用帮助，这里的页面出现了区别：

相比公开API模板创建的服务，这里多出了项目AppKey与AppSecret。

向下滚动页面，查看Python的示例代码：

这里也出现了不同，需要在客户端初始化时进行鉴权过程。
所以这里创建的并不是公开API，公网可以访问，但是要经过鉴权。

猜想

注意到bodyMap中包含了iotToken项，键值为无意义的xxxx。而iotToken常用于物联网设备HTTP连接的鉴权。猜想在非公开API的调用过程中，sdk根据appKey与appSecret建立连接得到iotToken。接着替换bodyMap中的对应项，在实际API调用过程中，起到鉴权作用的只是iotToken。换言之，如果得到了正确的iotToken，仅使用POSTMAN也可以完成非公开API的调用。
测试内容待补充。

Saxon
2020-3-8 15:25

码农公寓