自定义云服务开发

本节介绍如何将智能灯云端自定义云服务 Demo运行在AbleCloud提供的云应用引擎之上。

以下内容假设开发者有一定的 Java 基础,确保安装1.7版本及以上版本的JDK。

环境安装

首先请按照如下文档安装 IntelliJ IDE 和 Maven(至少 3.2 以上版本)。

安装好 Maven 后,使用 mvn -version 来检查是否安装成功。

本地运行 Demo

开发者首先在本地进行开发和调试自定义云服务,可在本地运行自定义云服务,方便调试和查看问题。

注意:
1.本机运行自定义云服务要求已安装 Java 的运行时环境 JRE(推荐 1.7 或更新版本)。
2.DemoService只能在英文目录下执行。

步骤如下:

Step 1

从 AbleCloud 下载页面下载智能灯的云端 自定义云服务demo。
解压后包括两个部分,其中/src 是自定义云服务的源代码,/package 的目录结构则是自定义云服务的打包结构、不能随意修改。

Step 2

进入 /package 目录。修改 /config 文件夹下的 cloudservice-conf.xml 文件。

按照下面注释的信息,分别填写开发者 ID、开发者秘钥对、主域子域信息。

开发者 ID,开发者秘钥对(access-key,secret-key),主域子域等信息,均能登录 AbleCloud 开发者控制台获取:

  • 开发者 ID:【个人中心 => 开发者 ID】获取。
  • 开发者秘钥对:【服务管理 => 开发秘钥】任选一对 AK/SK 签名秘钥即可(AK/SK 签名原理请参考这里)。
  • 主域:【个人中心 => 主域】获取。
  • 子域:【产品管理】页面上,查看特定产品的子域。
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <developer>
        <!-- 控制台路径:【个人信息->个人信息->开发者ID】 -->
        <id>此处填写你的开发者ID</id>
    </developer>

    <authentication>
        <!-- 控制台路径:【密钥对管理->全部密钥对】,选择已启用的任意一对。 -->
        <access-key>此处填写开发者 access-key</access-key>
        <secret-key>此处填写开发者 secret-key</secret-key>
    </authentication>

    <service>
        <!-- 控制台路径:【产品管理->产品列表->主域名】 -->
        <major-domain>此处填写你的主域名</major-domain>
        <!-- 控制台路径:【产品管理->产品列表->子域名】 -->
        <sub-domain>此处填写自定义云服务对应的产品的子域名</sub-domain>
    </service>
</configuration>

Step 3

demo 中为了能够查询开关状态属性纪录,需要持久化存储设备上报的开关记录数据。

通过开发者管理控制台的【产品管理=>智能灯Demo=>属性管理】完成设备上报属性参数的定义。
定义好的属性如下图所示:

demoservice_property


Step 4

进入 /package 目录。

Linux 下,在终端运行如下命令启动服务:

sh start.sh

Windows 下,在 cmd 窗口中运行如下命令启动服务:

start.cmd

至此,本地自定义云服务提供 Restful API 的一个服务就已经启动了,通过文件夹下的 /log 目录可以看到服务运行的日志。

本地启动自定义云服务成功后,可使用 curl 命令进行测试。

注意: Linux 系统上如果没有 curl 则使用诸如 apt-get install curl(Ubuntu、Debian)或者 yum install curl(RedHat、Fedora)的方式来安装。 Windows 系统上安装 curl 的方法见这里

测试用的 curl 指令如下:

注意: 下面的 curl 指令中有两处需开发者自行修改:

  1. X-Zc-Major-Domain: DOMAIN_NAME 中的 DOMAIN_NAME 替换成开发者主域。
  2. X-Zc-Sub-Domain: SUBDOMAIN_NAME 中的 SUBDOMAIN_NAME 替换成产品子域。

主域和子域参考上述《本地运行 Demo》里的 Step 2

curl -v -X POST -H "Content-Type:application/x-zc-object" -H "X-Zc-User-Id:1" -H "X-Zc-Major-Domain: DOMAIN_NAME" -H "X-Zc-Sub-Domain: SUBDOMAIN_NAME" --data-ascii "{\"action\":\"I am test\"}" "http://localHost:8080/test"

简单解释一下上面的 curl 指令(更多 curl 用法请参考 curl 手册):

  • -v 表示 verbose 即显示 HTTP 通信交互详情。
  • -x POST 表示使用 HTTP POST 方法。
  • -H 表示 HTTP 请求头。
  • --data-ascii 表示本请求的 HTTP body 格式是 ASCII。 其余经常用到的格式还有 --data-binary,即按照字节流(octet stream)来发送请求;具体使用请参考 curl 手册,此处不赘述。
  • "http://localHost:8080/test" 表示给本地 8080 端口运行的自定义云服务的 test 方法发送请求。 8080 是自定义云服务demo本地默认的端口号,见 /config 文件夹下的 cloudservice-conf.xml 文件,<service> <port> 配置。 test 方法是专供测试使用的一个方法,什么动作都不会触发,只回复一个空HTTP响应(没有任何 payload 的 HTTP 响应)表示请求被正常处理。

发送了上述 curl 指令后,开发者应该可以在控制台上看到类似下面的响应。

< HTTP/1.1 200 OK
< Content-Type: application/x-zc-object
< X-Zc-Msg-Name: X-Zc-Ack
< Content-Length: 0

其中:

  • 200 是 HTTP 返回码(表示 HTTP 请求正常返回);
  • X-Zc-Msg-Name 是 AbleCloud 服务框架自定义的 HTTP 请求头,当此值等于 X-Zc-Ack 时表示请求被正常处理(反之,如果是 X-Zc-Err 则表示出现了错误,并会附带错误码和错误详情);

至此,我们已完成了本地运行 自定义云服务demo 和发送 curl 指令进行测试。

发布服务

接下来,我们将阐述如何编译 自定义云服务demo(见下面的《编译自定义云服务工程》),并将编译好的自定义云服务发布至云端(见《发布自定义云服务》。

编译自定义云服务工程

在上面的《环境安装》中,开发者已经安装了 maven 并使用 mvn -version 验证了安装是否成功。

本节中,将阐述如何利用 maven 来编译自定义云服务工程。

非常简单,只需要如下两步。

Step 1

进入下载的 demo 解压缩后的文件夹,修改 maven 的项目对象模型(project object model)文件 pom.xml

修改下面的部分,其余部分都无需变动。

<groupId>com.ablecloud.demo</groupId>
<artifactId>demo_service</artifactId>
<version>1.1.9</version>

上面三项的准确含义,请参考 maven 文档。 简单来说:

  • groupId 就是服务源代码文件夹所在的目录结构;
  • artifactId 是开发者给自己的自定义云服务起的名字(可以任意自定义);
  • version 就是开发者给自己的自定义云服务标记的版本号(便于开发者管理版本)。

因此,一般来说,开发者可以任性修改 artifactIdversiongroupId 则保持不变。

Step 2

依然是在上述文件夹(有 pom.xml 文件的文件夹)内,打开终端(Linux)或者 cmd 窗口(Windows),执行 mvn package 开始打包。

初次打包会花费较长时间,等待一段时间后,就能在终端或者 cmd 中看到类似下面的信息。

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.582s
[INFO] Finished at: Wed Aug 17 16:34:14 CST 2016
[INFO] Final Memory: 8M/151M
[INFO] ------------------------------------------------------------------------

至此,开发者就已经完成了服务编译,可以在项目文件夹的 package/lib 路径下找到对应的 jar 包了。
比如,在第一步中开发者设置的 artifactIddemo_service,那么在 package/lib 文件夹中就能看到刚打包生成的 demo_service.jar 包。

发布自定义云服务

UDS完成本地开发和测试后,按照要求的目录结构打包成 zip,即可上传到 AbleCloud 云应用引擎完成上线发布。

具体步骤如下:

Step 1

进入 demo 文件夹里的 package 路径,然后将 package 路径下所有内容打包成 zip。 再次说明:要求 zip 文件解压缩后能直接得到此目录结构,不能存在其它中间层次的目录。

Step 2

登陆管理控制台,通过【云端服务 => 云应用引擎 => 新建服务】可创建自定义云服务。

upload自定义云服务new service

  • 服务名:填写自定义云服务的名称,如 demo_service
  • 服务描述:填写自定义云服务的描述。

之后,我们就可以在【云端服务 => 云应用引擎】里看到新建的服务了。

Step 3

点击 Step 2 里新建的服务的【查看】,进入该服务的版本管理页进行版本管理。点击右上方的“新建版本”按钮新建版本,并将前述步骤里打包的zip文件上传,操作成功后,服务就可以在AbleCloud的分布式应用引擎里运行了。

upload自定义云服务new version

  • 版本号:AbleCloud 对自定义云服务采取的一种版本约定,即类似于上面在 pom.xml 文件里填写的 version 参数(1.9.1)。
  • App 文件:Step 1 里打包的 zip 包。
  • 描述:用户定义的服务版本文字描述。

Step 4

我们可通过控制台【服务管理 =>自定义云服务 => 版本管理 => 上线/下线】,管理/查看此自定义云服务版本的运行状态了。

设置设备转发

创建完成自定义云服务后,设备可以选择将设备转发到指定的UDS服务,回到之前创建的智能灯设备配置之中,选择将设备数据转发到此自定义云服务。
如下图所示。

数据转发

下一步?

接下来,我们将了解到:

  • 如何使用App Demo进行设备联网配置;
  • 如何使用App Demo进行设备绑定和开关控制,跟设备进行联调;
  • 如何通过App Demo查看历史开关记录,跟自定云服务进行联调。