写点什么

【涂鸦物联网足迹】涂鸦云平台接口说明

用户头像
IoT云工坊
关注
发布于: 2020 年 11 月 09 日
【涂鸦物联网足迹】涂鸦云平台接口说明

前序系列文章>>>【涂鸦物联网足迹】API及SDK介绍


我们系列文章,都会围绕如何完成一款智能“隔空接吻机”的开发。希望能帮到各异地恋__or__异国恋的情侣们!


本文我们会大概讲解基于 OpenAPI 进行开发时所涉及到的 API 调用方法、规范、示例以及集成 SDK 相关内容。内容会比较硬核,请各单位注意!


一、开发流程


  1. 注册开发者账号

  2. 云开发创建云应用项目,获取 client_id & secret。


说明:开发者平台 key 的名称为 accessId & accessKey。


  1. 创建 SDK:在涂鸦 IoT 平台,选择 App 工作台 > App SDK > 获取 SDK > 按要求填写参数 > 获取 schema(渠道标识)。

  2. 基于 OpenAPI 进行业务开发。

  3. 测试无误后,开发者自行发布。


二、授权流程


每个业务 OpenAPI 都需要进行 token 校验。


说明:涂鸦 OpenAPI 遵循 OAuth 2.0 协议标准。


三、简单模式


针对云云对接场景,涂鸦提供了隐式授权的方式获取:



  1. 按照涂鸦云 OpenAPI 接口规范对开发者 client_id 和 secret 进行签名认证。

  2. 涂鸦云校验并颁发令牌给第三方云。


说明:隐式授权方式获取的 token,权限维度为开发者维度,token 的操作权限范围为该开发者有权限操作的范围,例如操作(增、删、改、查)开发者的应用用户数据,产品下的设备数据和应用下用户绑定的设备数据。


四、接口规范


环境说明


各接口使用方请根据自身所在区域调用相应接口。


中国区 https://openapi.tuyacn.com


美洲区 https://openapi.tuyaus.com


欧洲区 https://openapi.tuyaeu.com


印度区 https://openapi.tuyain.com


请求方式


支持的请求方式如下:


  • GET

  • PUT

  • POST

  • DELETE


说明:当请求方式为POST时,Content-Type 需使用application/json


请求头设置


任意接口都需要在 header 中加入如下参数:



说明:业务接口(非 token 接口)请求时需要参数access_token


五、签名规范


涂鸦云采用 HMAC-SHA256 创建摘要,根据不同应用场景,当前提供两套签名算法:


  • 令牌管理接口(获取令牌、刷新令牌)


sign = HMAC-SHA256(client_id + t, secret).toUpperCase()


使用申请到的 client_id 与当前请求的 13 位标准时间戳拼接成待签名的字符串,采用申请到的云应用 secret 作为密钥参与哈希摘要,得到的字符串,最后转大写;


  • 业务接口


sign = HMAC-SHA256(client_id + access_token + t, secret).toUpperCase()


使用申请到的云应用 client_id + 当前有效的请求令牌 + 当前请求的 13 位标准时间戳拼接成待签名的字符串,采用申请到的云应用 secret 作为密钥参与哈希摘要,得到的字符串,最后转大写。


签名示例


  • 准备参数:


client_id:1KAD46OrT9HafiKdsXeg


secret:4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC


t:1588925778000


access_token:3f4eda2bdec17232f67c0b188af3eec1


  • 令牌管理接口签名:


待签名字符串:1KAD46OrT9HafiKdsXeg1588925778000


签名结果:HMAC-SHA256(1KAD46OrT9HafiKdsXeg1588925778000,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)


ceaafb5ccdc2f723a9fd3e91d3d2238ee0dd9a6d7c3c365deb50fc2af277aa83


转大写为:CEAAFB5CCDC2F723A9FD3E91D3D2238EE0DD9A6D7C3C365DEB50FC2AF277AA83


  • 业务接口:


待签名字符串:1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec11588925778000


签名结果:HMAC-SHA256(1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec11588925778000,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)


36c30e300f226b68add014dd1ef56a81edb7b7a817840485769b9d6c96d0faa1


转大写为:36C30E300F226B68ADD014DD1EF56A81EDB7B7A817840485769B9D6C96D0FAA1


  • 各类语言 HMAC SHA256 的实现:


Javascript HMAC SHA256 


/**Run the code online with this jsfiddle. Dependent upon an open source js library calledhttp://code.google.com/p/crypto-js/.**/
<script src="http://crypto-js.googlecode.com/svn/tags/3.0.2/build/rollups/hmac-sha256.js"></script><script src="http://crypto-js.googlecode.com/svn/tags/3.0.2/build/components/enc-base64-min.js"></script>
<script> var hash = CryptoJS.HmacSHA256("Message", "secret"); var hashInBase64 = hash.toString().toUpperCase(); document.write(hashInBase64);</script>
复制代码


PHP HMAC SHA256


/**PHP has built in methods for hash_hmac (PHP 5) and base64_encode (PHP 4, PHP 5) resulting in no outside dependencies. Say what you want about PHP but they have the cleanest code for this example.**/
$s = hash_hmac('sha256', 'Message', 'secret', true);echo strtoupper(var_dump($s));
复制代码


Java HMAC SHA256


/**Dependent on Apache Commons Codec to encode in base64.**/
import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import org.apache.commons.codec.binary.Base64;
public class ApiSecurityExample { public static void main(String[] args) { try { String secret = "secret"; String message = "Message";
Mac sha256_HMAC = Mac.getInstance("HmacSHA256"); SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256"); sha256_HMAC.init(secret_key);
byte[] bytes = sha256_HMAC.doFinal(message.getBytes()); String hash = new HexBinaryAdapter().marshal(bytes).toUpperCase(); System.out.println(hash); } catch (Exception e){ System.out.println("Error"); } }}
复制代码


 C# HMAC SHA256


using System;using System.Security.Cryptography;
namespace Test{ public class MyHmac { public static string Encrypt(string message, string secret) { secret = secret ?? ""; var encoding = new System.Text.UTF8Encoding(); byte[] keyByte = encoding.GetBytes(secret); byte[] messageBytes = encoding.GetBytes(message); using (var hmacsha256 = new HMACSHA256(keyByte)) { byte[] hashmessage = hmacsha256.ComputeHash(messageBytes); StringBuilder builder = new StringBuilder(); for (int i = 0; i < hashmessage.Length; i++) { builder.Append(hashmessage[i].ToString("x2")); } return builder.ToString().ToUpper(); } } }}
复制代码


返回结果 统一返回 JSON,一般格式如下:


请求成功


{    "success": true,    "result": {        //object    }}
复制代码


请求异常


{    "success": false,    "code": 1010,    "msg": "token非法"}
复制代码


六、集成 SDK Java 概述


目前提供的基于 Java 的 Tuya Cloud SDK 封装了 token 相关、用户相关以及设备相关的接口,以便加速云云对接的开发。


开发者只需要关注所使用的业务功能方法的调用,构建对应的 TuyaClient 实例,实例会自动更新 token 以及完成对应 API 的调用。SDK 主要包括了以下功能, 详细接口信息请参考后文对应模块:


token 相关(无需用户调用)


用户相关(获取用户列表、注册用户、获取用户下的设备列表)


设备相关(获取设备配网 token、获取配网 token 下所有设备列表等接口)


集成 SDK


IDEA 导入 jar 包: https://jingyan.baidu.com/article/0f5fb0993e9e1f6d8334ead2.html


Eclipse 导入 jar 包: https://jingyan.baidu.com/article/ca41422fc76c4a1eae99ed9f.html


GitHub 地址


https://github.com/TuyaInc/tuya_cloud_sdk_java


通用模块


由于部分新增接口无法及时同步集成至 SDK,开发者可通过 SDK 通用接口进行水平扩展满足开发。


获取 Header 列表:


/** * 获取Header列表 * @param isToken 是否是token相关请求,一般是false * @return */public List<Header> getHeaders(Boolean isToken)
复制代码


万能涂鸦接口:


/** * 万能涂鸦接口 * @param url * @param method 请求类型(例如:GET) * @param headers 请求头内容(额外新增的header) * @param body * @return */public String commonHttpRequest(String url, HttpMethod method, Map<String, String> headers, Object body)
复制代码


调用示例


以下为注册用户的示例:


TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);String uid = client.registerUser("testApp","86","18212345678", MD5Util.getMD5("123456")"nickName",UserTypeEnum.MOBLIE);System.out.println("成功同步用户: "+ uid);
复制代码


Golang


Golang SDK 源码地址,请参见Golang SDK


用户头像

IoT云工坊

关注

公众号:涂鸦IoT开发平台(Tuya_IoT) 2020.10.31 加入

微信:tuya1077,回复“行业报告”,可获取2020年20多份最新物联网相关行业报告。

评论 (1 条评论)

发布
用户头像
写的不错 共勉~,最近也在开始写博客。大佬们来翻牌啊!
2020 年 11 月 14 日 10:01
回复
没有更多了
【涂鸦物联网足迹】涂鸦云平台接口说明