接口演进指导_设备接入 IoTDA_API参考_历史API_华为云

(1)

API 参考

文档版本 96

发布日期 2021-07-29

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 应用侧 API 参考

1.1 使用前必读 1.2 如何调用API 1.3 API列表 1.4 产品管理 1.5 设备管理 1.6 设备消息 1.7 设备命令 1.8 设备属性 1.9 AMQP队列管理 1.10 接入凭证管理 1.11 数据流转规则管理 1.12 流转数据

1.13 设备联动规则 1.14 设备影子 1.15 设备组管理 1.16 标签管理 1.17 资源空间管理 1.18 批量任务

1.19 设备CA证书管理 1.20 附录

(13)

1.1 使用前必读

概述

物联网平台把自身丰富的管理能力通过API的形式对外开放，包括产品管理、设备管理、设备组管理、标签管理、设备CA证书管理、设备影子、设备命令、设备消息、设备属性、订阅管理、规则管理、批量任务等，帮助用户快速构筑基于物联网平台的行业应用。您可以根据本文档提供的API来使用物联网平台的服务，平台支持的全部API 请参见API列表。

角色说明

● 如果您是新用户，推荐使用应用侧API参考中的接口。

● 如果您是老用户，想继续使用老接口，请使用应用侧API参考中的接口。

● 如果您是老用户，想升级到新接口，请详细预览接口演进指导，完成改造后，再使用应用侧API参考中的接口。

调用说明

物联网平台提供了RESTful（Representational State Transfer）风格API，支持您通过 HTTPS请求调用，调用方法请参见如何调用API。

物联网平台的Endpoint请参见：地区和终端节点。

使用限制

● API的演进会保持前向兼容性，若接口升级了版本，其旧版本接口可以继续使用，

但功能不再做增强，新增功能仅在新版本接口中提供。

● 应用在接收处理物联网平台发送的响应消息和推送消息时，需要兼容或忽略消息中的新增参数，不能因为消息中的新增参数导致应用的处理异常。

● 调用API的其他使用限制，请参见物联网平台的使用限制。

1.2 如何调用 API

1.2.1 构造请求

本节介绍REST API请求的组成，并以调用物联网平台的查询产品和创建产品接口说明如何调用API，该API可用于获取用户的指定产品信息。

请求 URI

请求URI由如下部分组成。

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传

(14)

● Endpoint：指定承载REST服务端点的服务器域名或IP，不同服务不同区域的 Endpoint不同，您可以从地区和终端节点中获取。例如物联网平台在“华北-北京四”区域的Endpoint为“iotda.cn-north-4.myhuaweicloud.com”。

● resource-path：资源路径，也即API访问路径。从具体API的URI模块获取，例如

“查询产品”API的resource-path为“/v5/iot/{project_id}/products/

{product_id}”。

● query-string：查询参数，是可选部分，并不是每个API都有查询参数。查询参数 前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

例如您需要在物联网平台获取在“华北-北京四”区域下的指定产品信息，则需使用

“华北-北京四”区域的Endpoint（iotda.cn-north-4.myhuaweicloud.com），并在查询产品的URI部分找到resource-path（/v5/iot/{project_id}/products/{product_id}），

拼接起来如下所示。

https://iotda.cn-north-4.myhuaweicloud.com/v5/iot/{project_id}/products/{product_id}

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

● GET：请求服务器返回指定资源。

● PUT：请求服务器更新指定资源。

● POST：请求服务器新增资源或执行特殊操作。

● DELETE：请求服务器删除指定资源，如删除对象等。

● HEAD：请求服务器资源头部。

● PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会 去创建一个新的资源。

在查询产品的URI部分，您可以看到其请求方法为“GET”，则其请求为：

GET https://iotda.cn-north-4.myhuaweicloud.com/v5/iot/{project_id}/products/{product_id}

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

如下公共消息头需要添加到请求中。

● Content-Type：消息体的类型（格式），必选，默认取值为“application/

json”，有其他取值时会在具体接口中专门说明。

● X-Auth-Token：用户Token。当使用Token方式认证时，必须填充该字段，可通 过调用获取用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”

就是需要获取的用户Token。

对于查询产品接口，由于需要认证，所以需要添加“Content-Type”和“X-Auth- Token”到头域，添加消息头后的请求如下所示。

(15)

Content-Type: application/json X-Auth-Token：******

请求消息体

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于创建产品接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，如：其中

name

为产品名称，

device_type

为设备类型，

protocol_type

为设备使用的协议类型。

POST https://iotda.cn-north-4.myhuaweicloud.com/v5/iot/abab***cdcd/products Content-Type: application/json

X-Auth-Token: ********

{ "name" : "Thermometer", "device_type" : "Thermometer", "protocol_type" : "MQTT", "data_format" : "binary", "manufacturer_name" : "ABC", "industry" : "smartCity",

"description" : "this is a thermometer produced by Huawei", "service_capabilities" : [ {

"service_type" : "temperature", "service_id" : "temperature", "description" : "temperature", "properties" : [ {

"unit" : "centigrade", "min" : "1",

"method" : "R", "max" : "100",

"data_type" : "decimal", "description" : "force", "step" : 0.1,

"enum_list" : [ "string" ], "required" : true,

"property_name" : "temperature", "max_length" : 100

} ],

"commands" : [ {

"command_name" : "reboot", "responses" : [ {

"response_name" : "ACK", "paras" : [ {

"unit" : "km/h", "min" : "1", "max" : "100", "para_name" : "force", "data_type" : "string", "description" : "force", "step" : 0.1,

"enum_list" : [ "string" ], "required" : false, "max_length" : 100 } ]

} ], "paras" : [ {

(16)

"para_name" : "force", "data_type" : "string", "description" : "force", "step" : 0.1,

} ],

"option" : "Mandatory"

} ],

"app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka"

}

到此请求需要的内容已具备齐全，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。

1.2.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证通用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key)加密调用请求。

Token 认证

说明

Token是服务端生成的一串字符串，作为客户端进行请求的一个令牌。第一次登录后，服务器生成一个Token并将此Token返回给客户端，以后客户端只需带上这个Token前来请求数据即可，

无需再次带上用户名和密码。Token有效期是24小时，从客户端获取开始算起（24小时是相对时间），需要使用同一个Token鉴权时，建议缓存起来使用，避免频繁调用。在Token过期前，务必刷新Token或重新获取Token，否则Token过期后会在服务端鉴权失败。

如果您获取Token多次，以最新的为准，前面的Token会被覆盖并失效。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

调用获取IAM用户Token（使用密码）接口获取Token，调用样例如下：

POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

}

(17)

} } }

注：“username”即IAM用户名、“password”即登录华为云密码、

“domainname”即账号名，“projectname”项目，您可以参考我的凭证页面获取。

接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值为获取到的Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth- Token: ABCDEFJ....”加到请求消息头即可，如下所示。

Content-Type: application/json X-Auth-Token: ABCDEFJ....

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12M以内，12M以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥 ID和私有访问密钥一起使用，对请求进行加密签名。

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见： API签名指南。

说明

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

1.2.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码

(18)

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”等。

对于创建产品接口，平台会返回“Content-type”、Date等消息头。

响应消息体

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于创建产品接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "product_id" : "5ba24f5ebbe8f56f5a14f605", "name" : "Thermometer",

"device_type" : "Thermometer", "protocol_type" : "LWM2M", "data_format" : "binary", "manufacturer_name" : "ABC", "industry" : "smartCity",

"description" : "this is a thermometer produced by Huawei", ...

}

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "IOTDA.013005"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

1.3 API 列表

调用以下接口前，请先参考认证鉴权完成认证鉴权操作。

产品管理

API 说明

查询产品列表查询已导入物联网平台的产品模型信息列表，了解产品模

型的概要信息。

创建产品创建产品。此接口仅创建了产品，没有创建和安装插件，

如果需要对数据进行编解码，还需要在平台开发和安装插件。

查询产品查询已导入物联网平台的指定产品模型详细信息，包括产

品模型的服务、属性、命令等。

修改产品修改已导入物联网平台的指定产品模型，包括产品模型的

服务、属性、命令等。此接口仅修改了产品，未修改和安装插件，如果修改了产品中的service定义，且在平台中有对应的插件，请修改并重新安装插件。

删除产品删除已导入物联网平台的指定产品模型。

(19)

设备管理

API 说明

查询设备列表查询物联网平台中的设备信息列表。

创建设备在物联网平台注册一个设备，仅在注册后设备才可以接入

物联网平台。

查询设备查询物联网平台中指定设备的详细信息。

修改设备修改物联网平台中指定设备的基本信息。

删除设备在物联网平台上删除指定设备。若设备下连接了非直连设

备，则必须把设备下的非直连设备都删除后，才能删除该设备。

重置设备密钥重置设备密钥，携带指定密钥时平台将设备密钥重置为指

定的密钥，不携带密钥时平台将自动生成一个新的随机密钥返回。

冻结设备冻结设备，设备冻结后不能再连接上线，可以通过解冻设

备接口解除设备冻结。注意，当前仅支持冻结与平台直连的设备。

解冻设备解冻设备，解除冻结后，设备可以连接上线。

设备消息

API 说明

查询设备消息查询指定设备下的消息，平台为每个设备默认最多保存20

条消息，超过20条后，后续的消息会替换下发最早的消息。

下发设备消息向设备下发消息，应用服务器可调用此接口向指定设备下

发消息，以实现对设备的控制。应用将消息下发给平台后，平台返回应用响应结果，平台再将消息发送给设备。

查询指定消息id的消息查询指定消息id的消息。

设备命令

API 说明

下发设备命令设备的产品模型中定义了物联网平台可向设备下发的命

令，应用服务器可调用此接口向指定设备下发同步命令，

以实现对设备的同步控制。

(20)

API 说明

下发异步设备命令设备的产品模型中定义了物联网平台可向设备下发的命

令，应用服务器可调用此接口向指定设备下发异步命令，

以实现对设备的控制。

查询指定id的命令可通过指定id查询某条特定命令。

设备属性

API 说明

查询设备属性设备的产品模型中定义了物联网平台可向设备下发的属

性，应用服务器可调用此接口查询指定设备下属性。

修改设备属性设备的产品模型中定义了物联网平台可向设备下发的属

性，应用服务器可调用此接口向指定设备下属性。平台负责将属性以同步方式发送给设备，并将设备执行属性结果同步返回。

AMQP 队列管理

API 说明

查询AMQP列表可调用此接口查询物联网平台中的AMQP队列信息列表。

创建AMQP队列可调用此接口在物联网平台创建AMQP队列。您可以通过

调用数据流转规则管理接口，将数据推送到此AMQP队列。

查询单个AMQP队列可调用此接口查询物联网平台中指定队列的详细信息。

删除AMQP队列可调用此接口在物联网平台上删除指定AMQP队列。

接入凭证管理

API 说明

生成接入凭证接入码是用于客户端使用AMQP等协议与平台建链的一个

认证凭据，调用该接口将会生成一对新的接入码。

数据流转规则管理

API 说明

查询规则条件列表可调用此接口查询物联网平台中设置的规则条件列表。

(21)

API 说明

创建规则触发条件可调用此接口在物联网平台创建一条规则触发条件。

查询规则条件可调用此接口查询物联网平台中指定规则条件的配置信

息。

修改规则触发条件可调用此接口修改物联网平台中指定规则条件的配置参

数。

删除规则触发条件可调用此接口删除物联网平台中的指定规则条件。

查询规则动作列表可调用此接口查询物联网平台中设置的规则动作列表。

修改规则动作可调用此接口在物联网平台创建一条规则动作。

查询规则动作可调用此接口查询物联网平台中指定规则动作的配置信

息。

修改规则动作可调用此接口修改物联网平台中指定规则动作的配置。

删除规则动作可调用此接口删除物联网平台中的指定规则动作。

流转数据

API 说明

查询设备消息应用服务器在物联网平台创建设备状态变更通知规则后，当物

联网平台中的设备状态发生变更时，平台会向应用服务器推送通知消息。

设备属性上报通知应用服务器在物联网平台创建了设备属性上报通知规则后，当

设备上报属性数据时，平台会向应用服务器推送通知消息。

设备消息状态变更通知

应用服务器在物联网平台创建了消息状态变更通知规则后，当设备消息状态变更时，平台会向应用服务器推送通知消息。

批量任务状态变更通知

应用服务器在物联网平台创建了批量任务状态变更通知规则后，当批量任务状态变更时，平台会向应用服务器推送通知消息。

设备消息上报通知应用服务器在物联网平台创建了设备消息上报通知规则后，当

设备上报消息数据时，平台会向应用服务器推送通知消息。

设备添加通知应用服务器在物联网平台创建了设备添加事件规则后，当物联

网平台中的设备添加时，平台会向应用服务器推送通知消息。

设备更新通知应用服务器在物联网平台创建了设备更新事件规则后，当物联

网平台中的设备更新时，平台会向应用服务器推送通知消息。

设备删除通知应用服务器在物联网平台创建了设备删除通知事件规则后，当

物联网平台中的设备删除时，平台会向应用服务器推送通知消息。

(22)

API 说明

产品添加通知应用服务器在物联网平台创建了产品添加通知事件规则后，当

物联网平台中的产品添加时，平台会向应用服务器推送通知消息。

产品更新通知应用服务器在物联网平台创建了产品更新通知事件规则后，当

物联网平台中的产品更新时，平台会向应用服务器推送通知消息。

产品删除通知应用服务器在物联网平台创建了产品删除通知事件规则后，当

物联网平台中的产品删除时，平台会向应用服务器推送通知消息。

设备异步命令状态变更通知

应用服务器在物联网平台创建了命令状态变更通知后，当命令状态变更时，平台会向应用服务器推送通知消息。

设备联动规则

API 说明

查询规则列表查询物联网平台中设置的设备联动规则列表。

创建规则在物联网平台创建一条设备联动规则。

查询规则查询物联网平台中指定规则的配置信息。

修改规则修改物联网平台中指定规则的配置。

删除规则删除物联网平台中的指定规则。

修改规则状态修改物联网平台中指定规则的状态，激活或者去激活规

则。

设备影子

API 说明

查询设备影子数据查询指定设备的设备影子信息，包括对设备的配置信息

（desired区）和设备最新上报的数据信息（reported 区）。当前仅使用LWM2M协议的设备支持设备影子功能，且仅支持修改LwM2M协议定义的属性信息，用户自定义的属性暂不支持修改。

配置设备影子预期数据配置设备影子的预期数据（desired区），当设备上线时把

数据下发给设备。设备影子的属性和产品模型耦合在一起，配置的预期属性需在产品模型中定义且method具有可写属性“W”才可下发。当前仅使用LWM2M协议的设备支持设备影子功能，且仅支持修改LWM2M协议定义的属性信息，用户自定义的属性暂不支持修改。

(23)

设备组管理

API 说明

查询设备组列表查询物联网平台中的设备组信息列表。

添加设备组新建设备组，一个华为云账号下最多可有1,000个分组，

包括父分组和子分组。

查询设备组查询设备组详情。

修改设备组修改指定设备组。

删除设备组删除指定设备组。

管理设备组中的设备管理设备组中的设备，包括添加设备到设备组和从设备组

删除设备。单个设备组内最多添加20,000个设备。一个设备最多可以被添加到10个设备组中。

查询设备组设备列表查询指定设备组下的设备列表。

标签管理

API 说明

绑定标签为指定资源绑定标签。当前仅支持为设备绑定标签。

解绑标签为指定资源解绑标签。当前仅支持为设备解绑标签。

按标签查询资源查询绑定了指定标签的资源。

资源空间管理

API 说明

查询资源空间列表资源空间对应的是物联网平台原有的应用，在物联网平台

的含义与应用一致，只是变更了名称。应用服务器可以调用此接口查询资源空间列表。

创建资源空间资源空间对应的是物联网平台原有的应用，在物联网平台

的含义与应用一致，只是变更了名称。应用服务器可以调用此接口创建资源空间。

查询资源空间资源空间对应的是物联网平台原有的应用，在物联网平台

的含义与应用一致，只是变更了名称。应用服务器可以调用此接口查询指定资源空间详情。

删除资源空间删除指定资源空间。删除资源空间属于高危操作，删除资

源空间后，该空间下的产品、设备等资源将不可用，请谨慎操作！

(24)

批量任务

API 说明

查询批量任务列表查询物联网平台中批量任务列表，每一个任务又包括具体

的任务内容、任务状态、任务完成情况统计等。

创建批量任务创建批量处理任务，对多个设备进行批量操作。当前仅支

持批量软固件升级。

查询批量任务查询物联网平台中指定批量任务的信息，包括任务内容、

任务状态、任务完成情况统计以及子任务列表等。

查询批量任务文件列表查询批量任务文件列表。

上传批量任务文件上传批量任务文件，用于创建批量任务。当前仅支持批量

创建设备任务文件上传。

删除批量任务文件删除批量任务文件。

设备 CA 证书管理

API 说明

获取设备CA证书列表获取设备的CA证书列表。

上传设备CA证书上传设备的CA证书。

删除设备CA证书删除设备的CA证书。

验证设备CA证书验证设备的CA证书，目的是为了验证用户持有设备CA证

书的私钥。

1.4 产品管理

产品模型定义了该产品下所有设备具备的能力或特征，产品管理为应用服务器提供对物联网平台中产品模型的操作管理功能。

1.4.1 查询产品列表

接口说明

应用服务器可调用此接口查询已导入物联网平台的产品模型信息列表，了解产品模型的概要信息。

调试

您可以在API Explorer中调试该接口。

(25)

URI

请求方法 GET

URI /v5/iot/{project_id}/products 传输协议 HTTPS

请求参数

名称必选/可

选

类型位置说明

X-Auth-

Token 必选 String Head

er 参数说明：用户Token。通过调用 IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中

“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。

Instance-

Id 可选 String Head

er 参数说明：实例ID。物理多租下各实例的唯一标识，一般华为云租户无需携带该参数，仅在物理多租场景下从管理面访问API时需要携带该参数。

project_i

d 必选 String Path 参数说明：项目ID。获取方法请参见获取项目ID。

limit 可选 Integer Quer

y 参数说明：分页查询时每页显示的记录数。

取值范围：1-50的整数，默认值为 10。

marker 可选 String Quer

y 参数说明：上一次分页查询结果中最后一条记录的ID，在上一次分页查询时由物联网平台返回获得。分页查询时物联网平台是按marker 也就是记录ID降序查询的，越新的数据记录ID也会越大。若填写 marker，则本次只查询记录ID小于marker的数据记录。若不填写，则从记录ID最大也就是最新的一条数据开始查询。如果需要依次查询所有数据，则每次查询时必须填写上一次查询响应中的marker 值。

取值范围：长度为24的十六进制字符串，默认值为

ffffffffffffffffffffffff。

(26)

名称必选/可选

类型位置说明

app_id 可选 String Quer

y 参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，可以携带该参数查询指定资源空间下的产品列表，不携带该参数则会查询该用户下所有产品列表。

取值范围：长度不超过36，只允许字母、数字、下划线（_）、连接符（-）的组合。

offset 可选 Integer Quer

y 参数说明：表示从marker后偏移 offset条记录开始查询。当offset为 0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配 marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，

但到11页后，由于offset限制为 500，您需要使用第11页返回的 marker作为下次查询的marker，

以实现翻页到12-22页。

取值范围：0-500的整数，默认为 0。

响应参数

名称类型说明

products List<ProductSu

mmary> 产品信息列表。

page Page Object 查询结果的分页信息。

表1-1 ProductSummary

名称类型说明

app_id String 资源空间ID。

app_name String 资源空间名称。

product_id String 产品ID，用于唯一标识一个产品，在物联网平台创建产品后由平台分配获得。

name String 产品名称。

(27)

名称类型说明 device_type String 设备类型。

protocol_typ

e String 设备使用的协议类型。取值范围：MQTT，

CoAP，HTTP，HTTPS，Modbus，ONVIF，

OPC-UA，OPC-DA，Other。

data_format String 设备上报数据的格式，取值范围：json，

binary。

manufactur

er_name String 厂商名称。

industry String 设备所属行业。

description String 产品的描述信息。

create_time String 在物联网平台创建产品的时间，格式：

yyyyMMdd'T'HHmmss'Z'，如 20151212T121212Z。

表1-2 Page

名称类型说明

count Long 满足查询条件的记录总数。

marker String 本次分页查询结果中最后一条记录的ID，可在下一次分页查询时使用。

请求示例

GET https://{Endpoint}/v5/iot/{project_id}/products?

limit={limit}&marker={marker}&app_id={app_id}&offset={offset}

Content-Type: application/json X-Auth-Token: ********

Instance-Id: ********

响应示例

Status Code: 200 OK

Content-Type: application/json { "products" : [ {

"app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "app_name" : "testAPP01",

"product_id" : "5ba24f5ebbe8f56f5a14f605", "name" : "Thermometer",

"device_type" : "Thermometer", "protocol_type" : "MQTT", "data_format" : "json",

(28)

"create_time" : "20190303T081011Z"

} ], "page" : { "count" : 10,

"marker" : "5c90fa7d3c4e4405e8525079"

}}

错误码

HTTP

状态码错误码错误码英文描述错误码中文描述处理建议 403 IOTDA

.00002 2

Operation not allowed. The user does not have the permission

该用户没有权限请排查该用户是否有权限访问。

IOTDA .00100 6

Operation not allowed.

Application not found by

authorized user or the authorized user has no application.

用户下没有应用或应用与用户不匹配

请排查用户下是否有应用或是否有指定的应用。

IOTDA .00100 7

Operation not allowed. The application does not belong to the authorized user.

应用与用户信息不

匹配请排查该用户下是

否有指定的应用。

1.4.2 创建产品

接口说明

应用服务器可调用此接口创建产品。

调试

您可以在API Explorer中调试该接口。

注意事项

此接口仅创建了产品，没有创建和安装插件，如果需要对数据进行编解码，还需要在平台开发和安装插件。

URI

请求方法 POST

(29)

URI /v5/iot/{project_id}/products 传输协议 HTTPS

请求参数

名称必选/可

选

类型位置说明

X-Auth-

Token 必选 String Head

er 参数说明：用户Token。通过调用 IAM服务获取IAM用户Token接口获取，接口返回的响应消息头中

“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。

Instance-

Id 可选 String Head

er 参数说明：实例ID。物理多租下各实例的唯一标识，一般华为云租户无需携带该参数，仅在物理多租场景下从管理面访问API时需要携带该参数。

project_i

d 必选 String Path 参数说明：项目ID。获取方法请参见获取项目ID。

product_i

d 可选 String Body 参数说明：产品ID，用于唯一标识一个产品。如果携带此参数，平台将产品ID设置为该参数值；如果不携带此参数，产品ID在物联网平台创建产品后由平台分配获得。

name 必选 String Body 参数说明：产品名称。

取值范围：长度不超过64，只允许中文、字母、数字、以及_?'#().,&

%@!-等字符的组合。

device_ty

pe 必选 String Body 参数说明：设备类型。

protocol_

type 必选 String Body 参数说明：设备使用的协议类型。

取值范围：MQTT，CoAP，

HTTP，HTTPS，Modbus，

ONVIF，OPC-UA，OPC-DA，

Other。

(30)

名称必选/可选

类型位置说明

data_for

mat 必选 String Body 参数说明：设备上报数据的格式。

取值范围：

● json：JSON格式

● binary：二进制码流格式默认值json。

service_c apabilitie s

必选 List<ServiceC

apability> Body 参数说明：设备的服务能力列表。

取值范围：数组长度大小不超过 500，内容大小不超过500k。

manufact urer_nam e

可选 String Body 参数说明：厂商名称。

industry 可选 String Body 参数说明：设备所属行业。

descripti

on 可选 String Body 参数说明：产品的描述信息。

取值范围：长度不超过128，只允许中文、字母、数字、空白字符、

以及_?'#().,;&%@!- ，、：；。/

等字符的组合。

app_id 可选 String Body 参数说明：资源空间ID。此参数为非必选参数，存在多资源空间的用户需要使用该接口时，建议携带该参数指定创建的产品归属到哪个资源空间下，否则创建的产品将会归属到默认资源空间下。

表1-3 ServiceCapability

名称必选/可选类型说明

service_id 必选 String 参数说明：设备的服务ID。注：产品内不允许重复。

取值范围：长度不超过32，只允许中文、字母、数字、以及_?'#().,&%@!-

$等字符的组合。

(31)

名称必选/可选类型说明 service_typ

e 必选 String 参数说明：设备的服务类型。

取值范围：长度不超过32，只允许中文、字母、数字、以及_?'#().,&%@!-

$等字符的组合。

properties 可选 List<ServicePr

operty> 参数说明：设备服务支持的属性列表。

取值范围：数组长度大小不超过500。

commands 可选 List<ServiceC

ommand> 参数说明：设备服务支持的命令列表。

events 可选 List<ServiceEv

ent> 参数说明：设备服务支持的事件列表。

description 可选 String 参数说明：设备服务的描述信息。

取值范围：长度不超过128，只允许中文、字母、数字、空白字符、以及 _?'#().,;&%@!- ，、：；。/等字符的组合。

option 可选 String 参数说明：指定设备服务是否必选。目前本字段为非功能性字段，仅起到标识作用。

取值范围：

● Master：主服务

● Mandatory：必选服务

● Optional：可选服务默认值为Optional。

表1-4 ServiceProperty

property_n

ame 必选 String 参数说明：设备属性名称。注：设备服

务内不允许重复。属性名称作为设备影子JSON文档中的key不支持特殊字符：

点(.)、dollar符号($)、空char(十六进制的ASCII码为00)，如果包含了以上特殊字符则无法正常刷新影子文档。

取值范围：长度不超过64，只允许中文、字母、数字、以及_?'#().,&%@!- 等字符的组合。

data_type 必选 String 参数说明：设备属性的数据类型。

取值范围：int，long，decimal，

(32)

required 可选 Boolean 参数说明：设备属性是否必选。默认为 false。

enum_list 可选 List<String> 参数说明：设备属性的枚举值列表。

min 可选 String 参数说明：设备属性的最小值。

取值范围：长度1-16。

max 可选 String 参数说明：设备属性的最大值。

max_lengt

h 可选 Integer 参数说明：设备属性的最大长度。

step 可选 Double 参数说明：设备属性的步长。

unit 可选 String 参数说明：设备属性的单位。

取值范围：长度不超过16。

method 必选 String 参数说明：设备属性的访问模式。

取值范围：RWE，RW，RE，WE，E，

W，R。

● R：属性值可读

● W：属性值可写

● E：属性值可订阅，即属性值变化时上报事件

description 可选 String 参数说明：设备属性的描述。

default_va

lue 可选 Object 参数说明：设备属性的默认值。如果设

置了默认值，使用该产品创建设备时，

会将该属性的默认值写入到该设备的设备影子预期数据中，待设备上线时将该属性默认值下发给设备。

表1-5 ServiceCommand

command

_name 必选 String 参数说明：设备命令名称。注：设备服务内不允许重复。

(33)

名称必选/可选类型说明 paras 可选 List<ServiceC

ommandPara

>

参数说明：设备命令的参数列表。

responses 可选 List<ServiceC ommandResp onse>

参数说明：设备命令的响应列表。

表1-6 ServiceCommandPara

para_nam

e 必选 String 参数说明：参数的名称。

data_type 必选 String 参数说明：参数的数据类型。

取值范围：int，long，decimal，

string，DateTime，jsonObject，

enum，boolean，string list。

required 可选 Boolean 参数说明：参数是否必选。默认为 false。

enum_list 可选 List<String> 参数说明：参数的枚举值列表。

min 可选 String 参数说明：参数的最小值。

max 可选 String 参数说明：参数的最大值。

max_lengt

h 可选 Integer 参数说明：参数的最大长度。

step 可选 Double 参数说明：参数的步长。

unit 可选 String 参数说明：参数的单位。

description 可选 String 参数说明：参数的描述。

(34)

表1-7 ServiceCommandResponse

response_

name 必选 String 参数说明：设备命令响应名称。

paras 可选 List<ServiceC ommandPara

>

参数说明：设备命令响应的参数列表。

表1-8 ServiceEvent

event_type 必选 String 参数说明：设备事件类型。注：设备服务内不允许重复。

paras 可选 List<ServiceC ommandPara

>

参数说明：设备事件的参数列表。

响应参数

名称类型说明

app_id String 资源空间ID。

app_name String 资源空间名称。

product_id String 产品ID，用于唯一标识一个产品，在物联网平台创建产品后由平台分配获得。

name String 产品名称。

device_type String 设备类型。

protocol_typ

e String 设备使用的协议类型。取值范围：MQTT，

CoAP，HTTP，HTTPS，Modbus，ONVIF，

OPC-UA，OPC-DA，Other。

data_format String 设备上报数据的格式，取值范围：json，

binary。

manufactur

er_name String 厂商名称。

(35)

名称类型说明

industry String 设备所属行业。

description String 产品的描述信息。

service_capa

bilities List<ServiceCa

pability> 设备的服务能力列表。

create_time String 在物联网平台创建产品的时间，格式：

yyyyMMdd'T'HHmmss'Z'，如 20151212T121212Z。

表1-9 ServiceCapability

名称类型说明

service_id String 参数说明：设备的服务ID。注：产品内不允许重复。

取值范围：长度不超过32，只允许中文、字母、

数字、以及_?'#().,&%@!-$等字符的组合。

service_type String 参数说明：设备的服务类型。

数字、以及_?'#().,&%@!-$等字符的组合。

properties List<ServicePro

perty> 参数说明：设备服务支持的属性列表。

commands List<ServiceCo

mmand> 参数说明：设备服务支持的命令列表。

events List<ServiceEve

nt> 参数说明：设备服务支持的事件列表。

description String 参数说明：设备服务的描述信息。

取值范围：长度不超过128，只允许中文、字母、数字、空白字符、以及_?'#().,;&

%@!- ，、：；。/等字符的组合。

option String 参数说明：指定设备服务是否必选。目前本字段为非功能性字段，仅起到标识作用。

取值范围：

● Master：主服务

● Mandatory：必选服务

● Optional：可选服务默认值为Optional。

(36)

表1-10 ServiceProperty

名称类型说明

property_na

me String 参数说明：设备属性名称。注：设备服务内不允

许重复。属性名称作为设备影子JSON文档中的 key不支持特殊字符：点(.)、dollar符号($)、空 char(十六进制的ASCII码为00)，如果包含了以上特殊字符则无法正常刷新影子文档。

数字、以及_?'#().,&%@!-等字符的组合。

data_type String 参数说明：设备属性的数据类型。

取值范围：int，long，decimal，string，

DateTime，jsonObject，enum，boolean，

string list。

required Boolean 参数说明：设备属性是否必选。默认为false。

enum_list List<String> 参数说明：设备属性的枚举值列表。

min String 参数说明：设备属性的最小值。

max String 参数说明：设备属性的最大值。

max_length Integer 参数说明：设备属性的最大长度。

step Double 参数说明：设备属性的步长。

unit String 参数说明：设备属性的单位。

method String 参数说明：设备属性的访问模式。

取值范围：RWE，RW，RE，WE，E，W，R。

● R：属性值可读

● W：属性值可写

● E：属性值可订阅，即属性值变化时上报事件 description String 参数说明：设备属性的描述。

%@!- ，、：；。/等字符的组合。

default_valu

e Object 参数说明：设备属性的默认值。如果设置了默认

值，使用该产品创建设备时，会将该属性的默认值写入到该设备的设备影子预期数据中，待设备上线时将该属性默认值下发给设备。

(37)

表1-11 ServiceCommand

名称类型说明

command_n

ame String 参数说明：设备命令名称。注：设备服务内不允许重复。

paras List<ServiceCo

mmandPara> 参数说明：设备命令的参数列表。

responses List<ServiceCo mmandRespon se>

参数说明：设备命令的响应列表。

表1-12 ServiceCommandPara

名称类型说明

para_name String 参数说明：参数的名称。

data_type String 参数说明：参数的数据类型。

取值范围：int，long，decimal，string，

DateTime，jsonObject，enum，boolean，

string list。

required Boolean 参数说明：参数是否必选。默认为false。

enum_list List<String> 参数说明：参数的枚举值列表。

min String 参数说明：参数的最小值。

max String 参数说明：参数的最大值。

max_length Integer 参数说明：参数的最大长度。

step Double 参数说明：参数的步长。

unit String 参数说明：参数的单位。

description String 参数说明：参数的描述。

%@!- ，、：；。/等字符的组合。

(38)

表1-13 ServiceCommandResponse

名称类型说明

response_na

me String 参数说明：设备命令响应名称。

取值范围：长度不超过128，只允许中文、字母、数字、以及_?'#().,&%@!-等字符的组合。

mmandPara> 参数说明：设备命令响应的参数列表。

表1-14 ServiceEvent

名称类型说明

event_type String 参数说明：设备事件类型。注：设备服务内不允许重复。

mmandPara> 参数说明：设备事件的参数列表。

请求示例

POST https://{Endpoint}/v5/iot/{project_id}/products Content-Type: application/json

X-Auth-Token: ********

Instance-Id: ********

{ "product_id" : "5ba24f5ebbe8f56f5a14f605", "name" : "Thermometer",

"device_type" : "Thermometer", "protocol_type" : "MQTT", "data_format" : "json", "service_capabilities" : [ { "service_type" : "temperature", "service_id" : "temperature", "description" : "temperature", "properties" : [ {

"unit" : "centigrade", "min" : "1",

"method" : "RW", "max" : "100",

"data_type" : "decimal", "description" : "force", "step" : 0.1,

"default_value" : { "color" : "red", "size" : 1 },

"enum_list" : [ "string" ], "required" : true,

"property_name" : "temperature", "max_length" : 100

} ],

"commands" : [ {

"command_name" : "reboot",

(39)

"responses" : [ {

} ], "paras" : [ { "unit" : "km/h", "min" : "1", "max" : "100", "para_name" : "force", "data_type" : "string", "description" : "force", "step" : 0.1,

} ],

"events" : [ {

"event_type" : "reboot", "paras" : [ {

} ],

"option" : "Mandatory"

} ],

"manufacturer_name" : "ABC", "industry" : "smartCity",

"description" : "this is a thermometer produced by Huawei", "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka"

}

响应示例

Status Code: 201 Created

Content-Type: application/json

{ "app_id" : "jeQDJQZltU8iKgFFoW060F5SGZka", "app_name" : "testAPP01",

"product_id" : "5ba24f5ebbe8f56f5a14f605", "name" : "Thermometer",

"device_type" : "Thermometer", "protocol_type" : "MQTT", "data_format" : "json", "manufacturer_name" : "ABC",

(40)

"service_id" : "temperature", "service_type" : "temperature", "properties" : [ {

"property_name" : "temperature", "required" : true,

"data_type" : "decimal", "min" : "1",

"max" : "100", "max_length" : 100, "step" : 0.1, "unit" : "centigrade", "method" : "RW", "description" : "force", "default_value" : { "color" : "red", "size" : 1 }

} ],

"commands" : [ {

"command_name" : "reboot", "paras" : [ {

"para_name" : "force", "required" : false, "data_type" : "string", "min" : "1",

"max" : "100", "max_length" : 100, "step" : 0.1, "unit" : "km/h", "description" : "force"

} ],

"responses" : [ {

} ] } ] } ],

"events" : [ {

"event_type" : "reboot", "paras" : [ {

} ] } ],

"description" : "temperature", "option" : "Mandatory"

} ],

"create_time" : "20190303T081011Z"

}

(41)

错误码

HTTP 状态码

错误码错误码英文描述错误码中文描述处理建议

400 IOTDA .01300 5

The productName has been used in the same

application.

该应用下产品名已被使用

请更换产品名重新操作。

IOTDA .01301 0

Invalid input. The content in product service capability is duplicated, please check %s

产品模型内容定义

重复，请检查产品模型内容有重

复的命名信息

IOTDA .01301 2

Invalid input. The size of product profile content has reach or exceed

%s.

产品模型内容大小超过

请将定义的产品模型内容限制在指定范围内。

IOTDA .01403 4

Invalid input. The serviceId or eventType do not match.

serviceId或

eventType不匹配请检查请求参数 serviceId与 eventType是否与 profile中定义的相同。

403 IOTDA .00002 2

Operation not allowed. The user does not have the permission

该用户没有权限请排查该用户是否有权限访问。

IOTDA .00100 5

Operation not allowed. The parameter 'app_id' is not carried, and the authorized user has more than one applications.

Include the

parameter 'app_id', or contact Huawei technical support engineers to merge application data.

该用户下有多个应用的情况下未携带 appId访问接口

请携带对应的appId 或联系华为工程师合并应用数据。

接口演进指导_设备接入 IoTDA_API参考_历史API_华为云

API 参考

目 录

1 应用侧 API 参考...1

2 设备侧 MQTT 接口参考... 496

3 设备侧 HTTP/HTTPS 接口参考... 548

4 模组 AT 指令参考...561

5 应用示例... 566

6 设备发放 API 参考... 577

7 历史 API... 585

8 修订记录... 991

1 应用侧 API 参考

1.1 使用前必读

概述

角色说明

调用说明

使用限制

1.2 如何调用 API

1.2.1 构造请求

请求 URI

请求方法

请求消息头

请求消息体

name

device_type

protocol_type

1.2.2 认证鉴权

Token 认证

AK/SK 认证

1.2.3 返回结果

状态码

响应消息头

响应消息体

1.3 API 列表

产品管理

设备管理

设备消息

设备命令

设备属性

AMQP 队列管理

接入凭证管理

数据流转规则管理

流转数据

设备联动规则

设备影子

设备组管理

标签管理

资源空间管理

批量任务

设备 CA 证书管理

1.4 产品管理

1.4.1 查询产品列表

接口说明

调试

URI

请求参数

响应参数

请求示例

响应示例

错误码

1.4.2 创建产品

接口说明

调试

注意事项

URI

请求参数

响应参数

请求示例

响应示例

错误码

目录