开发者中心

SmartREST

概述

本参考指南讲述SmartREST协议,所使用的数据格式,以及SmartREST模板的解析和注册。也会提及内置消息和错误信息。更详细的步骤,参见SmartREST指南(/guides/rest/smartrest.html)。

协议

SmartREST 是建立在完善的 HTTP协议上,现在流行的平台都提供一个HTTP客户端,通过它可以访问 SmartREST,因此SmartREST可以工作在几乎任何地方。SmartREST通过特定的/s资源来通信,支持HTTP POST方法实现双向通信。传递的数据格式使用CSV (值和值通过逗号分隔)格式。

下面的示例显示了一个客户端和SmartREST端之间的通信。注意请求中的Authorizationheader和自定义X-Idheader,指定了这个请求使用的SmartREST模板。

POST /s HTTP/1.0
                      Authorization: Basic ...
                      X-Id: ...
                      Content-Length: 13

                      100,1234456
                    

每个SmartREST请求是一行,第一个值是唯一的无符号整数,表明动作和随后的参数的值。

SmartREST端产生下面的响应。注意HTTP响应代码总是200 除非SmartREST端不可用。

HTTP/1.1 200 OK
                      Content-Length: 29

                      200,1,123456,Request result
                    
  • SmartREST 端生成的每一行代表从一系列 SmartREST 请求结果的提取值,包含一个唯一的无符号整数,SmartREST*请求的行数和提取的数据值等等。

注:如果QuarkIoE REST API的响应是空的(例如删除托管对象),则 SmartREST 的响应也是空的。和注册的响应模板无关。

数据格式

CSV (值与值之间用逗号分隔)格式用于与 smartrest 端通信。以下规则必须遵循以确保通信顺畅。

  • 每一行必须由CRLF字符序列结尾。
  • 值总是用逗号(,)分隔的。
  • 如果一个值包含双引号(")、逗号(),前置或后置空格,换行或TAB符,它必须用引号括起(")。包含双引号(")必须被转义产生另一个双引号("")。
示例

下面的例子说明了上面所说的规则:

100,Hello world!
                    101," I have leading whitespace!"
                    102,"I have trailing whitespace!"
                    103,"I contain a line
                    break!"
                    104,"I have ""quotes""!"
                    105,I also have 'quotes'!
                  

模板

SmartREST 模板是一系列用于 QuarkIoE REST API调用转换的请求和响应的模板。此外, SmartREST 模板包含一个模板标识符,这是相对于自定义X-Idheader字段识别用于处理 SmartREST*模板。

每个请求和响应的模板都有一个唯一的数字标识符称为消息标识符,每个 SmartREST 请求或响应行的第一个值都引用它。为了避免与默认的消息标识符发生冲突,建议开发人员选择从"100"开始的消息标识符。

请求模板

请求模板包含所有必要的信息,将 SmartREST 请求转换为相应的REST API调用,然后发送到平台。

一个请求模板包含以下信息:

  • 一个唯一的无符号整数作为消息标志符。
  • 请求的方法,例如 GETPOST
  • 资源URI,例如 /inventory/managedObjects
  • 收发数据的Content-TypeAccept header 值
  • 一个占位符例如 %%
  • 预期的请求参数,例如STRINGNUMBERUNSIGNED整数和 DATE
  • 包含每个参数占位符的模板字符串。
响应模板

响应模板包含所有必要的信息,从一个平台REST API调用的响应中提取数据值,然后用 CSV 数据格式作为响应发送回客户端。

下面的信息包含在响应模板中:

  • 一个唯一的无符号整数作为消息标志符。
  • 一个JSON路径,引用基类对象或对象列表来从例如 $$.managedObjects提取数据。如果JSON路径指向一个对象列表,产生列表中的每个对象提取的一行数据。
  • 一个在基本对象或对象的列表中必须存在的JSON路径,用于提取值,如$.id。该值不添加到响应中。
  • 一系列JSON路径,对应每个提取的值,例如$.id$.name$.type。值按照模板中定义的顺序被添加响应。

注册过程

本参考指南仅仅集中在注册 SmartREST 模板,来使用的 SmartREST ,/s端。另外,模板也可以注册来使用平台目录(inventory)API。

在 SmartREST 模板注册前,必须检查是否存在相同的模板。如果模板已存在,则不需要注册,并产生一个错误消息。

一个 SmartREST 模板是否存在可以用一个空的要求检查:

POST /s HTTP/1.0
                    Authorization: Basic ...
                    X-Id: ...
                    Content-Length: 0
                  

如果模板存在,返回下面的响应,消息标识符20表明在目录(inventory)中模板存在,参数123456表示模板的管理对象的GID:

HTTP/1.1 200 OK
                    Content-Length: 10

                    20,12345
                  

如果模板不存在,则会产生包含错误信息的响应:

HTTP/1.1 200 OK
                    Content-Length: 33

                    40,"No template for this X-ID."
                  

如果模板不存在,可以使用之前发回的X-Id来发出模板注册请求。

模板可以用一个 CSV 数据格式的 SmartREST 模板来注册。一个模板注册请求和一个正常的SmartREST请求之间的区别是,在模板注册中所有行不会被单独处理。

POST /s HTTP/1.0
                    Authorization: Basic ...
                    X-Id: ...
                    Content-Length: 275

                    10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
                    11,201,,"$.c8y_IsDevice","$.id"
                  

如果模板注册成功,类似的响应将被返回。

HTTP/1.1 200 OK
                    Content-Length: 10

                    20,12345
                  
语法

每个请求和响应模板包含在模板数据的一行中。请求模板是由消息标识符"10"标志,响应模板由标识符"11"表示。如果这些消息标识符中的一个出现在 SmartREST 请求中,整个请求作为一个模板。因此,除了10和11的任何其他消息标识符都会产生一个错误。

请求模板

请求模板使用下面的语法:

10,<ID>,<METHOD>,<URI>,<CONTENT>,<ACCEPT>,<PLACEHOLDER>,<PARAMS>,<TEMPLATE>
                  

其中:

  • <ID>是请求模板的的消息标识符。
  • <METHOD>是用于请求的 HTTP 方法,支持GETPOSTPUTDELETE
  • <URI>是资源标识符。
  • <CONTENT>Content-Type header字段值。
  • <ACCEPT>Accept header字段值,差不多等于<CONTENT>
  • <PLACEHOLDER>是占位符字符串, 会被请求URI中参数和模板字符串替换。
  • <PARAMS>是模板需要的参数类型列表,使用空格分隔。 请求URI和模板字符串的占位符字符串出现次数必须等于指定参数的个数。
  • STRING参数如果没有指定值只会产生一个错误。
  • UNSIGNED参数如果提供的参数不是一个无符号整数,则会产生一个错误。
  • INTEGER参数如果提供的参数不是一个有符号整数,则会产生一个错误。
  • NUMBER参数如果提供的参数不是一个浮点数,则会产生一个错误。
  • DATE参数如果提供的参数不能解析为日期值,则会产生一个错误。
  • NOW 参数永远不会产生错误。不需要请求参数。
  • <TEMPLATE>是参数值替代占位符后,作为发往平台负载的实际的模板字符串。
示例
10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
                  

解释:

  • 10 代表一个请求模板。
  • 100 是一个请求模板的消息标志符。
  • POST是使用的 HTTP 方法。
  • /inventory/managedObjects是资源标识符。
  • application/vnd.com.nsn.cumulocity.managedObject+json是"Content Type"。
  • application/vnd.com.nsn.cumulocity.managedObject+json 是"Accept Content Type"。
  • %% 占位符字符串。
  • STRING 表示请求只接受一个参数,参数必须是一个字符串。
响应模板

响应模板使用下面的模板:

11,<ID>,<BASE>,<COND>,<VALUE>[,<VALUE>]
                  

其中:

  • <ID> 是响应模板的消息标识符。
  • <BASE> 是指向一个提取值的对象列表的基本的JSON路径
  • <COND> 是一个需要检查是否存在的有条件的JSON路径。如果路径存在,数值被提取。
  • <VALUE> 是一个指向在基本对象或者在基本对象列表里提取值的JSON路径。 可以指定不受数量限制的<VALUE>
示例
11,201,,"$.c8y_IsDevice","$.id"
                  

解释:

  • 11 表示一个响应模板。
  • 201 是响应模板的消息标志符。
  • 基本对象的JSON路径为空,则默认假设为$
  • $.c8y_IsDevice表示只有对象有个c8y_IsDevice片段,值才会被提取。
  • $.id 是提取的设备ID的值。

用多X-Id使用SmartREST

SmartREST支持在相同的请求中给不同的X-Id发送消息。这种情况不可以使用X-Id header,但在正文(body)里可以包含哪行属于哪个X-Id的附加信息。

发送消息

为了表明正文(body)中的X-Id,可以包含下面的行:

15,myxid
                  

下面的所有行都将被处理成给的X-Id,直到你输入下一个X-Id行。

15,myxid1
                    ...
                    ...
                    15,myxid2
                    ...
                  
接受消息

当使用多X-Ids发送时,响应也可以包含来自多个X-Ids的响应。响应将包含额外的行来表明下面的行是从哪个X-Id来的。 这行里的第二个值表示下面的多少行是从这个X-Id来的。

87,2,myxid1
                      ...
                      ...
                      87,1,myxid2
                      ...
                    
查看模板是否已经注册

你可以在正文(body)里包含X-Id行来检查模板是否已经存在。

15,myxid1
                      15,myxid2
                      15,myxid3
                      15,myxid4
                    

你将得到相同的响应,如在注册过程中每行所描述的正文。

20,12345
                      20,12346
                      40,"No template for this X-ID."
                      20,12347
                    
注册模板

模板注册还支持在正文(body)中使用X-Id。因此,可以在一个单一的请求中创建多个。

15,myxid1
                      10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
                      11,201,,"$.c8y_IsDevice","$.id"
                      15,myxid2
                      10,100,POST,/inventory/managedObjects,application/vnd.com.nsn.cumulocity.managedObject+json,application/vnd.com.nsn.cumulocity.managedObject+json,,,"{""name"":""Test Device"",""type"":""com_example_TestDevice"",""c8y_IsDevice"":{}}"
                      11,201,,"$.c8y_IsDevice","$.id"
                    

SmartREST实时通知

所有可用的QuarkIoE平台实时通知终端和channel在smartrest也是可用的。请在实时通知参考指南来了解Bayeux协议的通用功能。

和SmartREST一起使用实时通知

为了告诉QuarkIoE平台实时通知应使用smartrest,所有发送到URL的请求必须包含X-Id头。

消息标识符
消息标识符 消息参数 描述
80 None 初始握手,会返回一个唯一的贝叶clientId。
81 clientId,channel 订阅指定的channel。
82 clientId,channel 退订指定的channel。
83 clientId 建立接受通知的连接。 (长连接long-polling)。
84 clientId 断开客户端和服务器的连接。
握手

示例 request:

80
                    

示例 response:

Un1q31d3nt1f13r
                    
订阅

示例 request:

81,Un1q31d3nt1f13r,/mychannel
                    

示例 response:

除非有一个错误,否则没有订阅的特定响应。

退订

示例 request:

82,Un1q31d3nt1f13r,/mychannel
                    

示例 response:

除非有一个错误,否则没有退订的特定响应。

连接

示例 request:

83,Un1q31d3nt1f13r
                    

示例 response:

响应是由一组X-Id通过SmartREST注册的响应模板组成。实时的每一个收到的通知将使用可用的模板解析,每一个匹配的模板将作为连接请求的响应返回。

保活Keep-Alive:

QuarkIoE平台将通过一个建立的长连接每隔10分钟发送一个空格字符,用来检测连接是否断开。一个已经建立了较长时间的连接响应,在响应的第一行中可以包含一个开头的空格字符。

断开连接

示例 request:

84,Un1q31d3nt1f13r
                    

示例 response:

除非有一个错误,没有断开连接的特定响应。

建议的响应

贝叶(Bayeux)协议有一个特殊的片段来告诉客户端的连接超时的推荐设置、连接请求的间隔和连接响应后的跟进策略。建议将以响应中的单独一行通过SmartREST通信,可以包含在任何上面任何请求的响应中。

响应结构:

86,<timeout>,<interval>,<reconnect policy>
                    

超时(timeout)和间隔(interval)是以毫秒定义的时间的数值。重新连接策略可以是三个值中的一个:

  • none: 不要在连接的响应后重新连接。
  • retry: 在连接的响应后重新连接。
  • handshake: 开始一个新的握手(因为clientId无效/服务器已关闭会话(session))。

一个建议响应行不需要为每一个字段赋值。

示例:

86,,10000,retry
                    
用多个模板订阅

如果设备使用多个模板(例如子设备有和父设备不同的模板),是可以添加这些模板到订阅请求。服务器将使用所有的模板(从header和订阅声明)来解析响应。

示例 request:

POST /devicecontrol/notifications HTTP/1.0
                      Authorization: Basic ...
                      X-Id: mytemplate1

                      81,Un1q31d3nt1f13r,/mychannel,mytemplate2,mytemplate3
                    

在使用多个模板的情况下,响应将包含一个额外的行,指示哪些行被以哪个模板解析:

87,{number of parsed rows},{X-Id used to parse the following rows}

示例 response:

HTTP/1.0 200 OK

                     87,2,mytemplate1
                     100,myvalue
                     101,myvalue2
                     87,1,mytemplate3
                     100,myvalue3
                   

内建消息

SmartREST 有一系列内建的消息。

请求消息
消息标识符 消息参数 描述
10 模板消息标识符
方法
资源标识符
Content MIME类型
Accept MIME类型
占位符
请求参数
模板字符串
代表一个请求模板。如果在正文(body)中出现这个消息,则整个正文(body)会被当成一个 SmartREST 模板,而且除了 10 and 11 的所有消息都会产生一个错误。
11 模板消息标识符
基本JSON路径
有条件JSON路径
值JSON路径
表示一个响应模板。 如果此消息出现在正文(body)中,则整个正文将被视为 SmartREST 模板,因此除了"10"和"11"之外的所有消息都会产生错误。
15 X-Id 定义接下来各行使用的X-Id。 使用此行时,不得使用X-Id标头(Header)。
61 设备MO GId 在设备引导过程中轮询设备凭证。 不能使用X-Id标头(header),并且必须使用设备引导授权。
80 None 初始握手将返回唯一贝叶(bayeux)clientId。 SmartREST实时通知。
81 clientId,channel 订阅给定的频道(channel)。 SmartREST实时通知。
82 clientId,channel 退订给定的频道(channel)。 SmartREST实时通知。
83 clientId 建立用于接收通知的连接(长轮询)。 SmartREST实时通知。
84 clientId 断开客户端与服务器的连接。 SmartREST实时通知。
响应消息
消息标识符 消息参数 描述
20 SmartREST 模板MO GId 回应响应消息。 模板被找到或已被创建,一切正常。
40 None 模板未找到。
41 行号(可选) 模板创建错误。
42 行号 格式错误的请求行。
43 行号 消息标识符无效。
45 行号 消息参数无效。
50 行号
HTTP 响应码
服务器错误。 当 SmartREST 代理和平台之间发生错误时,会出现此消息。
70 行号
唯一设备标识符
租户ID
用户名
密码
使用证书设备引导轮询响应。
86 超时,间隔,重新连接策略 使用SmartREST实时通知的客户端的设置建议。
87 行数, X-Id 指示使用哪个X-Id创建接下来响应行的数量。
错误消息
消息标识符 错误消息
41 无法为已存在的模板对象创建模板。
41 不允许重复的消息标识符。
41 错误的请求模板定义。
41 错误的响应模板定义
41 错误数值类型: ...
41 错误模式。
41 不是模板创建的有效消息标识符。
41 无效JsonPath。
41 使用JsonPath来引用对象列表不适用于SmartRest。
41 SmartRest不允许在JsonPath中使用过滤器(?)。
41 没有{GET或DELETE}模板支持的内容类型。
41 没有支持{GET或DELETE}模板的模板字符串。
41 找不到{POST或PUT}模板的内容类型。
41 找不到{POST或PUT}模板的模板字符串。
41 仅支持带有占位符的模板的值。
42 格式错误的请求。
43 无效的消息标识符。
45 不支持参数。
45 参数数量错误
45 数值不是 {value type}: {value}

© 2010-2017 QuarkIoE