[TOC]

# 微瓴应用API

# 1. API概述

Hi，您好，欢迎使用腾讯微瓴开放平台服务。本文档主要介绍腾讯微瓴开放平台API快速使用流程，如果您对文档内容有任何疑问，可以通过以下方式联系我们：联系邮箱：welink@tencent.com

# 2. 使用流程

# 2.1 成为开发者

https://open.welink.qq.com (opens new window) 点击顶部导航栏右侧控制台或者底部快速入门-管理控制台，首次登录将会跳转到注册界面，完成企业资质注册即可进入控制台页面。

# 2.2 创建应用

在控制台页面，您可以在【应用管理】板块点击新增应用，填写应用的相关信息，自动生成应用AppID、AppKey和应用票据[将后台审核描述去掉，更改为“自动生成应用AppID、AppKey和应用票据”]，完成应用的创建。

# 2.3 获取密钥

在您的应用创建成功之后，可以在应用调试或应用详情中查看此应用的接入凭证AppID和AppKey。这是您的应用接入微瓴的主要凭证，每个应用有唯一标识，互不相同，请您妥善保管。

# 2.4 生成签名

您的应用在调用微瓴API之前，首先需要获取接口鉴权的签名。您需要使用应用所分配的AppID和AppKey，参考签名Demo，生成API接口鉴权签名。

# 2.5 开始开发

腾讯微瓴开放了REST API形式的服务，您可以点击【开发资源-API文档】查看具体调用参数及方法。

# 3. 调用方式

# 3.1 服务地址

接口域名在开放平台正式app列表详情里，通过指定域名访问，在实际项目对应的环境中进行联调

目前支持的环境和域名列表为：

接入地域	环境类别	域名
华南地区（广州）	开放平台沙箱环境	sandbox2api.welink.qq.com
华南地区（广州）	公有云环境	api-gz.welink.qq.com

# 3.2 通信协议

微瓴开放平台提供的所有API接口均通过HTTPS协议传输，提供高安全性的通讯。

# 3.3 请求方法

微瓴支持的 HTTP 请求方法:

POST（推荐）
GET

POST 请求支持的 Content-Type 类型：

application/json（推荐），必须使用 HMAC-SHA1 签名方法。
GET 请求的请求包大小不得超过 32 KB。
POST 请求使用签名方法为 HMAC-SHA1时不得超过 1 MB。

# 3.4 字符编码

均使用UTF-8编码。

# 3.5 公共参数

公共参数是用于标识接口鉴权的参数，每次请求均需要携带这些参数，才能正常发起请求

参数	参数描述
appid	应用接入微瓴的唯一标识App ID，新增应用通过后系统自动生成
app_ticket	用于登录API的应用票据，app_ticket有时间期限，由管理员决定app_ticket的期限，推荐3个月，请注意及时更新票据
sig	加密的密文，用于登录API使用，生成方式见生成签名
token	动态密钥，20分钟有效期，每一次调用API均需要带上该密钥
iotim_ticket	物联票据，每一次调用API均需要带上该票据

# 4. 签名机制

# 4.1 签名机制简介

微瓴开放平台HTTP API使用签名机制来验证请求的合法性。应用在调用微瓴API时必须带上接口请求签名，其中签名信息由接口请求参数和应用密钥根据本文提供的HMAC-SHA1算法生成，使用Base64编码。对于校验不通过的请求，API将拒绝处理，并返回鉴权失败错误。

# 4.2 获取应用密钥

登录微瓴开放平台，进入控制台-应用管理页面，如您未创建应用，可通过新增应用功能创建应用，获取AppID和AppKey。

# 4.3 签名生成样例

获取到AppID和AppKey之后，您需要自行实现生成签名的功能。签名的生成推荐使用我们提供的各语言Demo。具体样例如下：

# 4.3.1 JAVA签名示例

private static String encrypt(String appKey,long timeStamp,long randomNum){
  byte[] k = appKey.getBytes();
  byte[] t = getBytesByLong(timeStamp);
  byte[] n = getBytesByLong(randomNum);
  byte[] np = new byte[k.length+t.length+n.length];
  int i=0;
  for(int j=0;j<k.length;j++,i++){
    np[i]=k[j];
  }
  for(int j=0;j<t.length;j++,i++){
    np[i]=t[j];
  }
  for(int j=0;j<n.length;j++,i++){
    np[i]=n[j];
  }
  String sha1 = getSHA1(np);
  return sha1;
}

private static byte[] getBytesByLong(long data){
  byte[] bytes = new byte[8];
  bytes[0] = (byte) (data & 0xff);
  bytes[1] = (byte) ((data >> 8) & 0xff);
  bytes[2] = (byte) ((data >> 16) & 0xff);
  bytes[3] = (byte) ((data >> 24) & 0xff);
  bytes[4] = (byte) ((data >> 32) & 0xff);
  bytes[5] = (byte) ((data >> 40) & 0xff);
  bytes[6] = (byte) ((data >> 48) & 0xff);
  bytes[7] = (byte) ((data >> 56) & 0xff);
  return bytes;
}

private static String getSHA1(byte[] str) {
  String sha1 = "";

  try {
    MessageDigest digest = MessageDigest.getInstance("SHA-1");
    digest.update(str);

    byte[] messageDigest = digest.digest();
    StringBuilder hexString = new StringBuilder();
    for (int i = 0; i < messageDigest.length; i++) {
      String shaHex = Integer.toHexString(messageDigest[i] & 0xFF);
      if (shaHex.length() < 2) {
          hexString.append(0);
        }
        hexString.append(shaHex);
    }

    sha1 = hexString.toString();
  } catch (Exception e) {
    e.printStackTrace();
  }

  return sha1.toUpperCase();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

# 4.3.2 Python签名示例

import time
import struct
import hashlib

timeStamp = str(int(round(time.time() * 1000)))
#timeStamp = '1494502392528'
randomNum = '4561615'
appKey = '************'
#12sqq 中的 12s 表示KEYS的长度为12
signature_str = struct.pack('=12sqq',appKey,long(timeStamp),long(randomNum))

signature = hashlib.sha1(signature_str).hexdigest()

1
2
3
4
5
6
7
8
9
10
11
12

# 4.3.3 PHP签名示例

$appKey='testtesttesttest1';
$timeStamp = 1479693497852;
$randomNum = 4516316;

var_dump(encrypt($appKey,$timeStamp,$randomNum));

function encrypt($appKey,$timeStamp, $randomNum){
  $k = getBytes($appKey);
  $t = getBytesByLong($timeStamp);
  $n = getBytesByLong($randomNum);
  $np = array();
  $i=0;

  for($j=0;$j<count($k);$j++,$i++){
    $np[$i]=$k[$j];
  }

  for($j=0;$j<count($t);$j++,$i++){
    $np[$i]=$t[$j];
  }

  for($j=0;$j<count($n);$j++,$i++){
    $np[$i]=$n[$j];
  }
  //var_dump($np);
  $sha1 = sha1(toStr($np));
  return $sha1;
}

function toStr($bytes) {
  $str = '';
  foreach($bytes as $ch) {
    $str .= chr($ch);
  }
  return $str;
}

/**
* 转换一个String字符串为byte数组
* @param $str 需要转换的字符串
* @param $bytes 目标byte数组
* @author weling
*/
function getBytes($string) {
  $bytes = array();
  for($i = 0; $i < strlen($string); $i++){
    $bytes[] = ord($string[$i]);
  }
  return $bytes;
}

/**
* 转换一个long为byte数组
* @param $byt 目标byte数组
* @param $val 需要转换的字符串
*/
function getBytesBylong($val) {
  if(PHP_INT_SIZE == 4) { //整型为 32 位
    $byt = array();
    $byt[0] = ($val & 0xff);
    $byt[1] = ($val >> 8 & 0xff);
    $byt[2] = ($val >> 16 & 0xff);
    $byt[3] = ($val >> 24 & 0xff);
    if($val > PHP_INT_MAX) {
      $high = intval($val / 4294967296);
      $byt[4] = ($high & 0xff);
      $byt[5] = ($high >> 8 & 0xff);
      $byt[6] = ($high >> 16 & 0xff);
      $byt[7] = ($high >> 24 & 0xff);
    } else {
      $byt[4] = $byt[5] = $byt[6] = $byt[7] = 0;
    }
    return $byt;
  } else {                //整型为 64 位
    $byt = array();
    $byt[0] = ($val & 0xff);
    $byt[1] = ($val >> 8 & 0xff);
    $byt[2] = ($val >> 16 & 0xff);
    $byt[3] = ($val >> 24 & 0xff);
    $byt[4] = ($val >> 32 & 0xff);
    $byt[5] = ($val >> 40 & 0xff);
    $byt[6] = ($val >> 48 & 0xff);
    $byt[7] = ($val >> 56 & 0xff);
    return $byt;
  }
}

# 4.3.4 NodeJS签名示例

// if not browser env, then require node.js's util. otherwise just use window's
const TextEncoder = (typeof window === 'undefined') ? require('util').TextEncoder : window.TextEncoder

const crypto = require('crypto')

const encryptSig = function (appKey, timeStamp, randomNum) {
  let keyBytes = getBytesByStr(appKey)
  let timestampBytes = getBytesByInt64LE(timeStamp)
  let numberBytes = getBytesByInt64LE(randomNum)
  let concatBuffer = new Uint8Array(keyBytes.length + 16)
  concatBuffer.set(keyBytes)
  concatBuffer.set(timestampBytes, keyBytes.length)
  concatBuffer.set(numberBytes, keyBytes.length + 8)
  let sha1 = crypto.createHash('SHA1')
  sha1.update(concatBuffer)
  let sigResult = sha1.digest('hex')
  return sigResult
}

const getBytesByStr = function (str) {
  // always utf-8
  let encoder = new TextEncoder()
  let strBuffer = encoder.encode(appKey)
  return strBuffer
}

const getBytesByInt64LE = function (number) {
  let w = 4294967296
  let high = ((number / w) & 0xffffffff)
  let low = number % w
  // transfer to LE
  let numberLEArray = new Uint8Array(8)
  numberLEArray[0] = low & 0xff
  numberLEArray[1] = low >> 8 & 0xff
  numberLEArray[2] = low >> 16 & 0xff
  numberLEArray[3] = low >> 24 & 0xff
  numberLEArray[4] = high & 0xff
  numberLEArray[5] = high >> 8 & 0xff
  numberLEArray[6] = high >> 16 & 0xff
  numberLEArray[7] = high >> 24 & 0xff
  return numberLEArray
}

let loginTimestamp = new Date().getTime()
let loginNum = Math.round(Math.random() * 100000)
let appKey = '********' // change it to your own app key
let sig = encryptSig(appKey, loginTimestamp, loginNum)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# 4.3.5 Golang签名示例

func TestUnit_login(T *testing.T){
 appId:=""
 app_ticket:=""
 app_key:=""
 time:=time.Now().UnixNano() / int64(time.Millisecond)
 sig:=encrypt(app_key,time,1)
 url,_:=url.Parse("https://domain.welink.qq.com")
 url.Path="/common/ticket/loginByApp"
 params:=url.Query()
 params.Add("appid",appId)
 params.Add("time",strconv.FormatInt(time,10))
 params.Add("num",strconv.Itoa(1))
 params.Add("sig",sig)
 params.Add("app_ticket",app_ticket)
 url.RawQuery=params.Encode()
 resp,_:=http.Get(url.String())
 bytes,_:=ioutil.ReadAll(resp.Body)
 fmt.Printf("resp:%s",string(bytes))

}

func  encrypt( key string , times int64, num int64)string{
 if len(key)<=0 {
  return ""
 }
 k:= []byte(key)
 var buffer bytes.Buffer
 buffer.Write(k)
 buffer.Write(intToByte(times))
 buffer.Write(intToByte(num))
 h:=sha1.New()
 h.Write(buffer.Bytes())
 bs:=h.Sum(nil)
 sig:=hex.EncodeToString(bs)
 return strings.ToUpper(sig);
}
func intToByte(n int64 )([]byte){
 result:=make([]byte,8)
 result[0]= byte(int8(n))
 result[1]= byte(int8(n >> 8))
 result[2]= byte(int8(n >> 16))
 result[3]= byte(int8(n >> 24))
 result[4]=byte(int8(n >> 32))
 result[5]=byte(int8(n >> 40))
 result[6]=byte(int8(n >> 48))
 result[7]=byte(int8(n >> 56))
 return result
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# 4.3.5 C#签名示例

using System.Security.Cryptography;
using System.Linq;

public class Test
{
	public static void Main()
	{
		string key = "KgoucKqD6eRj";
		long times = 1599710713383;
		long num = 335;
		Console.WriteLine(HMAC1(key,times,num));
	}
	
	//sha1加密
    public static string HMAC1(string key, long times, long num)
    {
        byte[] byte1 = System.Text.Encoding.UTF8.GetBytes(key);
        byte[] byte2 = BitConverter.GetBytes(times);
        byte[] byte3 = BitConverter.GetBytes(num);
        
        byte[] ndata = new byte[byte1.Length + byte2.Length + byte3.Length];
        byte1.CopyTo(ndata, 0);
        byte2.CopyTo(ndata, byte1.Length);
        byte3.CopyTo(ndata, byte1.Length+byte2.Length);
        
        //建立SHA1对象
        SHA1 sha = new SHA1CryptoServiceProvider();
        byte[] result = sha.ComputeHash(ndata);
        
        string hashValue = result.Aggregate("", (s, e) => s + String.Format("{0:x2}", e), s => s);
        return hashValue.ToUpper();
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 5. 接口鉴权

# 5.1 使用用户信息登录（邮箱/QQ/微信账号登录）

请求url: /common/ticket/loginByUser
请求方式: get
描述: 用于获取token和iotim_ticket。适用于先登录过微瓴开放平台，已经有用户登录态的情况。例如从微瓴开放平台拉起客户端，从session中获取用户登录信息，然后使用该接口调用API获取动态密钥token和物联票据iotim_ticket。
参数列表:

字段名称	字段类型	是否必须	字段描述
appid	Long	Yes	应用系统的appid，新增应用后系统自动生成
time	Long	是	当前时间戳，需要和生成sig的time保持一致
num	Long	是	加密时的正随机数
sig	String	是	用于鉴权的密文，生成方式见签名生成样例
loginKey	String	是	cookie中mvs_unified_login_token_key字段的值。支持QQ、微信、邮箱账号登录。
projectId	String	是	项目id,由系统自动分配

请求示例：

/common/ticket/loginByUser
?appid=10000
&time=1494765993240
&num=1518
&sig=*****************************
&loginKey=************************************

1
2
3
4
5
6

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
token	String	动态密钥，20分钟过期
iotim_ticket	String	物联票据

返回格式:

{
  "code": 0,
  "data": {
    "iotim_ticket": "*****************",
    "token": "******************"
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8

# 5.2 使用后台方式登录

请求url: /common/ticket/loginByApp
请求方式: get
描述: 用于获取token和iotim_ticket。适用于不关注用户信息，通过后台方式获取调用API的访问权限的场景。开发者可以使用开放平台分配的app_ticket通过该接口获取动态密钥token和物联票据iotim_ticket。
参数列表:

字段名称	字段类型	是否必须	字段描述
appid	Long	是	应用系统的App ID，由系统自动分配
time	Long	是	当前时间戳,需要和生成sig的time保持一致
num	Long	是	加密时的正随机数
sig	String	是	用于鉴权的密文，生成方式见签名生成样例
app_ticket	String	是	开放平台分配的票据，用于登录鉴权
projectId	String	是	项目id,由系统自动分配

请求示例：

/common/ticket/loginByApp
?time=1520231107761
&num=1
&sig=*****************************
&appid=*****
&app_ticket=*******************************************

1
2
3
4
5
6

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
token	String	动态密钥，20分钟过期
iotim_ticket	String	物联票据

返回格式:

{
  "code": 0,
  "data": {
    "iotim_ticket":
      "*******************************************************",
    "token":
      "*******************************************************"
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8
9
10

# 6. 设备管理

# 6.1 获取设备列表

请求url: /common/device/getDeviceList
请求方式: get
描述: 根据条件查询设备列表信息，设备需绑定到应用

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
num	Integer	是	分页参数：每页记录数，最大返回100
page	Integer	是	分页参数：当前页码
pid	Long	否	查询条件：设备所属的产品的id
sn	String	否	查询条件：设备序列号
wId	String	否	查询条件：设备在微瓴的唯一标志
parent_wId	String	否	查询条件：父设备
project_id	String	否	项目编号

请求示例：

/common/device/getDeviceList?page=1
&num=999
&token=***************
&iotim_ticket=*********************

1
2
3
4

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
totalpage	Integer	总页数
totalrow	Integer	总数量
list	JsonArray	设备详细信息列表
wId	String	子设备在微瓴的唯一标志
product_id	Integer	设备所属产品id
project_id	Integer	项目ID
position	String	设备位置信息
device_status	String	设备在线状态，online-在线，offline-离线
isLive	boolean	推流状态（仅摄像机有该状态）
device_name	String	设备名称
device_nick	String	设备昵称
device_type	Integer	设备类型编码
dt_name	String	设备类型名称
sn	String	设备序列号
point_name	String	设备点位名称
coordinate	String	设备坐标点，格式(x,y,z)
parent_wId	String	父设备在微瓴的唯一标志
din	String	子设备在微瓴的唯一标志（旧标识，推荐使用wId）
parent_din	String	父设备在微瓴的唯一标志（旧标识，推荐使用parent_wId）
ota_version	String	设备当前上报的ota版本

返回格式:

{
   "code":0,
   "data":{
      "totalpage":1,
      "totalrow":4,
      "list":[
         {
            "device_status":"offline",
            "coordinate":"",
            "din":"300000000000043491",
            "device_nick":"11dsadsdasfasf3",
            "device_type":49,
            "point_name":"",
            "poi_code":"w0903001",
            "device_name":"11dsadsdasfasf3",
            "parent_wId":"de415023-5fa8-4cdb-adb1-2172f0d6b2b5",
            "wId":"c9dca342-5640-4509-8d10-5ce42c4ae5a9",
            "project_id":137,
            "dt_name":"空气净化器",
            "product_id":1700006776,
            "parent_din":"300000000000043333",
            "sn":"11dsadsdasfasf3",
            "position":"",
            "ota_version":"1.1.1"
         },
         {
            "device_status":"offline",
            "coordinate":"",
            "din":"300000000000043490",
            "device_nick":"1asfasasfas12",
            "device_type":49,
            "point_name":"",
            "poi_code":"w0903001",
            "device_name":"1asfasasfas12",
            "parent_wId":"de415023-5fa8-4cdb-adb1-2172f0d6b2b5",
            "wId":"7c2e46f3-898d-447d-9170-d5682f20506a",
            "project_id":137,
            "dt_name":"空气净化器",
            "product_id":1700006776,
            "parent_din":"300000000000043333",
            "sn":"1asfasasfas12",
            "position":"海阔天空大厦_F3_1asfasasfas12",
            "ota_version":"1.1.1"
         },
         {
            "device_status":"offline",
            "coordinate":"",
            "din":"300000000000043489",
            "device_nick":"111dsafasgah",
            "device_type":49,
            "point_name":"",
            "poi_code":"w0903001",
            "device_name":"111dsafasgah",
            "parent_wId":"de415023-5fa8-4cdb-adb1-2172f0d6b2b5",
            "wId":"70b62a97-2dce-44e4-beea-94d1b62c4663",
            "project_id":137,
            "dt_name":"空气净化器",
            "product_id":1700006776,
            "parent_din":"300000000000043333",
            "sn":"111dsafasgah",
            "position":"海阔天空大厦_F2_111dsafasgah",
            "ota_version":"1.1.1"
         },
         {
            "device_status":"offline",
            "coordinate":"",
            "din":"300000000000043488",
            "device_nick":"99fsghfdjs3",
            "device_type":49,
            "point_name":"",
            "poi_code":"w0903001",
            "device_name":"99fsghfdjs3",
            "parent_wId":"de415023-5fa8-4cdb-adb1-2172f0d6b2b5",
            "wId":"5cad83dd-4fd0-4cb8-89fc-d8931390a22a",
            "project_id":137,
            "dt_name":"空气净化器",
            "product_id":1700006776,
            "parent_din":"300000000000043333",
            "sn":"99fsghfdjs3",
            "position":"海阔天空大厦_F1_99fsghfdjs3",
            "ota_version":"1.1.1"
         }
      ]
   },
   "message":"OK"
}

# 6.2 更换设备接口

请求url: /common/device/replaceDevices
请求方式:POST
参数列表:

字段名称	字段类型	字段描述
token	String	鉴权参数：登录获取的动态密钥
iotim_ticket	String	鉴权参数：登录获取的物联票据
projectId	Integer	项目Id,不能为空,
oldDeviceWId	String	被替换设备wid, 与 oldDeviceDin不能同时为空，优先以oldDeviceWId设备信息为准。
oldDeviceDin	String	被替换设备din,与 oldDeviceWId 不能同时为空,如果同时不为空，则优先以oldDeviceWId设备信息为准。
newWId	String	新设备WId,与 newProductId+newSN 不能同时为空，如果同时不为空，则优先以newWId设备为准。
newProductId	String	新设备productId,如果newWId不为空，则优先以newWId为准，如果newWId为空，则newProductId+newSN不能为空
newDeviceSN	String	新设备SN，如果newWId不为空，则优先以newWId为准;如果newWId为空，则newProductId+newDeviceSN不能为空
newDeviceName	String	新设备名称
isCopyOldDeviceHistory	String	可以为空，是否继承原有设备的历史数据 ,true ，继承，false 不继承。默认为false

说明: 替换的新设备需要在微瓴平台放号后才可以允许替换

请求示例：

/common/device/replaceDevices?
iotim_ticket=****************************
&token=***********************************
a.headers: Content-Type: application/json
b.body: {"projectId":11111118,"deviceInfo":[{"oldDeviceWId":"","oldDeviceDin":"","newDeviceName":"testDeviceName","newDeviceWId":"","newDeviceProductId":"","newDeviceSN":"","isCopyOldDeviceHistory":true}]}

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	返回码
message	String	返回信息提示
upateResult	Number	替换结果,0标识替换成功，-1表示替换失败
data	Json	返回内容消息体

例如：

{

   "code":0,
   "message":"success",
   "data":[
        "projectId":11111118,
         "deviceInfo":[
       {
           "oldDeviceWId":"",
		   "oldDeviceDin":"",
           "newDeviceName":"testDeviceName",
		   "newDeviceWId":"",
	       "newDeviceProductId":"",
	       "newDeviceSN":"",
           "upateResult":0
       },
       {
          
           "oldDeviceWId":"",
		   "oldDeviceDin":"",
           "newDeviceName":"testDeviceName2"
		   "newDeviceWId":"",
	       "newDeviceProductId":"",
	       "newDeviceSN":"",
           "upateResult":-1
       }
       ]
   ]

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 6.3 设备导入接口

请求url: /common/open/device/import
请求方式: POST application/json
描述：把设备导入到指定项目中

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
productId	String	是	产品Id
sn	String	是	设备sn，仅支持单个导入
parentDin	String	否	父设备din号填入则为子设备不填入则是直连设备
locationId	String	否	位置id 填入则对位置信息进行校验从数字空间获取

请求示例：

/common/open/device/import?
iotim_ticket=****************************
&token=***********************************
a.headers: Content-Type: application/json
b.body: {"productId":"1700006187","locationId":"5c479e94-938f-11eb-8dc4-badd26213509","parentDin":"200900000000014359","sn":"IMPORT00024"}

1
2
3
4
5

返回参数:

字段名称	字段类型	描述
message	string	导入返回信息
code	Int	返回码
data	JSONObject	导入结果
successList	JSONArray	成功导入的设备列表
failList	JSONArray	导入失败的设备列表

返回示例:

{
	"code": 0,
	"data": {
		"successList": [{
			"floorId": "ca6688d7-e273-4ed9-b9ba-46c373fd754b",
			"result": true,
			"msg": "success",
			"productId": "1700006187",
			"locationId": "5c479e94-938f-11eb-8dc4-badd26213509",
			"location": "RM107",
			"sn": "IMPORT00024",
			"floor": "F1",
			"building": "IDC机房",
			"buildingId": "ecf67fa2-9337-4cb1-bf0f-bacfc4c99417"
		}],
		"failList": []
	},
	"message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 6.4 设备绑定接口

请求url: /common/open/device/bind
请求方式: POST application/json
描述：批量把设备和应用进行绑定

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
dins	String	是	设备绑定din, 多个设备用逗号分隔
appIds	String	是	绑定项目下的应用id, 多个应用用逗号进行分割

请求示例:

/common/open/device/bind?
iotim_ticket=****************************
&token=***********************************
a.headers: Content-Type: application/json
b.body: {"appIds":"20005","dins":"200900000000014359,200900000000014360"}

1
2
3
4
5

返回参数:

字段名称字段类型字段描述

code Int 返回码

message String 返回信息提示
返回示例：

{
	"code": 0,
	"message": "OK"
}

1
2
3
4

# 6.5 设备移除接口

请求url: /common/open/device/remove
请求方式: POST application/json
描述：批量把设备从项目中移除，并解除设备已绑定的应用关系

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
dins	string	是	设备绑定din, 多个设备用逗号分隔

请求示例:

/common/open/device/remove?
iotim_ticket=****************************
&token=***********************************
a.headers: Content-Type: application/json
b.body: {"dins":"200900000000014359,200900000000014360"}

1
2
3
4
5

返回参数:

字段名称字段类型字段描述

code Int 返回码

message String 返回信息提示
返回示例:

{
	"code": 0,
	"message": "OK"
}

1
2
3
4

# 6.6 设备ota升级推送

请求url: /common/open/device/upgrade
请求方式: POST application/json
描述：为设备推送指定版本的ota升级包

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
dins	String[]	是	设备唯一标识，String数组
productId	String	是	设备的产品Id
otaVersion	String	是	设备产品的ota版本号

请求示例:

/common/open/device/upgrade?
iotim_ticket=****************************
&token=***********************************
a.headers: Content-Type: application/json
b.body: {
	"dins":["200900000000014359,200900000000014360"],
	"productId": 1700006208,
	"otaVersion": "1.1.1",
}

1
2
3
4
5
6
7
8
9

# 6.7 设备和应用绑定列表

请求url: common/device/getDeviceAndAppList
请求方式: GET
描述：通过接口查询应用权限下的设备与各应用之间的关系。

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
num	Int	是	分页参数：每页记录数，最大返回1000
page	Int	是	分页参数：当前页码
wId	String	否	设备编号，支持模糊查询
appId	String	否	应用编号，支持模糊查询

请求示例:

common/device/getDeviceAndAppList?token=*******&iotim_ticket=***********&page=1&num=999&appId=20010

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
totalRow	int	总数量
totalPage	int	总页数
pageNumber	int	当前页码
pageSize	int	每页数量
list	array	产品列表，Json数组
wId	String	产品编号
appIds	array	应用编号，String数组

返回示例:

{
    "code":0,
    "data":{
        "totalRow":28805,
        "totalPage":14403,
        "pageNumber":1,
        "pageSize":2,
        "list":[
            {
                "wId":"87074b1f-aca9-4de4-a826-2f8a1f80eb6e",
                "appIds":[
                    "20010",
                    "20011"
                ]
            },
            {
                "wId":"ecafca98-d66f-4c41-944d-09abd9ef509e",
                "appIds":[
                    "20010"
                ]
            }
        ]
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 6.8 添加设备状态的统计维度

请求url: /common/open/device/addDeviceStatisticsDim
请求方式: POST application/json

描述：

添加项目下需要统计哪些层级的设备状态数据，添加后需要10分钟才会生效。调用接口 6.9 获取设备状态的统计记录 (opens new window) 获取项目下的设备状态统计结果。
单个项目下只允许有一种统计维度，如果单个项目添加多个统计维度，以最后一次提交的为准。

dimensions 配置规则：

a: 参照开放平台文档poiId描述 (opens new window)，建筑的维度为level=6，楼层的维度为level=7，房间的维度为level=8；
b: dimensions 为4字节32位的Int值，将对应的比特位设置为1表示需要统计该维度的数据；例如：对于项目11111171，需要统计建筑【level6】- 楼层【level7】维度的设备状态，那么将dimensions的第6，7位置为1，也就是 dimensions=1100 0000。
参照表：

Dimension值	层级名	值
0000 1100 0000	建筑+楼层	192
0000 0100 0000	建筑	64
0001 0100 0000	建筑+房间	320
0001 0000 0000	房间	256
0001 1000 0000	楼层+房间	384
0000 1000 0000	楼层	128
0001 1100 0000	建筑+楼层+房间	448

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
projectId	String	是	项目编号
show_device_type	Boolean	是	是否统计设备类型维度，默认为 true
dimensions	Int	是	统计维度，将对应的比特位设置为1即可，例如统计建筑维度（level6，则为0100 0000=64）。需要传入十进制

请求示例: 统计项目11111171的建筑层级的设备状态，dimensions = 64 (0100 0000)

/common/device/addDeviceStatisticsDim?token=******&iotim_ticket=*****************&projectId=11111171
a.请求头：Content-Type:application/json
b.请求包体:
{
	"dimensions": 64,
	"show_device_type": true
}

1
2
3
4
5
6
7

返回参数:

字段名称字段类型字段描述

code Int 返回码，0表示成功，其他见错误码说明

message String 执行结果消息
返回示例:

字段名称	字段类型	字段描述
code	Int	返回码，0表示成功，其他见错误码说明
message	String	执行结果消息

{
	"code": 0,
	"message": "OK"
}

1
2
3
4

# 6.9 获取设备状态的统计记录

请求url: /common/open/device/getDeviceStatus
请求方式: GET
描述：
- 获取项目下指定建筑|指定楼层|指定房间|指定设备类型的状态（汇总数，在线数，离线数，故障数）。若是第一次获取指定项目下的设备状态统计，需要调用接口 6.8 添加设备状态的统计维度 (opens new window) 进行指定项目的配置
- POIID 地理层级关系图 (opens new window)

请求参数:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥，拼接在url，body不需要携带
iotim_ticket	String	是	鉴权参数：登录获取的物联票据，拼接在url，body不需要携带
projectId	String	是	项目编号
level	Int	是	所属地理层级，"0"表示查询项目下的设备状态
poiIds	String	否	需要查询的poiId，多个以,分隔（为空表示查询所有，返回该项目下该level的设备状态的统计结果）
poiCodes	String	否	需要查询的poiCode，多个以,分隔，为空表示查询所有

说明：当level=0的时候，表示查询项目下的设备状态，不包含位置信息。此时poiIds字段的内容不会作为筛选条件，poiCodes仍可作为筛选条件进行查询指定的设备类型。

返回参数:

字段名称					字段类型	字段描述
code					Int	返回码，0表示成功，其他见错误码说明
message					String	执行结果消息
data					JSON	查询结果
	projectId				String	项目ID
	total				Int	汇总数
	onlineSum				Int	离线数
	offlineSum				Int	离线数
	faultSum				Int	故障数
	poiCodeListOverview				JSON	设备类型概览列表
		poiCode			String	设备类型值
		name			String	设备类型名称
		total			Int	汇总数
		offline			Int	离线数
		online			Int	在线数
		fault			Int	故障数
		levelList			JSON	层级列表，当poiIds只有一个查询条件时，不显示此项
			id		String	层级id
			total		Int	汇总数
			offlineSum		Int	离线数
			onlineSum		Int	在线数
			faultSum		Int	故障数
			poiCodeList		JSON	设备类型列表
				poiCode	String	设备类型值
				name	String	设备类型名称
				total	Int	汇总数
				offline	Int	离线数
				online	Int	在线数
				fault	Int	故障数

请求示例1:

/common/open/device/getDeviceStatus?token=******&iotim_ticket=*****************&projectId=11111171&level=8&poiIds=440305000003,440305000406&poiCodes="

返回示例1:

{
   "code": 0,
   "data": {
       "projectId": "11111171",
       "total": 13,
       "onlineSum": 0,
       "offlineSum": 12,
       "faultSum": 1,
       "poiCodeListOverview": [
           {
               "poiCode": "w0905001",
               "name": "灯控面板",
               "total": 1,
               "online": 0,
               "fault": 0,
               "offline": 1
           },
           {
               "poiCode": "w0107006",
               "name": "照明网关",
               "total": 2,
               "online": 0,
               "fault": 0,
               "offline": 2
           },
           {
               "poiCode": "w0701003",
               "name": "半球摄像头",
               "total": 3,
               "online": 0,
               "fault": 1,
               "offline": 2
           },
           {
               "poiCode": "w0701004",
               "name": "快球摄像头",
               "total": 5,
               "online": 0,
               "fault": 0,
               "offline": 5
           },
           {
               "poiCode": "w0713002",
               "name": "优图盒子",
               "total": 1,
               "online": 0,
               "fault": 0,
               "offline": 1
           },
           {
               "poiCode": "w0714001",
               "name": "智能插座",
               "total": 1,
               "online": 0,
               "fault": 0,
               "offline": 1
           }
       ],
       "levelList": [
           {
               "id": "440305000003",
               "total": 5,
               "onlineSum": 0,
               "offlineSum": 5,
               "faultSum": 0,
               "poiCodeList": [
                   {
                       "poiCode": "w0701004",
                       "name": "快球摄像头",
                       "total": 5,
                       "online": 0,
                       "fault": 0,
                       "offline": 5
                   }
               ]
           },
           {
               "id": "440305000406",
               "total": 8,
               "onlineSum": 0,
               "offlineSum": 7,
               "faultSum": 1,
               "poiCodeList": [
                   {
                       "poiCode": "w0714001",
                       "name": "智能插座",
                       "total": 1,
                       "online": 0,
                       "fault": 0,
                       "offline": 1
                   },
                   {
                       "poiCode": "w0905001",
                       "name": "灯控面板",
                       "total": 1,
                       "online": 0,
                       "fault": 0,
                       "offline": 1
                   },
                   {
                       "poiCode": "w0701003",
                       "name": "半球摄像头",
                       "total": 3,
                       "online": 0,
                       "fault": 1,
                       "offline": 2
                   },
                   {
                       "poiCode": "w0713002",
                       "name": "优图盒子",
                       "total": 1,
                       "online": 0,
                       "fault": 0,
                       "offline": 1
                   },
                   {
                       "poiCode": "w0107006",
                       "name": "照明网关",
                       "total": 2,
                       "online": 0,
                       "fault": 0,
                       "offline": 2
                   }
               ]
           }
       ]
   },
   "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

请求示例2:

/common/open/device/getDeviceStatus?token=******&iotim_ticket=*****************&projectId=11111171&level=0&poiIds=&poiCodes=w0901001,w0701010"

返回示例2:

{
   "code": 0,
   "data": {
       "projectId": "11111171",
       "total": 70,
       "onlineSum": 3,
       "offlineSum": 67,
       "faultSum": 0,
       "poiCodeListOverview": [
           {
               "poiCode": "w0901001",
               "name": "机顶盒",
               "total": 16,
               "online": 0,
               "fault": 0,
               "offline": 16
           },
           {
               "poiCode": "w0701010",
               "name": "视频网关",
               "total": 54,
               "online": 3,
               "fault": 0,
               "offline": 51
           }
       ]
   },
   "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 7. 服务管理

# 7.1 调用第三方服务

请求url: /common/logic/call
请求方式: POST
描述: 应用通过该接口访问开放平台上发布的服务。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
service_id	Long	是	访问的服务的id
api_id	Long	是	访问的服务下的某个api的id
params	JsonArray	否	服务的api的参数数组
name	String	否	参数名
value	All	否	参数值
project_id	String	否	项目编号

请求示例：

/common/logic/call?
service_id=*******************************
&api_id=**********************************
&iotim_ticket=****************************
&token=***********************************
&project_id=******************************
a.headers: Content-Type: application/json
b.body: {"params": [{"name":"a", "value":"a"},{"name":"b", "value":"2"}]}

1
2
3
4
5
6
7
8

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
  "code": 0,
  "message": "OK"
}

1
2
3
4

# 8. 帐号权限

# 8.1 获取当前用户信息

请求url: /common/account/getCurrentUserInfo
请求方式: get
描述: 获取当前登录用户的的信息，包括用户的角色列表
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
project_id	String	否	项目编号

请求示例：

/common/account/getCurrentUserInfo?
token=************************************
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
user_id	Integer	用户id
user_name	String	用户名称
email	String	用户邮箱
user_expire_time	String	用户账号授权过期时间，“永久授权”表示无过期时间
project_id	String	项目id
organizationlist	Json	用户组织架构信息
organization	String	用户所属组织架构,例如:top3-top2-top1-top2
detail	JsonArray	每层组织架构详细信息
gmt_create_	String	该组织架构创建时间
parent_id	String	该组织架构上层组织部架构id
name	String	该组织架构名称
id	String	该组织架构id
order_num	String	该级别组织架构排序
gmt_modified	String	该组织架构最后一次更新时间
rolelist	JsonArray	用户角色信息
role_name	String	用户角色名称
role_id	String	用户角色id
role_code	String	用户角色代码

返回格式:

    "code": 0,
    "data": [
        {
            
            "project_id": "11111118",
            "organizationlist": {
                "organization": "",
                "detail": [
                ]
            },
           
            "email": "935367253@qq.com",
            "rolelist": [
                {
                    "role_name": "fortestrole",
                    "role_id": "2042",
                    "role_code": "welink_1590049749780"
                }
            ],
            "user_id": "40845",
            "用户自定义字段1": "用户自定义字段1的value",
            "用户自定义字段2": "用户自定义字段2的value",
            "用户自定义字段3": "用户自定义字段3的value",
            "user_expire_time": "2023-06-29 23:59:59",
        }

    ],
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 8.2 获取项目下告警处理人角色的用户列表

请求url:/common/processor/processorList
请求方式:get
描述: 获取项目下的用户列表（告警处理人角色）
参数列表:

字段名称	字段类型	是否必须	字段描述
token	Int	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
num	Int	否	分页参数：每页记录数（分页参数为空不分页）
page	Int	否	分页参数：当前页码（分页参数为空不分页）
email	String	否	需要查询的用户邮箱（参数为空，默认查询全量）

请求示例:

/common/processor/processorList?
token=************************************************************
&iotim_ticket=*********************************************************
&page=1
&num=10
&email=1234567@qq.com

1
2
3
4
5
6

返回参数:

返回参数	参数类型	参数说明
code	Int	错误码，0表示成功，其他看错误码说明
message	String	执行结果消息
data	Json	查询结果
list	JsonArray	用户列表
userName	String	用户名称
email	String	用户邮箱
mobile	String	用户手机号
createTime	String	用户创建时间
apiRoles	List	用户绑定应用角色信息（分配给应用的appid下的角色）,json数组

返回示例:

{
  "code": 0,
  "data": {
    "list": [
      {
        "userName": "用戶名"，
        "email"："12345678@qq.com",
       	"mobile": "12345678"，
        "createTime": 1562917573000,
        "apiRoles": [
          {
            "roleName": "admin",
            "roleCode": "admin",
            "description": "应用管理员"
          },
          {
            "roleName": "user",
            "roleCode": "user",
            "description": "应用普通用户"
          }
        ]
      },
      {
        "userName": "用戶名1"，
    	"email"："123456781@qq.com",
        "mobile": "123456781"，
    	"createTime": 1562917573000,
        "apiRoles": [
          {
            "roleName": "admin",
            "roleCode": "admin",
    		"description": "应用管理员"
          }
        ]
      }
    ]
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 8.3 根据用户手机号查询用户信息

请求url: /common/user/getUserInfoByMobile
请求方式: post
描述: 根据用户手机号查询用户基本信息，包括用户有权限的项目列表，每个有权限项目的用户基本信息，角色信息，自定义字段信息，组织架构信息。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
projectId	String	否	项目编号
email	String	否	用户邮箱
mobile	String	是	用户手机号，需要区分国际区号，例如:86-xxxxxxxxxxx
app_id	String	是	应用id

请求示例：

/common/user/getUserInfoByMobile?token=******&iotim_ticket=******
headers = {"Content-Type": "application/json"}
body = {
    "mobile":"189······689",
    "project_id":"137",
    "app_id":"40719"
}

1
2
3
4
5
6
7

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
user_id	Integer	用户id
user_name	String	用户名称
email	String	用户邮箱
user_expire_time	String	用户账号授权过期时间，“永久授权”表示无过期时间
project_id	String	项目id
organizationlist	Json	用户组织架构信息
organization	String	用户所属组织架构,例如:top3-top2-top1-top2
detail	JsonArray	每层组织架构详细信息
gmt_create_	String	该组织架构创建时间
parent_id	String	该组织架构上层组织部架构id
name	String	该组织架构名称
id	String	该组织架构id
order_num	String	该级别组织架构排序
gmt_modified	String	该组织架构最后一次更新时间
rolelist	JsonArray	用户角色信息
role_name	String	用户角色名称
role_id	String	用户角色id
role_code	String	用户角色代码

返回格式:

    "code": 0,
    "data": [
        {
            
            "project_id": "11111118",
            "organizationlist": {
                "organization": "",
                "detail": [
                ]
            },
           
            "email": "935367253@qq.com",
            "rolelist": [
                {
                    "role_name": "fortestrole",
                    "role_id": "2042",
                    "role_code": "welink_1590049749780"
                }
            ],
            "user_id": "40845",
            "用户自定义字段1": "用户自定义字段1的value",
            "用户自定义字段2": "用户自定义字段2的value",
            "用户自定义字段3": "用户自定义字段3的value",
            "user_expire_time": "2023-06-29 23:59:59",
        }

    ],
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 8.4 根据项目id,应用id 查询有权限的用户信息

请求url：/common/user/getUserInfoByApp
请求方式：get
描述：用于获取指定应用下有权限的用户信息，包括角色，自定义扩展属性，组织架构等基本信息
参数列表：

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
appId	Long	是	应用系统的App ID，由系统分配
projectId	Long	是	appId所属项目ID，由系统分配

请求示例：

/common/user/getUserInfoByApp?
projectId=xxx
&appId=xxx
&token=***************
&iotim_ticket=*********************

1
2
3
4
5

返回参数

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	JsonArray	查询结果

返回格式

{
    "code":0,
    "data":[
        {
            "自定义字段1":"",
            "自定义字段2":"",
            "自定义字段3":"test",
            "自定义字段4":"",
            "自定义字段5":"",
            "rolelist":[
                {
                    "role_name":"admin",
                    "role_id":"2035",
                    "role_code":"admin"
                }
            ],
            "user_id":"41878",
            "project_id":"1",
            "organizationlist":{
                "organization":"",
                "detail":[

                ]
            },
            "name":"测试用户",
            "en_name":"test_user_",
            "user_expire_time":"永久授权",
            "email":"xx@qq.com"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 8.5 新增角色

请求url：/common/account/addAPIRole
请求方式：get
描述：给当前应用新增一个API角色
参数列表：

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_name	String	是	角色名，中文请用utf8编码
role_code	String	是	角色代码，中文请用utf8编码
description	String	是	角色描述，中文请用utf8编码
project_id	String	否	项目编号

请求示例：

/common/account/addAPIRole?
token=************************************
&role_name=管理员
&role_code=admin5
&description=测试帐号
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4
5
6
7

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
  "code": 0,
  "message": "OK"
}

1
2
3
4

# 8.6 删除角色

请求url: /common/account/delAPIRole
请求方式: get
描述: 删除当前应用的一个API角色，被删除的角色代码不能再使用
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	否	角色代码，中文请用utf8编码
project_id	String	否	项目编号
force_delete	String	否	强制删除字段为true时：自动删除角色关联用户、设备、功能权限的关系，为false或者空时：如有用户、设备、功能相关资源则不能删除此角色

请求示例：

/common/account/delAPIRole?
token=************************************
&role_code=admin5
&iotim_ticket=****************************
&project_id=******************************
&force_delete=****************************

1
2
3
4
5
6

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
  "code": 0,
  "message": "OK"
}

1
2
3
4

# 8.7 查询角色

请求url: /common/account/findAPIRoleList
请求方式: get
描述: 根据角色代码查询角色信息
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	是	角色代码，中文请用utf8编码
project_id	String	否	项目编号

请求示例：

/common/account/delAPIRole?
token=************************************
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	JSONArray	角色信息列表

返回格式:

{
"code": 0,
"data": [
    {
      "role_name": "管理员",
      "role_code": "admin1",
      "description": "测试帐号"
    }
],
"message": "OK"}

1
2
3
4
5
6
7
8
9
10

# 8.8 新增角色与设备关系

请求url: /common/account/addRoleDeviceRelation
请求方式: GET
描述: 该接口用于添加角色和设备之间的关系，例如给角色赋予设备的读权限。如果应用有这个角色，应用就可以读取该设备的数据。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	是	角色代码，中文请用utf8编码
wId	String	是	设备在微瓴的唯一标识
project_id	String	否	项目编号

请求示例：

/common/account/addRoleDeviceRelation?
token=************************************
&role_code=admin1
&wId=******************
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4
5
6

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
  "code": 0,
  "message": "OK"
}

1
2
3
4

# 8.9 删除角色与设备关系

请求url: /common/account/delRoleDeviceRelation
请求方式: GET
描述: 用于删除角色和设备之间的关系，删除角色对设备的控制权限
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	是	角色代码，中文请用utf8编码
wId	String	是	设备在微瓴的唯一标识
project_id	String	否	项目编号

请求示例：

/common/account/delRoleDeviceRelation?
token=************************************
&role_code=admin1
&wId=*************************************
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4
5
6

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
del_count	Integer	删除的记录数

返回格式:

{
  "code": 0,
  "data": { "del_count": 1 },
  "message": "OK"
}

1
2
3
4
5

# 8.10 查询角色与设备关系

请求url: /common/account/findRoleDeviceRelation
请求方式: GET
描述: 该接口用于查询该应用下某个角色有权限的设备列表信息。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	是	角色代码，中文请用utf8编码
num	Integer	是	分页参数：每页显示的数量
page	Integer	是	分页参数：返回的页码
project_id	String	否	项目编号

请求示例：

/common/account/findRoleDeviceRelation?
token=************************************
&role_code=admin1
&page=1
&num=999
&iotim_ticket=****************************
&project_id=******************************

1
2
3
4
5
6
7

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	JSONArray	查询结果
totalPage	Integer	返回的总页数
totalRow	Integer	返回的总量
wId	String	设备的唯一标识

返回格式:

{
  "code": 0,
  "data": {
    "totalpage": 1,
    "totalrow": 2,
    "list": [
      {
        "wId": "******************"
      },
      {
        "wId": "******************"
      }
    ]
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 9. 消息广播

# 9.1 发送消息到设备

请求url: /common/msg/send
请求方式: GET
描述: 用于发送设备的控制消息，通过微瓴下控数据到直连设备(具有通讯能力的设备)，直连设备再根据下控的数据进行解析成设备对应的协议，并下达到指定的设备.
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
wId	String	是	设备的唯一标识
datapoint	Long	否	自定义功能码，默认为80000
cmd	String	是	下控设备的消息内容,需UrlEncode编码（用模型中services定义的内容来下控，也可以自定义消息下控）

请求示例：

/common/msg/send?token=***********************&iotim_ticket=***************&wId=************************&datapoint=100001548&cmd=****************

cmd示例1：

{
    "profile":{
        "poiCode":"w242400",
        "modelId":"123"
    },
    "services":{
        "switch":{
            "action":"lightOn",
            "color":"red"
        }
    }
}
//urlEncode:%7B%22profile%22%3A%7B%22poiCode%22%3A%22w242400%22%2C%22modelId%22%3A%22123%22%7D%2C%22services%22%3A%7B%22switch%22%3A%7B%22action%22%3A%22lightOn%22%2C%22color%22%3A%22red%22%7D%7D%7D

1
2
3
4
5
6
7
8
9
10
11
12
13

cmd示例2：

{"action":"lightOn"}
//urlEncode:%7B%22action%22%3A%22lightOn%22%7D

1
2

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	返回数据
seq	String	该次请求的seq

返回格式:

{
  "code": 0,
  "message": "OK",
  "data": {
    "seq": 5031738
  }
}

1
2
3
4
5
6
7

# 9.2 智能设备控制

请求url: /common/msg/controller
请求方式: GET
描述: 用于发送消息到设备，需要实现对应设备协议。仅适用于植入物联SDK模式，如果不是，建议采用9.1接口。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
din	String	是	设备的唯一标识
data	String	是	控制内容，需 UrlEncode
seq	Integer	是	序列号。在同一个 wId 之中相邻的两条请求中，如果 seq 相同则屏蔽后一条
sub_id	JsonArray	否	子节点 ID，用于对网关下设备进行群控操作，直连设备忽略该参数
timestamp	String	是	时间戳，单位：毫秒
cmd	String	是	sss控制命令

请求示例：

/common/msg/controller?
token=**************
&din=***************
&data={
  "timestamp":1494919323720,
  "sub_id":["031605230002","031605230003"],
  "seq":1,
  "cmd":{
    "bri":50,
    "on":true,
    "rgb":[100,100,100],
    "ct":100}
    }
&iotim_ticket=******

1
2
3
4
5
6
7
8
9
10
11
12
13
14

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	操作结果
update_num	Integer	录像记录修改数量

返回格式:

{
      "code": 0,
      "message": "OK",
      "data": {
         "update_num": 1000
      }
  }

1
2
3
4
5
6
7

# 9.3 文件上传

请求url: /common/msg/sendFile
请求方式: GET
描述: 通过对象存储（Cloud Object Storage，简称：COS）发送文件到设备，获取文件在COS上的信息。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
dins	String	是	设备 din，可以以","分隔，发送给多个设备
fileName	String	是	上传的文件名
fileSize	Integer	是	上传的文件大小，单位：byte
hashCode	String	是	本次上传文件的 hash 值
fileMD5	String	是	本次上传文件的 MD5 值
data	String	是	给设备发送的自定义消息内容

请求示例：

/common/msg/sendFile?
token=*******************************************************
&dins=***************
&fileName=img.png
&fileSize=8898
&hashCode=913cf4af128d078db1b21f3b85462bd8e5d7116f
&fileMD5=cc2e46c7dd477b86d0c729b2362a7cd0
&data=test
&iotim_ticket=***********************************************

1
2
3
4
5
6
7
8
9

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	操作结果
file_id	String	该次发送的文件 ID
cos_authorization	String	上传至 COS 系统所需的授权码
url	String	上传文件路径
host	String	上传至 cos 时的 header
x-cos-content-sha1	String	上传至 cos 时的 header

返回格式:

{
    "code":0,
    "data":{
        "x-cos-content-sha1":"913cf4af128dsd078db1b21f3b85462bd8e5d7116f",
        "file_id":"eb54f755-b2c6-4e0e-8e9f-cb035fdhdf0b9962",
        "host":"temporary-file-upload-137-130014261223318.cos.ap-guangzhou.myqcloud.com",
        "cos_authorization":"string-demo",
        "url":"http://tddfgary-file-ugdsad-137-1300142618.cos.ap-.com/iot_cos/20200825/eb54f755-b2c6-4e0e-8e9f/img.png"
    },
    "message":"OK"
}

1
2
3
4
5
6
7
8
9
10
11

上传url：sendFile返回的url
请求方式：PUT
请求头：

{
    "x-cos-content-sha1":"x-cos-content-sha1",//sendFile返回的x-cos-content-sha1的值
    "host":"host",//sendFile返回的host的值
    "Authorization":"cos_authorization"//sendFile返回的cos_authorization的值
}

1
2
3
4
5

返回状态码为200表示上传成功

# 9.4 通知平台文件已上传

请求url: /common/msg/fileNotify
请求方式: GET
描述: 通知平台发送文件在COS上链接到具体的设备。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
fileId	String	是	文件 ID
uploadResult	String	是	上传文件结果，success：成功，fail：失败

请求示例：

/common/msg/fileNotify?
token=*******************************************************
&fileId=0fdb0373-1921-4b87-90ff-41740670bff0
&uploadResult=success
&iotim_ticket=***********************************************

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
  "code": 0,
  "message": "OK"
}

1
2
3
4

返回ok后，设备侧可以收到dataponit id为30003的消息，接收格式查看此接口文档 (opens new window)

# 9.5 消息推送接口

请求url: /common/msg/report
请求方式: POST
描述: 消息广播接口，发送消息到平台。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数，登录获取的动态密钥
iotim_ticket	String	是	鉴权参数，登录获取的物联票据
message_type	Integer	是	消息类型，详见附录 (opens new window)
content	Object	是	消息内容，详见附录 (opens new window)

请求示例：

/common/msg/report?
token=*******************************************************
&iotim_ticket=***********************************************
a.请求头：Content-Type:application/json
b.请求包体:{"message_type":1000100,"content":"test content"}

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	操作结果
seq	String	消息的seq

返回格式:

{
  "code": 0,
  "message": "OK",
  "data": {
    "seq": "5031740"
  }
}

1
2
3
4
5
6
7

# 9.6 应用接收消息格式（来源应用）

请求方式: POST
描述: 微瓴主动推送消息给到应用端的消息格式。
参数列表:

字段名称	字段类型	是否必须	字段描述
cookie	String	是	本条消息的cookie，接收到需要返回
apiName	String	是	消息类型，"report_data_point"：表示设备主动上报， "set_data_point_res"：表示设备是根据某条下发消息所回应的数据， “api_broadcast ”来自于api 调用
from_app	String	是	消息来源的appid
time	Object	是	消息发送时间
value	Object	是	自定义消息内容
seq	Object	是	消息唯一编号

请求示例：

a.请求头：Content-Type:application/json
b.请求包体:{"apiName":"api_broadcaster","cookie":"29412_1063711","from_app":"40291","time":1561014001593,"value":"value text","seq":"13015327"}

1
2

返回参数: 需要消息接收方返回的内容

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
cookie	String	请求时所带参数

返回格式:

{
  "code": 0,
  "cookie": "29412_1063711"
}

1
2
3
4

# 9.7 应用接收消息格式（来源设备）

请求方式: POST
描述: 微瓴主动推送消息给到应用端的消息格式。
参数列表:

字段名称	字段类型	是否必须	字段描述
cookie	String	是	本条消息的cookie，接收到需要返回
apiName	String	是	消息类型，"report_data_point"：表示设备主动上报， "set_data_point_res"：表示设备是根据某条下发消息所回应的数据， “api_broadcast ”来自于api 调用
wId	String	是	设备唯一标识
errmsg	Object	是	异常消息内容
id	Object	是	datapoint id 表示功能ID 可选，硬件会上报，app也是可选项
time	Object	是	消息发送时间
type	Object	是	消息格式
value	Object	是	自定义消息内容
seq	Object	是	消息唯一编号

请求示例：

a.请求头：Content-Type:application/json
b.请求包体:{
  "apiName": "report_data_point",
  "cookie": "16198_577418",
  "wId": "********",
  "errmsg": "",
  "id": 20134,
  "time": 1511802600575,
  "type": "string",
  "value":"{\"V\":1,\"subid\":\"0900009\",\"list\":[{\"func\":\"CO2\",\"value\":\"972180.00\"}],\"timestamp\":1511802557768}",
  "seq": "0"
}

1
2
3
4
5
6
7
8
9
10
11
12

返回参数: 需要消息接收方返回的内容

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
cookie	String	请求时所带参数

返回格式:

{
  "code": 0,
  "cookie": "29412_1063711"
}

1
2
3
4

# 9.8 应用回调黑名单规则

应用回调地址请求失败次数超过5次则进入黑名单，第6次请求失败进入黑名单1分钟，第7次失败进入黑名单5分钟，第8次及之后进入黑名单15分钟；
进入黑名单后，在限制时间内不会再请求其回调地址；
从第一次进入黑名单起开始计算规则生效时间，超过1小时清空请求失败计数，重置黑名单规则；
应用回调地址请求成功后，也将重置黑名单规则。

# 9.9 以动作触发的方式发送消息到设备

请求url: /common/msg/triggerAction
请求方式: POST
描述: 用于发送设备的控制消息，通过微瓴管理平台上配置动作，将动作关联的数据下控到直连设备(具有通讯能力的设备)，直连设备再根据下控的数据进行解析成设备对应的协议，并下达到指定的设备。
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
wId	String	否	设备的唯一标识
action_id	Integer	是	动作ID
cmd	Json	是	下控设备的动态消息内容，用于替换动作的自定义消息中的某些动态数据，json格式

请求示例：

/common/msg/triggerAction?token=***********************&iotim_ticket=***************
a.请求头：Content-Type:application/json;charset=UTF-8
b.请求包体:{"wId":"************************","cmd":{"action":"lightOn"},"action_id":1}

1
2
3

cmd是json数据，示例如下：

{
	"profile": {
		"poiCode": "w242400",
		"modelId": "123"
	},
	"services": {
		"switch": {
			"action": "lightOn",
			"color": "red"
		}
	}
}

1
2
3
4
5
6
7
8
9
10
11
12

管理平台上动作消息以物模型模板的形式存在，支持动态值配置，动态值以%%()来标识，cmd中的数据是动态值的数据来源，通过动态替换得到最终的下发消息。动态值数据替换示例：

cmd消息数据：
 {
  "id": 123,
  "value": {
    "device": 789,
    "list": [
      "hello",
      "world"
    ]
  }
}

动作模板消息：
 {
  "action": "open",
  "device_id": "%%(value.device)",
  "item": "%%(value.list[0])",
  "item2": "%%(value.list[2])"
}

则动作发送的最终消息为：
 {
  "action": "open",
  "device_id": 789,
  "item": "hello",
  "item2": "NULL"
}

说明：如果动态值在cmd中不存在，则以 NULL 替换；支持数组取值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	返回数据
seq	String	String

返回格式:

{
  "code": 0,
  "message": "OK",
  "data": {
    "seq": 5031738
  }
}

1
2
3
4
5
6
7

# 10. 应用功能权限管理

# 10.1 查询角色的功能列表

请求url: /common/permission/findRolePermissionList
请求方式: get
描述: 根据角色编号查询对应的功能列表
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_code	String	是	角色编号
project_id	String	否	项目编号

请求示例：

/common/permission/findRolePermissionList?
token=****** 
&iotim_ticket=********
&role_code=******
&project_id=******

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息
data	Json	查询结果
role_code	String	角色码
role_name	String	角色名称
permission_list	JSONArray	权限列表
cp_id	Integer	功能编号
parent_cp_id	Integer	父功能编号
value	String	功能值
name	String	功能名称
type	String	功能类型

返回格式:

{
  "code": "0",
  "message": "ok",
  "data": {
    "role_code": "",
    "role_name": "",
    "permission_list": [
      {
        "cp_id": 123,
        "parent_cp_id ": 152,
        "value": "",
        "name": "",
        "type": ""
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 10.2 新增应用功能信息

请求url:/common/permission/addCustomPermission
请求方式: get
描述: 给应用新增一个功能信息
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
project_id	String	是	项目编号
parent_id	String	否	父功能编号
val	String	是	功能值
name	String	是	功能名称
type	String	是	功能类型
is_vaild	String	是	是否有效：-1为无效,0为有效
order	String	是	排序
email	String	是	用户注册邮箱

请求示例：

/common/permission/addCustomPermission?
token=********
&iotim_ticket =**************
&project_id =**************
&parentId =**************
&val =**************
&name =**************
&type =**************
&is_vaild=**************
&order=**************

1
2
3
4
5
6
7
8
9
10

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
    "code":0,
    "data":{
        "cp_id":"358"
    },
    "message":"OK"
}

1
2
3
4
5
6
7

10.3 修改应用功能信息

请求url: /common/permission/updateCustomPermission
请求方式: get
描述: 修改应用的功能信息
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
cp_id	String	是	功能编号
parent_id	String	否	父功能编号
val	String	否	功能值
name	String	否	功能名称
type	String	否	功能类型
is_vaild	String	否	是否有效
order	String	否	排序
project_id	String	否	项目编号

请求示例：

/common/permission/updateCustomPermission?
token=********
&iotim_ticket =************
&parent_id =**************
&val =**************
&name =**************
&type =**************
&is_vaild =**************
&order =**************

1
2
3
4
5
6
7
8
9

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
 "code": 0,
 "message": "OK"
}

1
2
3
4

10.4 根据应用删除应用功能

请求url: /common/permission/ delCustomPermission
请求方式: get
描述: 删除当前应用的一个API功能，被删除的功能代码不能再使用
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
cp_id	String	是	功能编号
is_del_sub	String	否	默认false，为true则递归删除子类
project_id	String	否	项目编号

请求示例：

/common/permission/delCustomPermission?
token=********
&iotim_ticket=************
&cp_id=********
&is_del_sub=********

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
 "code": 0,
 "message": "OK"
}

1
2
3
4

10.5 新增角色的应用功能权限

请求url: /common/permission/addApiRoleCp
请求方式:get
描述: 给角色新增应用功能权限
参数列表:

字段名称	字段类型	是否必须	字段描述
token	String	是	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	鉴权参数：登录获取的物联票据
role_id	String	是	角色编号
cp_id	String	是	功能编号
project_id	String	否	项目编号

请求示例：

/common/permission/addApiRoleCp?
token=********
&iotim_ticket=**********
&role_id=********
&cp_id=********

1
2
3
4
5

返回参数:

字段名称	字段类型	字段描述
code	Int	错误码，0表示成功，其他见错误码说明
message	String	执行结果消息

返回格式:

{
 "code": 0,
 "message": "OK"
}

1
2
3
4

# 11. 对象存储上传下载

# 11.1 获取临时上传地址

请求url：/common/fileservice/uploadTemporaryFile
请求方式：GET
描述：该接口支持多租户按项目临时存储，最大支持上传单个大小为1G的文件，不支持断点续传。客户端通过此接口获取临时文件上传的地址，然后对得到的地址发送HTTP PUT请求，把文件以二进制流的形式附在body上传到该地址。文件在微瓴默认保存时效为1小时，最大保存90天，超过保存时效后文件将被清理，请在时效内通过common/fileservice/downloadTemporaryFile接口下载上传的文件。同一个上传地址，在有效期内，上传多个文件，可用文件是最后一个上传文件。
请求参数

参数名称	类型	长度	是否必填	描述
token	string	无限制	true	鉴权参数：登录获取的动态密钥
iotim_ticket	string	无限制	true	鉴权参数：登录获取的物联票据
file_name	string	100	true	文件名
expired_time	Integer	无限制	false	获取的上传地址的有效时间，单位为秒，默认为3600秒
file_save_seconds	Integer	无限制	false	文件保存时效，单位为秒，默认为3600秒，最大保存7776000秒

请求示例

/common/fileservice/uploadTemporaryFile?
token=***********************
&file_name=test.jpg
&expired_time=3600
&file_save_seconds=3600

1
2
3
4
5

返回参数

参数名称	类型	是否必填	参数长度	描述
code	Int	true	无限制	错误码表，0表示成功，其他见错误码表
message	string	false	无限制	执行结果消息
data	JSON	false	无限制	返回结果
file_id	string	false	无限制	文件id
upload_url	string	false	无限制	文件上传地址

返回示例

{
  "code": 0,
  "data": {
    "file_id": "dec8d6f8-577f-4850-97bb-19059af93889",
    "upload_url": "https://temporarybucket-30035.sz.gfp.tencent-cloud.com/1000/10000/temporary-file-upload/20190725/common/1564036741985-dec8d6f8-577f-4850-97bb-19059af93889.jpg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DJwxbdHXcgrqZyWxNOcqdDnN0%26q-sign-time%3D1564036741%3B1564040341%26q-key-time%3D1564036741%3B1564040341%26q-header-list%3Dhost%3Bx-cos-content-sha1%26q-url-param-list%3D%26q-signature%3Dba3e7fc12e2a033c73b83f921ded736e9759ad9b"
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8

# 11.2 获取临时下载地址

请求url：/common/fileservice/downloadTemporaryFile
请求方式：GET
描述：客户端调用该接口获取下载地址，通过HTTP GET请求下载地址的方式将文件流转成文件。
请求参数

参数名称	类型	参数长度	是否必填	描述
token	string	无限制	true	鉴权参数：登录获取的动态密钥
iotim_ticket	string	无限制	true	鉴权参数：登录获取的物联票据
expired_time	Integer	无限制	false	获取的下载地址有效时间，单位为秒，默认为1200秒
file_id	string	无限制	true	文件id

请求示例

/common/fileservice/downloadTemporaryFile?
token=******************
&expired_time=3600
&file_id=dec8d6f8-577f-4850-97bb-19059af93889

1
2
3
4

返回参数

参数名称	类型	是否必填	参数长度	描述
code	Int	true	无限制	错误码表，0表示成功，其他见错误码表
message	string	false	无限制	执行结果消息
data	JSON	false	无限制	返回结果
filename	string	false	无限制	文件名
downloadUrl	string	false	无限制	文件下载地址

返回示例：

{
  "code": 0,
  "data": {
    "filename": "test.jpg",
    "downloadUrl": "https://temporarybucket-30035.sz.gfp.tencent-cloud.com/1000/10000/temporary-file-upload/20190725/common/1564036741985-dec8d6f8-577f-4850-97bb-19059af93889.jpg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DJwxbdHXcgrqZyWxNOcqdDnN0%26q-sign-time%3D1564036913%3B1564040513%26q-key-time%3D1564036913%3B1564040513%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3Ddb929c4a291b98cade0eeedf12f966718c56e11a"
  },
  "message": "OK"
}

1
2
3
4
5
6
7
8

12. 一码通服务

12.1 电子码解码

特殊字段使用申请：

使用电子邮箱发送需要用到的特殊字段到zhimuli@tencent.com进行申请，邮件中注明应用 APPKEY、应用名称和应用使用场景。

请求url：/wecard/apps/school-api/campus-code
请求方式：POST
请求参数

参数名称	类型	是否必填	示例	描述
token	String	是	abcde	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	abcde	鉴权参数：登录获取的物联票据
scene	int	是	1	1.门禁 2.消费 3.签到 4.其它
device_no	String(64)	是	device-1213	设备编号
location	String(64)	否	三食堂	扫码地点
auth_code	String	是	http://wx.url.cn/v001.Eee8m...kA	扫码获得的动态码

注：token和iotim_ticket放置在 url 后方

POST 请求体：

{
  "auth_code": "AUTH_CODE",
  "scene": "SCENE",
  "device_no": "DEVICE_NO",
  "location": "LOCATION"
}

1
2
3
4
5
6

请求示例:

/wecard/apps/school-api/campus-code?
token=***********************************
&iotim_ticket=****************************
a.headers: Content-Type: application/json
b.body: {"device_no":"device-1213","location":"三食堂","auth_code":"http://wx.url.cn/v001.Eee8m...kA","scene":4}

1
2
3
4
5

返回参数：

参数名称	类型	是否必填	示例	描述
code	Int	是	0	响应状态码，0 为成功
offline	Integer	是	0	1 表示当前码为离线码；0 表示当前码为在线码
card_number	String(32)	是	07302590	用户学工号
name	Integer	是	陈小明	用户姓名（需申请）
entrusts	Integer	是	0	签约状态，0：未签约，1：已签约（需申请）
risk	Integer	是	0	风控等级（需申请）
identity_type	Integer	是	1	成员身份类型（需申请），参考文档成员身份类型列表
grade	String	否	2016	年级（需申请）
college	String	否	人居环境工程学院	学院（需申请）
profession	String	否	工程造价	专业（需申请）
class	String	否	1 班	班级（需申请）
identity_title	String	否	本科生	身份职称（需申请）
gender	Integer	否	1	性别，0 为未知，1 为男，2 为女（需申请）
campus	String	否	东校区	校区（需申请）
dorm_number	String	否	至善园	6 号
physical_chip_number	String	否	xaqwecf	物理芯片号（需申请）
physical_card_number	String	否	fqweasd	物理卡号（需申请）
nation	String	否	汉族	民族（需申请）
birthday	String	否	20020319	生日（需申请）
origin_place	String	否	深圳市	生源地（需申请）
graduated_school	String	否	小碧中学	毕业学校（需申请）
address	String	否	广东省深圳市	地址（需申请）
contact_person	String	否	陈大明	联系人姓名（需申请）
contact_phone	String	否	(+86)13800138000	联系人手机号码（带区号）（需申请）
email	String	否	605135612@qq.com	用户邮箱（需申请）
id_card	String	否	440305200203194013	身份证（需申请）
telephone	String	否	(+86)13800138000	手机号码（带区号）（需申请）
expire_at	Datatime	否	2019-10-18 00:00:00	有效结束时间（需申请）
create_at	Datetime	否	2019-10-16 00:00:00	创建时间（需申请）

返回示例：

{
  "code": 0,
  "offline": "0",
  "user": {
    "card_number": "07302590",
    "entrusts": "0",
    "risk": "0",
    "name": "陈小明",
    "identity_type": "1",
    "grade": "2016",
    "college": "人居环境工程学院",
    "profession": " 工程造价",
    "class": "1班",
    "identity_title": "本科生",
    "gender": 1,
    "campus": "东校区",
    "dorm_number": "至善园",
    "physical_chip_number": "xaqwecf",
    "physical_card_number": "fqweasd",
    "nation": "汉族",
    "birthday": "20020319",
    "origin_place": "深圳市",
    "graduated_school": "小碧中学",
    "address": "广东省深圳市",
    "contact_person": "陈大明",
    "contact_phone": "(+86)13800138000",
    "email": "605135612@qq.com",
    "id_card": "440305200203194013",
    "telephone": "(+86)13800138000",
    "expire_at": "2019-10-18 00:00:00",
    "create_at": "2019-10-16 00:00:00"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

错误时返回：

{
  "code": 1000,
  "message": "必填参数不存在"
}

1
2
3
4

参数	是否可空	说明
code	非空	返回码（0 表示成功）
message	非空	提示信息

错误码：

名称	解决方案
1000	必填参数不存在
10003	解码失败
10004	解码成功，二维码已过期
10005	权限不足
10006	该码已被截图
10007	该码已被使用
20000	内部错误

12.2 发送通知

特殊字段使用申请：

使用电子邮箱发送需要用到的特殊字段到zhimuli@tencent.com进行申请，邮件中注明应用 APPKEY、应用名称和应用使用场景。

请求url：/wecard/cgi-bin/notice/send
请求方式：POST
描述：通过主体的发卡公众号向指定的用户（可批量）发送通知。
请求参数

参数名称	类型	是否必填	示例	说明
token	String	是	abcde	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	abcde	鉴权参数：登录获取的物联票据
cards	String	是	["111111111","222222222","333333333"]	学号数组，转成 Json
title	String(100)	是	全体代表大会	通知标题
content	String(1000)	是	请大家务必参加	通知内容
sender	String(60)	是	教务处	通知人
digest	String(100)	否	请大家务必参加	通知摘要，如不传会自动截取通知内容文案
customs	String	否	["You have a notice to check","https://weixiao.qq.com"]	自定义参数，分别为提示文案和通知跳转链接，如不传则公众号模版消息会默认显示'你有一条通知待查看'，并跳转到微校通知详情页

注：token和iotim_ticket放置在 url 后方

POST 请求体：

{
  "cards": "CARDS",
  "title": "TITLE",
  "content": "CONTENT",
  "sender": "SENDER",
  "digest": "DIGEST",
  "customs": "CUSTOMS"
}

1
2
3
4
5
6
7
8

请求示例:

/wecard/cgi-bin/notice/send?
token=***********************************
&iotim_ticket=****************************
a.headers: Content-Type: application/json
b.body: {"cards":"[\"此处填指定卡号\"]","sender":"教务处","customs":"[\"You have a notice to check\",\"https://weixiao.qq.com\"]","digest":"自定义参数","title":"全体代表大会","content":"请大家务必参加"}

1
2
3
4
5

返回参数：

参数	是否可空	说明
code	非空	返回码 (0 表示成功)
message	非空	提示信息
mark	可空	通知标识,可通过此值调接口查询该通知的数据明细和已读情况

返回示例：

{
  "code": 0,
  "message": "ok",
  "mark": "***"
}

1
2
3
4
5

错误码：

名称	解决方案
1003	没有权限（请联系工作人员开通该权限）
1004	参数错误
1005	参数缺失（请核对参数 cards）
1015	网络错误（请重试）
47001	学校标识码不合法（请核对参数 school_code）
10010016	必填参数缺失
20000	内部错误

12.3 获取组织架构

请求url：/wecard/cgi-bin/user/org-edu-list
请求方式：POST
请求参数

参数名称	类型	是否必填	示例	说明
token	String	是	abcde	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	abcde	鉴权参数：登录获取的物联票据
page	Integer	是	1	分页下标
page_size	Integer	是	5000	分页大小，每页最大数据是 5000

注：token和iotim_ticket放置在 url 后方

POST 请求体：

{
  "page": 1,
  "page_size": 50
}

1
2
3
4

请求示例:

/wecard/cgi-bin/user/org-edu-list?
token=***********************************
&iotim_ticket=****************************
a.headers: Content-Type: application/json
b.body: {"page":1,"page_size":50}

1
2
3
4
5

返回参数：

参数名称	类型	是否必填	示例	说明
errcode	Integer	是	0	响应状态码，0 为成功
errmsg	String	是	success	响应状态信息
page	Integer	是	1	当前获取数据为第几页
page_size	Integer	是	5000	当前获取数据的页大小
total	Integer	是	9800	该主体下组织架构总数
id	Integer	是	9751	组织架构唯一 id
name	String	是	广东省深圳市南山区教育局	组织架构名称
parent_id	Integer	是	0	父级组织架构唯一 id
updated_at	Datetime	是	2019-04-22 11:34:05	组织架构信息更新时间
area	String	是	南山区	区域
province	String	是	广东	省份
city	String	是	深圳	城市
org_type	String	是	普通组织	组织类型
type	Integer	是	0	类型

返回示例：

正确时返回的 json 数据包如下：

{
  "errcode": 0,
  "errmsg": "success",
  "page": 1,
  "page_size": 5000,
  "total": 9800,
  "organization": [
    {
      "id": 9751,
      "name": "广东省深圳市南山区教育局",
      "parent_id": "0",
      "updated_at": "2019-04-22 11:34:05",
      "area": "",
      "province": "",
      "city": "",
      "org_type": "",
      "type": 0
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

12.4 获取单个组织架构成员

特殊字段使用申请：

使用电子邮箱发送需要用到的特殊字段到zhimuli@tencent.com进行申请，邮件中注明应用 APPKEY、应用名称和应用使用场景。

请求url：/wecard/cgi-bin/user/get-org-users
请求方式：POST
请求参数

参数名称	类型	是否必填	示例	说明
token	String	是	abcde	鉴权参数：登录获取的动态密钥
iotim_ticket	String	是	abcde	鉴权参数：登录获取的物联票据
org_id	Integer	是	232	组织架构唯一 id
fetch_child	Integer	是	0	是否递归获取子组织架构下面的成员：1-是；0-否，默认为否
page	Integer	是	1	分页下标
page_size	Integer	是	5000	分页大小，每页最大数据是 5000

注：token和iotim_ticket放置在 url 后方

POST 请求体：

{
  "org_id": 0,
  "fetch_child": 0,
  "page": 1,
  "page_size": 50
}

1
2
3
4
5
6

请求示例:

/wecard/cgi-bin/user/get-org-users?
token=***********************************
&iotim_ticket=****************************
a.headers: Content-Type: application/json
b.body: {"fetch_child":0,"org_id":0,"page":1,"page_size":50}

1
2
3
4
5

返回参数：

参数	必填	类型	实例	说明
errcode	是	Integer	0	响应状态码，0 为成功
errmsg	是	String	success	响应状态信息
page	是	Integer	1	当前获取数据为第几页
page_size	是	Integer	5000	当前获取数据的页大小
total	是	Integer	98000	该组织架构下所有的用户总数
card_number	是	String(32)	07302590	用户学工号
name	是	Integer	陈小明	用户姓名
identity_type	是	Integer	1	成员身份类型，参考文档成员身份类型列表
grade	否	String	2016	年级（需申请）
college	否	String	人居环境工程学院	学院（需申请）
profession	否	String	工程造价	专业（需申请）
class	否	String	1	班级（需申请）
identity_title	否	String	本科生	身份职称（需申请）
gender	否	Integer	1	性别，0 为未知，1 为男，2 为女（需申请）
organization	否	Array	[2,222,496]	用户所属组织架构 id 列表（需申请）
role	否	Array	[1,2]	用户所属角色 id 列表（需申请）
campus	否	String	东校区	校区（需申请）
dorm_number	否	String	至善园 6 号	宿舍号（需申请）
physical_chip_number	否	String	xaqwecf	物理芯片号（需申请）
physical_card_number	否	String	fqweasd	物理卡号（需申请）
nation	否	String	汉族	民族（需申请）
birthday	否	String	20020319	生日（需申请）
origin_place	否	String	深圳市	生源地（需申请）
graduated_school	否	String	小碧中学	毕业学校（需申请）
address	否	String	广东省深圳市	地址（需申请）
contact_person	否	String	陈大明	联系人姓名（需申请）
contact_phone	否	String	(+86)13800138000	联系人手机号码（带区号）（需申请）
email	否	String	605135612@qq.com	用户邮箱（需申请）
id_card	否	String	440305200203194013	身份证（需申请）
telephone	否	String	(+86)13800138000	手机号码（带区号）（需申请）
bind_status	否	Integer	0	绑定状态（需申请）
frozen_status	否	Integer	0	冻结状态（需申请）
active_status	否	Integer	0	激活状态（需申请）
start_at	否	Datatime	2019-10-14 00:00:00	有效起始时间（需申请）
entrust_status	是	Integer	0	签约状态(需申请)0-未签约，1-已签约
expire_at	否	Datatime	2019-10-18 00:00:00	有效结束时间（需申请）
updated_at	否	Datatime	2019-10-16 00:00:00	用户信息变更时间（需申请）
staff_status	否	String	在职	人员状态（需申请）
head_image	否	String	https://weixiao.qq.com	头像地址

返回示例：

{
  "errcode": 0,
  "errmsg": "success",
  "page": 1,
  "page_size": 5000,
  "total": 9800,
  "userlist": [
    {
      "card_number": "07302590",
      "name": "陈小明",
      "identity_type": "1",
      "grade": "2016",
      "college": "人居环境工程学院",
      "profession": " 工程造价",
      "class": "1 班",
      "identity_title": "本科生",
      "gender": 1,
      "organization": [2, 222, 496],
      "role": [1, 2],
      "campus": "东校区",
      "dorm_number": "至善园",
      "physical_chip_number": "xaqwecf",
      "physical_card_number": "fqweasd",
      "nation": "汉族",
      "birthday": "20020319",
      "origin_place": "深圳市",
      "graduated_school": "小碧中学",
      "address": "广东省深圳市",
      "contact_person": "陈大明",
      "contact_phone": "(+86)13800138000",
      "email": "605135612@qq.com",
      "id_card": "440305200203194013",
      "telephone": "(+86)13800138000",
      "bind_status": 0,
      "frozen_status": 0,
      "active_status": 0,
      "entrust_status": 0,
      "start_at": "2019-10-14 00:00:00",
      "expire_at": "2019-10-18 00:00:00",
      "updated_at": "2019-10-16 00:00:00",
      "staff_status": "在职",
      "head_images": "https://weixiao.qq.com"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

← IOT通讯协议视频服务 →