快速入门

本文通过示例为您介绍如何在云开放平台快速开发，实现对智能设备的控制。

操作流程

仅需两步，玩转涂鸦云开放平台。云开发平台使用流程如下。

步骤 1: 创建项目

项目是 IoT 平台资源的集合，不同云开发项目之间的资源相互隔离。

步骤 2: 智慧商业平台开发者入驻

由于开发者入驻业务正在研发中，目前入驻方式先由开发者将开发者账号(IOT平台注册手机号/邮箱)、企业名称、行业域名(可不提供，使用默认的)交予我们智慧商业平台技术支持，生成入驻信息。

接入流程

接口规范

header参数约定

任何接口需要在header中加入如下参数：

参数名	类型	必填	描述
client_id	String	是	涂鸦云提供的client_id
sign	String	是	采用指定签名算法计算出的签名
sign_method	String	是	签名的摘要算法，固定填写HMAC-SHA256
t	Long	是	13位标准时间戳
access_token	String	否	业务接口必传，token相关接口不传
lang	String	否	语种，默认英文(中文:zh;英文:en;日语:ja;韩语:ko)

签名机制

您在向云开发平台发送调用请求时，都需要提供签名（Sign）进行身份验证。文本介绍如何构建云开发平台 API 签名。

签名算法

涂鸦云采用 HMAC-SHA256 方法创建摘要。针对不同的 API，当前提供两套签名算法。

令牌管理 API 签名算法

• 适用范围：获取令牌和刷新令牌 API。
• 签名算法： sign = HMAC-SHA256(client_id + t, secret).toUpperCase()
• 算法逻辑：

1. 将 client_id 与当前请求的 13 位标准时间戳（t）拼接成字符串。
2. 将字符串和 secret 进行哈希摘要，得到新的字符串。
3. 将新的字符串转为大写。

业务管理 API 签名算法

• 适用范围：令牌管理接口以外的其他 API。
• 签名算法：sign = HMAC-SHA256(client_id + access_token + t, secret).toUpperCase()
• 算法逻辑：

1. 将 client_id 、access_token 和当前请求的 13 位标准时间戳（t）拼接成字符串。
2. 将字符串和 secret 进行哈希摘要，得到新的字符串。
3. 将新的字符串转为大写。

签名构建示例

示例参数

参数名	参数值
client_id	1KAD46OrT9HafiKdsXeg
secret	4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC
t	1588925778000
access_token	3f4eda2bdec17232f67c0b188af3eec1

令牌管理 API 签名

1. 拼接待签名字符串。
   1KAD46OrT9HafiKdsXeg1588925778000
2. 通过哈希摘要获得新字符。
   • 哈希摘要：HMAC-SHA256(1KAD46OrT9HafiKdsXeg1588925778000,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)
   • 新字符：ceaafb5ccdc2f723a9fd3e91d3d2238ee0dd9a6d7c3c365deb50fc2af277aa83
3. 转换为大写。
   CEAAFB5CCDC2F723A9FD3E91D3D2238EE0DD9A6D7C3C365DEB50FC2AF277AA83

业务管理 API 签名

1. 拼接待签名字符串：1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec11588925778000
2. 通过哈希摘要获得新字符。
   • 哈希摘要：HMAC-SHA256(1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec11588925778000,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)
   • 新字符串：36c30e300f226b68add014dd1ef56a81edb7b7a817840485769b9d6c96d0faa1
3. 转换为大写。
   36C30E300F226B68ADD014DD1EF56A81EDB7B7A817840485769B9D6C96D0FAA1

HMAC SHA256 的实现

Javascript

/**
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

/**
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 = strtoupper(hash_hmac("sha256", "Message", 'secret'));
echo var_dump($s);

Java

/**
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#

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();
                }
            }
  }
}

错误码

全局错误码

code	msg	说明
500	system error,please contact the admin	系统错误，请联系管理员
1000	data not exist	数据不存在
1001	secret invalid	密钥非法
1002	access_token is null	访问令牌为空
1003	grant type invalid	grant type 无效
1004	sign invalid	签名无效
1005	Appkey invalid	Appkey 无效
1006	not support content type	不支持的content type
1007	not support Appkey	不支持的Appkey，请使用云端key
1010	token is expired	token过期
1011	token invalid	token无效
1012	token status is invalid	token状态无效
1013	request time is invalid	请求时间无效
1100	params is empty	参数为空
1101	params range invalid	参数范围无效
1102	params is null	参数为null
1105	missing the header	缺少header
1106	permission deny	权限非法
1108	uri path invalid	接口地址非法

业务错误码

code	说明
10100500	内部错误
10100501; 11100117	操作失败
10101100	参数不为空
10101106	无权限操作
10101105	参数体异常
10101107	网络繁忙，请稍后再试
10101202	设备不存在
10101401	房屋不存在
10101403	房屋编号已存在
10101660	用户不存在
10102700	该合作商已绑定该服务商
10102701	合作方和服务商的授权关系不存在
10102703	合作商授权项目关系不存在
10102711	该服务商有未完成施工维修工单，完成后方可解除
10102712	合作状态支持解除授权
10102713	施工商不存在
10102901	地理位置不存在
10102902	操作失败，已达到项目创建最大限制
10102903	项目已存在
10102904	项目不存在
10102905	操作失败，项目存在关联房屋
10102906	操作失败，已达到房屋创建最大限制
10102907	产品不存在
10102908	操作失败，项目不归属于您
10102909	缺少必传参数:Wifi或Zigbee设备品类及数量
10102910	施工状态无效
10102911	维修状态无效
10101812	工单不存在
10101813	施工品类不存在
10101814	设备离线
10101411	场景/自动化不存在
10103201	禁止连续添加两个延迟动作
10103202	延迟不能是最后的动作
10103203	执⾏动作类别只支持dpIssue
10103204	功能不支持
10103205	对应的红外码不存在
10103206	不支持设置特定温度的命令
10103207	匹配的红外代码无效
10103208	触发条件类别只支持设备状态
10103209	前置条件规则只支持时间段限制
10103210	操作失败，已达到场景创建最大限制
10103211	操作失败，已达到自动化创建最大限制
10103212	条件不支持
10103213	动作不支持
11100114	参数异常
11100118	数据不存在
11103001	任务不存在
11103012	任务状态不支持重开放
11103028	设备与房屋关系不正确
11103029	施工设备品类异常
11103037	施工拆分设备品类异常
11103038	施工红外设备品类异常
11103039	任务状态不允许删除
11104000	施工人员已被注册
11104005	施工人员不存在
11104008	已达到施工人员创建最大限制
11106000	一个模版只允许存在一个网关
11106005	模版不存在
11106006	模版不允许编辑
11106012	模板中区域名称不能重复
11106013	模板中区域名称不能重复
11106014	模板中自定义设备名称不能重复
11106015	已达到模板区域最大限制
11106016	已达到模板区域位置最大限制
11113000	已达到任务房屋最大限制