开发者中心

Hello REST!

概述

本节给出了一个非常基本的例子,如何在QuarkIoE创建一个设备表示并发送相关测量数据。 所有步骤都通过调用REST接口完成。 这些REST调用通过命令行执行CURL语句展示。 CURL的简短介绍请参看前面的章节

前提条件

为遵循本教程,请检查是否完成了以下的前提条件:

  • 有一个可以访问QuarkIoE的有效租户,用户名和密码。
  • 系统已经安装命令行工具CURL。

前提条件

执行REST调用

我们按顺序执行两个REST调用,详细描述如下:

  • 步骤 1: 在QuarkIoE目录清单创建一个新设备
  • 步骤 2: 发送此设备相关的测量数据

现实世界中,这些步骤由'设备agent'执行。 步骤 1 只在设备第一次连接到QuarkIoE时执行一次。 此后,通过在执行此步骤时返回的内部ID来执行与该设备相关的操作。

创建新设备

在QuarkIoE设备清单清单中创建新设备需要下面的REST请求:


   POST /inventory/managedObjects HTTP/1.1
	Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
	Accept: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
	Authorization: Basic <<Base64 encoded credentials <tenant ID>/<username>:<password> >>
	...
	{
	"c8y_IsDevice" : {},
	"name" : "HelloWorldDevice"
}
                    	

此调用可以通过执行以下CURL语句来完成:


	curl -v -u <username>:<password> \
		-H 'Accept: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9' \
		-H 'Content-type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9' \
		-X POST \
		-d '{"c8y_IsDevice":{},"name":"HelloWorldDevice"}' \
		http://<tenant-ID>.cumulocity.com/inventory/managedObjects
                    	

请用注册到QuarkIoE时得到的相应凭证替换 <username>, <password> 和 <tenant-ID> 。 用访问QuarkIoEWeb GUI同样的凭证可以执行REST调用。

你将收到下面这样的应答:


    HTTP/1.1 201 Created
	Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
	Authorization: Basic <<Base64 encoded credentials <tenant ID>/<username>:<password> >>
	...
	{
	"id": "1231234"
	"lastUpdated": "2014-12-15T14:58:26.279+01:00",
	"name": "HelloWorldDevice",
	"owner": "<username>",
	"self": "https://<tenant-ID>.cumulocity.com/inventory/managedObjects/1231234",
	"c8y_IsDevice": {},
	...
}
                     	

在创建设备时,QuarkIoE生成一个ID,这是为了进一步调用引用设备。 我们可以在响应中的"id"属性值对找到这个ID。

发送测量数据

现在设备已创建,我们可以发送测量数据。 本例中,我们发送摄氏度单位的温度测量值,一定时间内收集一次:


   POST /measurement/measurements
	Content-Type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
	Accept: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
	...
	{
	"c8y_TemperatureMeasurement": {
	"T": {
	"value": 21.23,
	"unit":"C"
		}
	},
	"time": "2014-12-15T13:00:00.123+02:00",
	"source": {
	"id": "1231234"
	},
	"type":"c8y_PTCMeasurement"
	 	}
				        

请用步骤 1 中得到的数值替换 id。

此外,应该用最新的时间戳更新time值以便QuarkIoEUI后续查找。 请注意 参考指南中时间戳的数据格式。


    curl -v -u <username>:<password> \
	-H 'Accept: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9' \
	-H 'Content-type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9' \
	-X POST \
	-d '{"c8y_TemperatureMeasurement":{"T":{"value":21.23,"unit":"C"}},"time":"2014-12-15T13:00:00.123+02:00","source":{"id":"1231234"},"type":"c8y_PTCMeasurement"}' \
	http://<tenant-ID>.cumulocity.com/measurement/measurements/
				        

请求的应答看起来如下:


HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
...
{
	"id": "4711",
	"self": "https://<tenant-ID>.cumulocity.com/measurement/measurements/4711",
	"source": {
	"id": "1231234",
	"self": "https://<tenant-ID>.cumulocity.com/inventory/managedObjects/1231234"
	},
	    "time": "2014-12-15T12:00:00.123+01:00",
	"type": "c8y_PTCMeasurement",
	"c8y_TemperatureMeasurement": {
	"T" : {
	"unit" : "C",
	"value" : 21.23
	}
	}
}
						

如果愿意,可以重复发送测量值。再次发送请求前,应该更新时间戳 ('time'属性的值)以便创建时间序列。

现在步骤都完成了。进入QuarkIoEWeb GUI, 在"全部设备"选项卡选择设备,进一步选择"测量"选项卡。在这里你可以看到测量数据。 如果看不到,修改过滤器设置,如 "上周" 以包括提交的测量值使用的时间戳。

更进一步

这里展示的顺序REST调用知识是设备集成的一个缩减过程。 第一步 ('创建新设备' 和 '注册设备') 是 '启动阶段'的一部分,而第二部 ('发送测量值') 引用自 '循环阶段'。

实现实际的agent所需要的进一步信息请参考 设备集成 部分。