RPC 调用通道

本文主要介绍远程过程调用（remote procedure call，RPC）调用通道的使用协议。RPC 通道主要用于提供云端 OpenAPI 的调用能力。设备可通过 MQTT 调用涂鸦的云端 OpenAPI，便于扩展现有业务，提供设备更多应用场景能力。

通用 RPC 调用通道

设备发送消息

设备主动向云端发起 RPC 请求。

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.xxx.config.get",
      	"apiVersion":"1.0",
        "params":{
        	"withVideoDataStorage":"true"
        }
	}
}

参数说明

参数	类型	说明	是否必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID。如果是子设备的身份发起调用，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	RPC 调用信息	是	RPC 名称、版本及参数信息。
data.api	string	RPC 接口名称	是	如：tuya.device.dynamic.config.ack。
data.apiVersion	string	RPC 接口版本	是	如：1.0。
data.params	object	RPC 调用参数	是	实际的接口参数对象。

设备接收消息

云端向设备发送 RPC 执行结果。

Topic: tylink/${deviceId}/channel/rpc/response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0,
    "data":{
      "success":true,
      // , "errorCode":"CAMERA_STORAGE_ORDER_NOT_EXISTED"
      // ,"errorMsg":"camera storage order not existed"
      "result":{
          "bucket":"00-00-00-000",
          "endpoint":"cos.000.com"
    	}
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID。如果是子设备的身份发起调用，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	RPC 调用状态码，0 代表成功，非 0 代表失败，默认 0。这个状态代表 RPC 通道的调用状态，不代表 RPC 执行的业务状态，RPC 调用业务是否成功需要进一步查看 data.success。
data	object	RPC 响应信息	是	RPC 调用返回结果、错误状态码等。
data.success	boolean	RPC 调用状态	是	RPC 调用是否成功，业务状态。
data.result	object	RPC 执行结果	否	RPC 执行后的返回结果。
data.errorCode	string	RPC 错误代码	否	当 RPC 执行有业务异常时返回的错误代码。
data.errorMsg	string	RPC 错误消息	否	当 RPC 执行有业务异常时返回的错误消息。

状态码说明

状态码	说明
0	默认状态，代表成功。
1001	RPC 服务调用失败。
1002	参数不合法。
1003	消息格式错误。
1006	RPC 调用超时。
1007	RPC 通道拒绝连接。
1008	未知的系统错误。
4600	RPC 通道内部响应解码失败。
4601	RPC 通道内部设备参数信息缺失。

设备 ICCID 信息上报

设备发送消息

设备主动向云端发起 RPC 请求。

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.meta.save",
      	"apiVersion":"1.0",
        "params":{
        	"metas":{
              "catIccId":"3hj21h3j2h1jh3j27***"
            }
        }
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID。如果是子设备的身份发起调用，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
data	object	RPC 调用信息	是	RPC 名称、版本及参数信息。
data.api	string	RPC 接口名称	是	如：tuya.device.meta.save。
data.apiVersion	string	RPC 接口版本	是	如：1.0。
data.params	object	RPC 调用参数	是	实际的接口参数对象。
data.params.metas.catIccId	string	4G 设备 ICCID（Integrated Circuit Card ID）信息	是	4G 设备 ICCID 信息，ICCID 为 IC 卡的识别号码，共由 20 位字符组成。

设备接收消息

云端向设备发送 RPC 执行结果。

Topic: tylink/${deviceId}/channel/rpc/response

{
    "msgId": "45lkj3551234001",
    "time": 1626197189640,
    "code": 0,
    "data": {
        "t": 1662452307,
        "success": true,
        "result": true
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID。如果是子设备的身份发起调用，deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，且仅有 1.0。
msgId	string	消息 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳，10 位秒级或 13 位毫秒级。
code	number	响应状态码	否	RPC 调用状态码，0 代表成功，非 0 代表失败，默认 0。这个状态代表 RPC 通道的调用状态，不代表 RPC 执行的业务状态，RPC 调用业务是否成功需要进一步查看 data.success。
data	object	RPC 响应信息	是	RPC 调用返回结果、错误状态码等。
data.success	boolean	RPC 调用状态	是	RPC 调用是否成功，业务状态。
data.result	object	RPC 执行结果	否	RPC 执行后的返回结果。
data.errorCode	string	RPC 错误代码	否	当 RPC 执行有业务异常时返回的错误代码。
data.errorMsg	string	RPC 错误消息	否	当 RPC 执行有业务异常时返回的错误消息。

获取绑定二维码短链

设备发送消息

设备主动向云端发起 RPC 请求。

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.qrcode.bind.info.get",
      	"apiVersion":"1.0",
        "params":{
        }
	}
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID，如果是子设备的身份发起调用 deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息的 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）。
data	object	RPC 调用信息	是	RPC 名称、版本及参数信息。
data.api	string	RPC 接口名称	是	如：tuya.open.iot.product.device.bind.code。
data.apiVersion	string	RPC 接口版本	是	如：1.0。
data.params	object	RPC 调用参数	是	实际的接口参数对象。

设备接收消息

云端向设备发送 RPC 执行结果。

Topic: tylink/${deviceId}/channel/rpc/response

{
    "msgId": "45lkj3551234001",
    "time": 1626197189640,
    "code": 0,
    "data": {
        "t": 1662452307,
        "success": true,
        "result":{
          "shortUrl":"https://t.tuya.com/AYNuQRli"
        }
    }
}

参数说明

参数	类型	说明	必选	备注
${deviceId}	string	设备 ID	是	发起 RPC 调用的设备 ID，如果是子设备的身份发起调用 deviceId 应该为子设备 ID。
version	string	协议版本	否	默认 1.0，仅有 1.0。
msgId	string	消息的 ID	是	总长度不超过 32 位的字符，请求和响应消息通过该值建立应答关系。
time	number	消息时间戳	是	消息发送时的 Unix 时间戳（10 位秒级或 13 位毫秒级）。
code	number	响应状态码	否	RPC 调用状态码，0 代表成功，非 0 代表失败，默认 0 。 这个状态代表 RPC 通道的调用状态，不代表 RPC 执行的业务状态，RPC 调用业务是否成功需要进一步查看 data.success。
data	object	RPC 响应信息	是	RPC 调用返回结果、错误状态码等。
data.success	boolean	RPC 调用状态	是	RPC 调用是否成功，业务状态。
data.result	object	RPC 执行结果	否	RPC 执行后的返回结果。
data.result.shortUrl	string	短链接	是	短链接，如：https://t.tuya.com/AYNuQRLi。
data.errorCode	string	RPC 错误代码	否	当 RPC 执行有业务异常是返回的错误代码。
data.errorMsg	string	RPC 错误消息	否	当 RPC 执行有业务异常是返回的错误消息。

更多协议内容

更多信息，请参考 MQTT 主题概览。