开发者中心

REST实现

概述

本节描述的是QuarkIoE是如何实现REST接口进行外部通讯的。接口是基于 Hypertext Transfer Protocol, version 1.1使用HTTPS

HTTP 使用

认证

所有request需要包含HTTP "Authorization" header。格式是:

Authorization: Basic <<Base64 encoded credentials>>
                      

Wikipedia entry上可以找到一个示例。OAuth认证,格式是:

Authorization: Bearer <<Base64 encoded access token>>
                      

QuarkIoE使用URL在"Host" header确定进行身份验证的租户。另外,可以用将租户的ID作为"Authorization"header的一部分,使用下面的格式:

<<tenant ID>>/<<user name>>:<<password>>
                      

通常情况下,租户ID对应访问QuarkIoE的URL的第一部分。例如,如果你使用URL"mytenant.quarkioe.com",租户ID是"mytenant"。

应用管理

QuarkIoE使用 "application key" 来区分来自设备还是应用的请求。如果你写一个应用程序,提交下面的header作为所有请求的一部分:

X-Quarkioe-Application-Key: <<application key>>
                      

例如,如果你在QuarkIoE的系统管理应用里使用关键字"MyApp"注册应用程序,提交

X-Quarkioe-Application-Key: myapp
                      

这将使你的应用程序可订阅和可付费。如果在设备上,则不需要提交。

确保你在来自应用程序的所有请求中传递这个key。如果你漏掉了这个key, 该请求将被视为一个设备请求,相应的设备将被标记为"可用"。

受限的HTTP客户端

如果使用一个只能在HTTP中执行GET和POST方法的HTTP客户端,你可以通过一个额外的"x-http-method"header来模拟其他方法。只需要发出一个POST request并添加header,指定要执行的实际的REST方法。例如,要模拟"PUT" (修改)方法,可以使用:

POST ...
                          X-HTTP-METHOD: PUT
                        
处理模式

每一个更新请求(PUT, POST, DELETE)都用一个所谓的处理模式来执行。默认的处理方式是持续性的,这意味着所有的更新将被发送到cumuloity数据库并进行实时处理。选择处理模式PERSISTENT将只发送更新的实时处理。在实时处理部分,用户可以决定个案通过quarkioe事件语言脚本更新是否应该存储到数据库或不。

为了显式地控制一个更新请求的处理方式,可以用一个"x-cumulocity-processing-mode"header,值设置为"PERSISTENT"或者"TRANSIENT"::

X-Quarkioe-Processing-Mode: TRANSIENT
                        
认证(Authorization)

所有发往QuarkIoE的请求都需要认证。要确定所需的权限,参见各个请求的参考文档中的条目"需要角色权限"。 了解QuarkIoE更多关于不同的权限和所有权的概念,参见"权限管理和所有权",章节"安全因素"。

媒体类型

每种类型的数据都与一个媒体类型相关联。媒体类型的一般格式是

application/vnd.com.nsn.cumulocity.<<type>>+json;ver=<<version>>;charset=UTF-8
                          

每个媒体类型包含一个参数"ver"表示类型的版本。在文档编写的时候,最新版本是"0.9"。在参考指南的各个相关章节中给出了完整的媒体类型名称。作为一个示例,当前版本中的错误消息的媒体类型是

application/vnd.com.nsn.cumulocity.error+json;ver=0.9;charset=UTF-8
                          

媒体类型是用于HTTP中"Content-Type" 和 "Accept" 的header。如果你在一个"POST"或"PUT"的请求中指定了一个"Accept"的header,则响应将包含新创建的或更新的对象。如果不指定header,则响应内容将为空。

如果一个媒体类型没有给定"ver"参数,服务器返回最老的版本号。如果accept header包含同一媒体类型的多个版本号,服务器将返回最新支持的版本的表述。

数据格式

QuarkIoE使用HTTP请求和响应完成数据交换,编码格式是JSON 格式UTF-8字符编码。收到和发出的时间和日期使用格式ISO 8601:

Date: YYYY-MM-DD
                            Time: hh:mm:ss±hh:mm
                            Timestamp: YYYY-MM-DDThh:mm:ss±hh:mm
                          

为避免歧义,所有的时间和时间戳必须包含时区信息。请记住加号字符"+"必须被编码为"%2B"。

错误报告

发生错误的时候,QuarkIoE返回标准HTTP的响应代码(response code),参见RFC2616。 客户端不仅要能够处理单个的代码,而且还要处理一类的代码. (例如4xx). 响应内容可以包含详细的错误信息, 参见下面的错误媒体类型定义。 常用的错误解释是:

代码 名字 描述
400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized Authentication has failed, or credentials were required but not provided.
403 Forbidden You are not authorized to access the API.
404 Not Found Resource not found at given location.
405 Method not allowed The employed HTTP method cannot be used on this resource (e.g., using "POST" on a read-only resource).
409 Update Conflict Conflict on resource update, entity was changed in the meantime.
409 Duplicate The entity already exists in the data source.
422 Invalid Data General error with entity data format.
422 Non Unique Result Resource constraints error. Non-unique result from the query.
422 Unprocessable entity Resource cannot be processed.
500 Internal Server Error An internal error in the software system has occurred and the request could not be processed.
503 Service Unavailable The service is currently not available. This may be caused by an overloaded instance or it is down for maintenance. Please try it again in a few minutes.

REST 使用

HTTP verbs解释

HTTP规范讲述的语义:

  • POST创造了一个新的资源。在响应(response)"Location"header,返回最新创建的资源的URI。
  • GET 取回一个资源。
  • PUT 用请求的内容更新一个现有资源。
  • DELETE 删除资源。响应将是"204没有内容"。

如果一个PUT请求只包含一个资源的一些部分,称为"fragments",只有包含的部分被更新。要删除一个片段,使用一个片段值为null的PUT请求。PUT无法更新由一个单独的URI标识的子资源。

URI空间和URI模板

客户端不应在请求中对URI布局作出假设,但可以用以前返回的URI和URI模板构造URI。根接口为客户端提供了入口点,参见下面。 URI模板包含使用大括号的占位符,它需要由客户端填写来生成一个URI。作为一个例子,参见下面的事件API响应摘录:

HTTP/1.1 200 OK
                              Content-Type: application/vnd.com.nsn.cumulocity.eventApi+json;...
                              Content-Length: ...

                              {
                              ...
                              "events" : { "self" : "http://..." },
                              "eventsForSourceAndType" : "http://...?type={type}&source={source}"
                              ...
                            }
                          

客户端需要用实际返回事件的类型和设备源填写"type"和"source"占位符。这些占位符的含义可以在参考指南各自的接口描述中找到。

接口(Interface)结构

总的来说,QuarkIoE的REST资源根据以下的模式来建模:

  • 出发点是API资源,提供在资源集合里通过URI和URI模板来访问实际数据的方式。例如,上述事件API资源提供"events"URI和"eventsforsourceandtype"URI来访问事件集合。
  • 资源集合包含了子资源,并允许在集合中创建新子资源。例如,通过"events"集合资源,可以创建新的事件。
  • 最后,单个的资源可以编辑。
请求结果分页

资源集合支持数据分页,以避免在从客户端到服务器的一个块中传递过大的数据量。对集合的GET请求接受两个查询参数:"pageSize"表示一次返回集合的多少条目。默认情况下,返回5个条目。一页的上限是目前2000,任何更大的要求的页面大小被限制到上限。"currentpage"定义当前返回的数据片,从"1"开始。默认情况下,返回第1页。

为方便,资源集合提供了一个"next"和"prev"的链接来取回下一页和前一页。这是一个托管对象集合的示例响应:

{
                            "self" : "...",
                            "managedObjects" : [
                            ...
                            ],
                            "statistics" : {
                            "totalPages" : 7,
                            "pageSize" : 5,
                            "currentPage" : 2
                          },
                          "prev" : "http://...?pageSize=5&Page=1",
                          "next" : "http://...?pageSize=5&Page=3"
                        }
                      

请注意,总页数"totalPages"的属性计算很耗时,因此它不是在范围查询中默认返回。需要在结果中包含总页数"totalPages",添加查询参数"withtotalpages = true"。

根接口

为了找到QuarkIoE的各个接口的URI,需要提供一个"root"根接口。这根接口包含所有底层的API资源。有关不同的API资源的更多信息,请查询参考指南的相应的接口部分。

Platform [application/vnd.com.nsn.cumulocity.platformApi+json]
名字 类型 出现次数 描述
self URI 1 这个资源的链接
inventory InventoryAPI 1 参见 设备清单 接口。
identity IdentityAPI 1 参见 身份标识 接口。
event EventAPI 1 参见 事件 接口。
measurement MeasurementAPI 1 See 测量值 接口。
audit AuditAPI 1 参见 审计 接口。
alarm AlarmAPI 1 参见 报警 接口。
user UserAPI 1 参见 用户 接口。
deviceControl DeviceControlAPI 1 参见 设备控制 接口。
GET Platform资源

应答正文: application/vnd.com.nsn.cumulocity.platformApi+json

应答示例:

HTTP/1.1 200 OK
                        Content-Type: application/vnd.com.nsn.cumulocity.platformApi+json;...
                        Content-Length: ...

                        {
                        "self" : "<<URL to the platform API resource>>",
                        "event" : {
                        "self" : "<<URL to the event API resource>>",
                        "events" : { "self" : "<<URL to event collection resource>>" },
                        "eventsForSourceAndType" : "<<URL to event collection resource>>?type={type}&source={source}"
                        ...
                      },
                      "inventory" : {
                      ...
                    },
                    ...
                  }
                

常用媒体类型

报错 [application/vnd.com.nsn.cumulocity.error+json]

错误类型提供了关于失败请求的原因的进一步信息。

名字 类型 出现次数 描述
error String 1 错误类型用下面的格式 "<<resource type>>/<<error name>>". 例如一个对象在目录里没有找到,表示为 "inventory/notFound"。
message String 1 错误的简短文字描述。
info URL 1 Internet上对错误描述的链接。
details Error details 1 错误的详细信息。 只适用于DEBUG模式。

错误详细信息由下面的结构来提供:

名字 类型 出现次数 描述
expectionClass String 1 导致错误的异常的Class名。
exceptionMessage String 1 异常信息内容。
expectionStackTrace String 1 异常的跟踪栈信息。
- - - 依据错误类型的进一步诊断信息。
分页统计 [application/vnd.com.nsn.cumulocity.pagingStatistics+json]

在以下格式中提供了资源集合的分页统计:

名字 类型 出现次数 描述
totalRecords Integer 1 记录的大致总数。
pageSize Integer 1 这次请求中包含的最大记录数。
currentPage Integer 1 在结果中返回的当前页码, 从"1"开始。