文档首页 > > 开发指南> 应用侧开发> 使用SDK对接> PHP SDK使用指南

PHP SDK使用指南

分享
更新时间: 2019/10/18 GMT+08:00

本文以提供的北向PHP SDK Demo为例说明如何使用PHP SDK与物联网平台对接,包括证书配置及回调等。Demo以PHP脚本为例,每个脚本文件都可单独运行,旨在演示如何调用SDK接口。

开发环境要求

开发平台

开发环境

推荐的操作系统

IoT

  1. XAMPP 7.2.9
  2. PhpStorm 2018.2.3

Windows7

SDK包为纯PHP的.zip格式的压缩包。

导入Demo工程

  1. 将下载的PHP SDK Demo解压到本地。
  2. 打开PhpStorm,选择菜单File > Open ,再选择Demo解压后的路径,单击“OK”

  3. PHP SDK Demo目录结构如下,Demo工程中的extend下已包含SDK库。

初始化及证书配置

新建一个NorthApiClient实例,设置好ClientInfo(包括平台IP、端口、appId和密码),再初始化证书。

平台IP、端口、appId和密码都是从配置文件./config/application.ini中读取的,因此,当这些信息发生变化时,只要修改配置文件,不用修改应用服务器的代码。本章节所指的证书是平台提供的,在调用平台接口过程中使用;一般情况下,与回调使用的证书不一样。

  • 使用测试证书:
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    $northApiClient = new NorthApiClient(); 
    
    PropertyUtil::init() 
    
    $clientInfo = new ClientInfo(); 
    $clientInfo = new ClientInfo();
    $clientInfo->platformIp = PropertyUtil::getProperty("platformIp");
    $clientInfo->platformPort = PropertyUtil::getProperty("platformPort");
    $clientInfo->appId = PropertyUtil::getProperty("appId");
    $clientInfo->secret = PropertyUtil::getProperty("secret"); 
    
    $northApiClient->clientInfo = $clientInfo;
    $northApiClient->initSSLConfig(); //默认使用测试证书,且不进行主机名校验
    
  • 如果不使用测试证书,可使用指定证书(如商用证书):
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    self::$northApiClient = new NorthApiClient(); 
    
    PropertyUtil::init() 
    
    $clientInfo = new ClientInfo(); 
    $clientInfo = new ClientInfo();
    $clientInfo->platformIp = PropertyUtil::getProperty("platformIp");
    $clientInfo->platformPort = PropertyUtil::getProperty("platformPort");
    $clientInfo->appId = PropertyUtil::getProperty("appId");
    $clientInfo->secret = PropertyUtil::getProperty("secret");  
    
    $sslConfig= new SSLConfig(); 
    $sslConfig->trustCAPath = PropertyUtil.getProperty("newCaFile"); 
    $sslConfig->selfCertPath = PropertyUtil.getProperty("newClientCertFile"); 
    
    self::$northApiClient->clientInfo = $clientInfo;
    $northApiClient->initSSLConfig($sslconfig); //使用指定的证书,且默认使用严格主机名校验
    

业务接口调用方法

设置好NorthApiClient实例后才能调用其他业务接口。以如下几个接口为例说明如何调用业务接口:

关于哪些参数需要设置,请查看《应用侧PHP SDK API参考》。对于可选参数,如果业务不需要,可以不设置或者设置为null。

配置日志

1
2
3
4
5
6
7
8
//在每个业务接口中都打印了日志
//开发者可通过修改config/log4php.xml配置文件来控制日志的输出

//value:日志的输出路径,默认在工作路径d:/php_sdk/log/,默认日志名称为php_sdk.log。
<param name="file" value="d:/php_sdk/log/php_sdk.log" />

//level:日志等级,默认INFO,如果value=OFF ,则会关闭日志。
<level value="INFO" />

鉴权

1
2
3
4
5
6
7
8
//得到NorthApiClient实例后,再使用$northApiClient得到鉴权类实例 
$authentication = new Authentication($northApiClient); 

//调用鉴权类实例authentication提供的业务接口,如getAuthToken 
$authOutDTO = $authentication->getAuthToken(); 

//从返回的结构体authOutDTO中获取需要的参数,如accessToken 
$accessToken = $authOutDTO->accessToken;

订阅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
//得到NorthApiClient实例后,再使用northApiClient得到订阅类实例 
$subscriptionManagement = new SubscriptionManagement($northApiClient); 

//先设置好subDeviceData的第一个入参SubDeviceDataInDTO结构体 
$sddInDTO = new SubDeviceDataInDTO(); 
$ddInDTO->notifyType= "deviceDataChanged"; 
//需要根据实际情况修改回调的ip和端口 
$ddInDTO->callbackUrl = "https://XXX.XXX.XXX.XXX:8099/v1.0.0/messageReceiver"; 
try { 
    //调用订阅类实例subscriptionManagement提供的业务接口,如subDeviceData 
    $subDTO = $subscriptionManagement->subDeviceData($sddInDTO, null, $accessToken); 
    echo $subDTO; 
} catch (NorthApiException $e) { 
    echo $e; 
}

注册设备

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
//得到NorthApiClient实例后,再使用northApiClient得到设备管理类实例 
$deviceManagement = new DeviceManagement($northApiClient); 

//设置好注册设备接口的第一个入参RegDirectDeviceInDTO2结构体 
$rddInDTO = new RegDirectDeviceInDTO2(); 
$nodeid = "86370303XXXXXX"; //this is a test imei 
$verifyCode = $nodeid; 
$rddInDTO->nodeId = $nodeid; 
$rddInDTO->verifyCode = $verifyCode; 
$rddInDTO->timeout = $timeout; 

//调用设备管理类实例deviceManagement提供的业务接口,如regDirectDevice 
$rddod = $deviceManagement->regDirectDevice($rddInDTO, null, $accessToken); 

//从返回的结构体rddod中获取需要的参数,如deviceId 
$deviceId = $rddod->deviceId;

回调接口实现及证书制作

回调接口实现

需要接收哪一类消息就修改 PushMessageReceiverTest类中对应的方法,如:
1
2
3
4
function handleDeviceAdded($body) {
    echo "deviceAdded ==> " . $body . "\r\n";
    //TODO deal with deviceAdded notification
}

接收到平台推送的消息后,开发者需要根据业务进行处理,但不建议进行复杂计算、I/O操作或者可能长时间等待的动作,可以先写数据库,应用进入相应界面或者刷新界面再从数据库取数据并进行数据处理。

回调路径已在SDK中设置好了,所以在订阅时要注意设置对应的回调地址。回调的IP地址则是服务器的地址,需要是公网地址。Demo工程的回调端口配置在config\application.ini中:

#specify the port of the web application  server.port=8099

回调证书制作

本章节以自签名证书为例。如果是使用商用证书,请直接向CA机构申请。

注:每个步骤的创建证书请求中的配置,请自行设置。“Common Name (e.g. server FQDN or YOUR name) []:”要输入应用服务器的IP或域名。

  1. 打开windows命令行窗口,输入where openssl,查询是否安装openssl。

    1
    where openssl
    

  2. 创建测试CA证书。

    1. 创建私钥。
      1
      openssl genrsa -out ca-key.pem 1024
      
    2. 创建证书请求。
      1
      openssl req -new -out ca-req.csr -key ca-key.pem
      
    3. 自签署证书。
      1
      openssl x509 -req -in ca-req.csr -out ca-cert.pem -signkey ca-key.pem -days 3650
      

  3. 生成server证书。

    1. 创建私钥。
      1
      openssl genrsa -out server.key 1024
      
    2. 创建证书请求。
      1
      openssl req -new -out server-req.csr -key server.key
      
    3. 自签署证书。
      1
      openssl x509 -req -in server-req.csr -out server.cert -signkey server.key -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial -days 3650
      

  4. 生成client证书。

    1. 创建私钥。
      1
      openssl genrsa -out client.key 1024
      
    2. 创建证书请求。
      1
      openssl req -new -out client-req.csr -key client.key
      
    3. 自签署证书。
      1
      openssl x509 -req -in client-req.csr -out client.cert -signkey client.key -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial -days 3650
      

  5. 在Demo工程中,已经配置好生成的server证书。
  6. 单击“启动”PushMessageReceiverTest,选择“Run” “PushMessageReceiverTest”

    当有数据推送到应用服务器时,就会进入相应的回调函数中。

回调证书导出

  1. 使用浏览器打开回调地址https://server:8099/v1.0.0/messageReceiver,以Google为例,并查看证书。

    server是应用服务器的地址(即本机地址),8099是在application.properties中配置的端口。

  2. 系统将弹出证书窗口,选择“详细信息”,单击“复制到文件”

  3. 单击“下一步”,进入“导出文件格式”界面,选择“Base64编码”,然后单击“下一步”

  4. 指定证书的保存路径,完成证书导出。

    如果应用服务器最后部署到云上,可能会有多级证书,建议在部署完成后再导出证书。此时需要将证书链上面几级的证书一一导出

    1. “要导出的文件”界面,单击“浏览”,选择一个路径,输入文件名,单击“保存”,回到证书导出向导,单击“下一步”

    2. 单击“完成”,完成证书导出。

  5. 若存在多级证书,需一一导出。

    1. “证书”窗口,选择“证书路径”,查看多级证书,选中证书路径中的某个证书,单击“查看证书”

    2. 系统将弹出证书窗口,选择“详细信息”,然后重复上述导出证书的步骤,导出已选证书。

  6. 使用文本编辑器,将所有导出的证书以首尾相连的方式,合并为一个.pem格式的文件。该文件需要上传到物联网平台相应的应用下。

回调证书上传

  1. 登录开发中心,进入相关项目。
  2. 选择应用 > 对接信息,单击“证书管理”
  3. 单击“添加”,上传证书。

业务接口调用流程及注意事项

  • 请按如下流程调用业务接口。

  • Demo中使用的Profile如下图所示,只有一个Brightness服务,Brightness服务下有一个brightness属性和一个PUT命令。在调用创建设备命令或设备服务调用等接口时,如果不是使用以下Profile内容,请将相关服务、属性或者命令名称修改为相应的名称。

  • 创建新的Profile方法:

    登录开发者中心,选择产品 > 产品开发 > 添加 > 自定义产品,点击“自定义产品”,进入“设置产品信息”页面。填写“产品名称”“型号”“厂商ID”“所属行业”“设备类型”“接入应用层协议类型”等产品信息,点击“创建”。然后点击“+新建服务”(根据设备功能添加属性和命令)最后点击“保存”

  • 修改设备信息接口使用到的字段值如“设备类型”“厂商名”“厂商ID”“设备型号”要与Profile定义的保持一致。
  • accessToken可以由SDK管理,也可由第三方应用自行管理,具体信息参考《PHP SDK API参考文档》中应用安全接入 > 定时刷新token 章节的说明。
分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区