开发者中心

REST介绍

概述

QuarkIoE所有外部通讯都采用REST。不管通讯从IoT设备发起,从web应用程序发起,还是从后台IT系统发起 — 通讯协议都是 REST。

REST是一种基于HTTP(S) 和 TCP的非常简单和安全的协议。现在它是事实上的互联网标准,支持从简单设备到大规模IT的网络编程环境。 这是众多介绍REST书籍中的一本 RESTful Web 服务

本指南介绍了如何使用QuarkIoE的REST接口实现以下功能

  • QuarkIoE与设备交互。
  • 在QuarkIoE之上开发应用程序。
  • QuarkIoE集成其他云服务和IT后端应用程序。

首先展示通常如何使用REST接口,然后讨论 设备集成 ,最后描述 应用程序开发。该描述和参考指南关系紧密,参考指南详细描述了每个接口。在参考指南中的相关章节如下:

如果开发使用Java ME/SE, JavaScript 或 C/C++, 要更方便的访问QuarkIoE功能请参考相应的开发者指南。此外,如果使用支持的开发板,更多信息请参阅相应的 "设备" 章节。

使用REST接口

现在多数编程环境都对基于REST的通讯有特别支持。使用一些命令行工具或浏览器扩展会有助于测试和理解QuarkIoE的REST接口。

例如,许多操作系统预先安装了 "curl" 命令。如果想开始浏览QuarkIoEAPI,输入以下命令行:


   $ curl -u <username>/<password> https://<yourURL>.quarkioe.com/platform
                    	

用注册到QuarkIoE的用户名和密码替换 "username" 和 "password"。同样的,用注册时的URL替换 "yourURL"。如果订阅了德国电信的M2M DevFree,用"dev-dg"替换"yourURL"。

命令返回QuarkIoE所有基本接口的链接:


...
    "inventory": {
    "managedObjects": {
    "references": [], 
    "self": "https://<yourURL>/inventory/managedObjects"
    }, 
    "managedObjectsForFragmentType": "https://<yourURL>/inventory/managedObjects?fragmentType={fragmentType}", 
    "managedObjectsForListOfIds": "https://<yourURL>/inventory/managedObjects?ids={ids}", 
    "managedObjectsForType": "https://<yourURL>/inventory/managedObjects?type={type}", 
    "self": "https://<yourURL>/inventory"
},
...
            			

在Mac上要得到更好的输出格式,请尝试 "curl ... | python -mjson.tool"。

从这一点开始,可以进一步导航。例如,按照"managedObjects"链接显示设备清单条目:


   $ curl -u <username>/<password> https://<yourURL>.quarkioe.com/inventory/managedObjects
            			

你会注意到实际返回的只是设备清单的一个子集,也就是一"页"。 分页处理的更多信息参见 查询结果分页

使用Postman

查看REST接口和QuarkIoE数据库内容的一个方便方法是使用浏览器扩展,如Chrome浏览器的 PostmanAdvanced REST Client

REST客户端例子

要设置Postman并导入示例REST API命令,点击下面的按钮:

在Postman中运行

安装Postman并导入示例("API集合")。集合带有一个只读环境的示例。 配置进一步的环境:

  • 点击"眼睛"小控件相邻的下拉菜单配置QuarkIoEURL。点击 "Manage environments" 和 "Add"。
  • 然后输入租户名。键"eye"配置为 "https://<yourURL>.quarkioe.com"。点击 "Submit"。
  • 现在,可以运行REST调用。例如,点击 "Quarkioe API", "Quarkioe API Overview", "GET Platform"。点击 "Send" 按钮,可以向QuarkIoE发送GET请求。第一次向QuarkIoE发送请求必须输入凭证。点击 "Basic Auth" 并输入用户名和密码,点击 "Refresh Headers"。
  • 要查看API,点击应答的链接。结果分页导航,点击应答下部的 "next" 链接。 例如, "?pageSize=100" 添加到请求URL后面可以得到比缺省的5个条目多的数据。

请注意Postman有两个问题:即使不指定它也总是发送内容类型。如果看到错误,请按参考手册描述添加"Content-Type"头。有时它也显示"Malformed JSON"作为应答,这是一个Postman的 bug

可以在Postman环境设置一个"auth"键,以便不必每次都输入凭证。"auth"包含Base64编码凭证的HTTP授权头。例如:假设用户名是 "me" ,密码是 "secret"。访问 http://ostermiller.org/calc/encode.html ,在文本域输入 "me:secret",然后在"Base 64"行点击"Encode"按钮。结果是"bWU6c2VjcmV0"。使用 "Basic bWU6c2VjcmV0" 作为"auth"的值。