自定义云服务开发

本节介绍如何将智能灯云端自定义云服务 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 就是开发者给自己的自定义云服务标记的版本号（便于开发者管理版本）。

因此，一般来说，开发者可以任性修改 artifactId 和 version，groupId 则保持不变。

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 包了。
比如，在第一步中开发者设置的 artifactId 是 demo_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查看历史开关记录，跟自定云服务进行联调。