OneMO模组说｜技术学堂-ML307A开发指南（二） OpenCPU HTTP及HTTPS使用介绍

HTTP是一个简单的请求-响应协议，在物联网设备中使用非常广泛，可向HTTP服务器获取数据、推送数据、下载服务器上的文件、OTA远程升级等。ML307A OpenCPU SDK提供的HTTP API接口最大支持创建4路HTTP实例，且支持GET、POST和PUT等常用请求方法。 本文从使用流程、demo代码、OneNET平台对接示例及常见问题四个方面对ML307A模组OpenCPU的HTTP及HTTPS功能进行了介绍。

一、HTTP使用流程解析

以下流程图为使用ML307A OpenCPU SDK HTTP功能时的常见流程及相关函数接口介绍。

图1 HTTP接口函数使用流程

图1介绍了使用HTTP同步接口cm_httpclient_sync_request()与HTTP服务器交互的常规流程，可结合ML307A_OpenCPU_Standard_x.x.x_release\examples\http\

src\ cm_demo_http.c中的demo示例程序加深理解。

HTTP功能包含的全部函数接口详细定义可在include\cmiot\cm_http.h中查看

二、HTTP demo代码解析

SDK中有一个HTTP常规使用方法的demo程序，可在cm_demo_http.c文件中查看，下面我们详细看一下。

2.1 创建HTTP客户端实例

图2 创建HTTP客户端实例函数

(1) 第一步使用cm_httpclient_create（）在模组本地端创建一个HTTP实例，此函数有三个参数，第一个参数为HTTP服务器地址url，可使用完整域名或“iP：端口”的形式，注意url地址前必须加上HTTP或者HTTPS，demo中访问的服务器为百度；

(2) 第二个参数为客户端相关回调函数，demo中使用cm_httpclient_sync_

request()同步接口可忽略该参数，仅传NULL即可；

(3) 第三个参数为实例句柄，若HTTP实例创建成功，则会返回一串随机的数字，作为这个实例的标识号，若创建失败则返回NULL。

2.2 HTTP客户端实例参数设置

图3 HTTP客户端实例参数设置

1. 第二步使用cm_httpclient_cfg_t结构体和cm_httpclient_set_cfg（）函数对第一步创建的HTTP客户端实例进行参数设置；

(2) demo中设置的主要参数有：

①是否使用SSL，本例访问百度，需要使用HTTPS，故此参数为true；

②SSL的索引号，当访问HTTPS服务器时设置；

③设置HTTP连接超时时间及请求响应超时时间，demo中均使用默认时间；具体如下图所示：

图4 HTTP超时时间默认值

④设置DNS解析优先级，demo中设置为1代表ipv6解析优先。

2.3 HTTP客户端实例SSL设置及CA证书

图5 SSL设置及CA证书

1. 第三步使用cm_ssl_setopt()函数设置SSL验证方式及设置CA证书，此函数有3个参数如下：

①第一个参数ssl_id是ssl通道号，范围为0-5，demo中ssl_id为2（第二步中client_cfg.ssl_id设置为2 ）；

②第二个参数cm_ssl_param_type_e是SSL配置项类型，根据cm_ssl_param_type_e中不同的枚举类型配置SSL的各个参数，demo中主要配置CM_SSL_PARAM_VERIFY和CM_SSL_PARAM_CA_CERT这两项，demo中设置SSL验证方式为1，单向验证。

图6 SSL配置类型结构体

1. 注意若要访问的HTTP服务器不带ssl，即不是以HTTPS开头，则不需要进行此步配置。

2.4 使用同步接口发送HTTP请求

图7 同步接口方式HTTP请求函数

1. 使用cm_httpclient_sync_param_t设置HTTP同步接口输入参数，此结构体中含请求类型GET、POST、PUT等，请求路径，及发送给服务器的请求数据（POST时发送给服务器的content）,demo中请求类型为GET，当为GET方法时，必须设置请求路径（本例中路径为根目录“/”），且第三个参数“数据长度”为0，第四个参数“数据”为NULL；

图8 HTTP同步接口输入参数

1. 使用cm_httpclient_sync_response_t结构体接收HTTP 同步接口响应数据；此结构体用于接收HTTP服务器发给模组的响应结果数据，包含响应结果码、响应报头，响应消息体等数据；

图9 HTTP同步接口响应参数结构体

(3) 使用cm_httpclient_sync_request()函数向HTTP服务器发送请求，此函数为同步接口。函数接口包括客户端实例句柄client，以及上面配置好的请求输入参数param和响应结果response。

2.5 HTTP响应结果

若2.4中发送的HTTP请求参数无错误，则模组会收到HTTP服务器响应结果，可将收到的response结构体中包含的服务器返回数据进行处理或打印输出。

图10 HTTP响应结果打印输出

(1) demo中打印了response的三个参数，分别为请求成功时的响应结果码、响应报头长度及响应消息体长度；

(2) 还可以将response剩余两个参数打印出来，即打印HTTP服务器返回的response_header和response_content，即为响应报头和响应消息体。

2.6 释放HTTP响应数据

当程序已将HTTP服务器返回的完整数据处理完后，需要释放这些数据，使用下图中的cm_httpclient_sync_free_data()函数进行释放。

图11 释放HTTP响应数据

2.7 终止HTTP连接或删除客户端实例

当本次HTTP请求结束时需要终止HTTP连接以及删除客户端实例，以释放模组本地资源或者供其他线程使用。

图12 终止HTTP连接及删除实例

删除HTTP本地实例注意事项：

（1）cm_httpclient_delete()接口会将close socket（HTTP）操作发送至eloop模块中让其执行close socket操作；

（2）本接口返回成功代表操作已发送至eloop中，不代表已完成实例删除操作；

（3）用户连续两次调用本接口时建议中间保证100ms以上的延时。

以上，就是HTTP demo示例程序的解析。

三、使用HTTP与OneNET平台对接示例

下面我们使用ML307A OpenCPU SDK提供的 HTTP函数接口与OneNET平台进行对接，整体程序流程与上述HTTP demo代码几乎一致，这里我们解析其中存在差异的部分，以下为完整步骤及程序流程解析。

3.1 平台侧创建HTTP产品及设备

首先，登录OneNET平台https://open.iot.10086.cn/，进入首页右上角“开发者中心”，点击左上角“全部产品服务”-“基础服务”-“多协议接入”，进入多协议接入页面后点击上面菜单的“HTTP”,然后开始创建产品，添加设备，完成以上步骤后即可继续在SDK中设置登录OneNET需要的相关HTTP客户端实例参数。

3.2 修改服务器地址为OneNET HTTP服务器地址

“OneNET平台-多协议接入-HTTP协议”的地址为http://api.heclouds.com，因此有如下修改。

图13 OneNET平台HTTP服务器地址

3.3 HTTP客户端实例参数设置

 因为“OneNET平台-多协议接入-HTTP协议”为HTTP普通连接，所以将ssl_enable参数设置为false，同时跳过HTTP客户端实例SSL设置。

图14 OneNET平台无需设置SSL

3.4 HTTP请求通用报头

不同于第二章的GET请求，我们需要POST发送数据给OneNET平台，所以需要设置OneNET规定的通用报头，即我们在OneNET平台上创建的产品masterapi-key，用作登录OneNET时的鉴权，因此需要增加一个设置通用报头的函数，如下图所示。

图15 设置通用报头函数接口

图16 登录OneNET平台所需的通用报头参数

3.5 使用同步接口发送HTTP POST请求

不同于第二章的GET请求，当需要向OneNET POST上发数据时cm_httpclient_

sync_param_t同步接口输入参数需要做三处修改：

1. 设置HTTP请求类型为HTTPCLIENT_REQUEST_POST；
2. 设置POST请求路径为/devices/1044214984/datapoints?type=3，其中1044214984为OneNET平台上的设备ID；
3. 向OneNET平台POST数据长度为24， 数据string_http="{\"temp123\"：

\"8834rteedd\"}",此处数据长度和数据内容可根据需要修改。

图17 向OneNET平台POST的内容

图18 OneNET平台HTTP POST参数设置

3.5 HTTP响应结果打印

此处将OneNET平台返回的HTTP响应结果包括响应结果码，响应报头长度、响应消息体长度，响应报头内容，响应消息体内容全部打印出来，打印程序及结果如下：

图19 OneNET平台HTTP响应结果打印

图20 OneNET平台HTTP响应结果示例

以上就是，使用HTTP与OneNET平台对接的完整程序流程解析

四、常见问题

1、cm_httpclient_sync_request()同步函数接口适用于哪些应用场景，使用时有什么注意事项?

发送http请求同步接口，只可用于非chunk模式发送，需先创建实例并完成相关参数设置，响应结果中的数据未内部动态分配空间，使用完后可通过cm_httpclient_

sync_free_data接口释放，下次请求时也会自动释放。

2、使用HTTP客户端参数设置时有什么注意事项？

  客户端参数设置，创建实例后设置,请求过程中不可设置；服务器应答重定向信息的情况下，采用cm_httpclient_set_cfg()配置的参数连接重定向的服务器。

3、使用HTTP实例的通用报头函数时有什么注意事项？

设置通用报头，实例期间有效，未设置时，发送请求时将自动添加默认报头。直接引用header指针，不做拷贝，需保证请求过程中不做修改和释放，如外部释放，也需调用cm_httpclient_custom_header_free接口释放内部设置。

4、什么情况下需要使用HTTP实例的特定报头函数，与通用报头函数有何区别？

设置特定报头，用于设置报头中，在不同请求时存在变化的字段，如果通用报头中同样存在该字段，将在发送请求时自动替换为当前设置值。直接引用header指针，不做拷贝，需保证请求过程中不做修改和释放，如外部释放，也需调用cm_httpclient_

specific_header_free接口释放内部设置。