Help Center> IoT Device Access> API Reference> 历史API> 接口演进指导> 应用侧接口差异说明
View PDF

应用侧接口差异说明

本章节为物联网平台应用侧API新版本和老版本的差异说明，包括请求访问地址、鉴权方式、证书资源、错误响应和API能力等差异。

老版本（即V3版本）应用侧API指应用侧API参考，新版本（即V5版本）应用侧API指应用侧API参考。

请求访问地址

v3版本接口请求访问地址

v5版本请求访问地址

差异说明

“host:port”：承载REST服务端点的服务器地址，格式为“host:port”，其中host为服务器的访问域名或IP，port为服务器的访问端口。

您可以参考平台对接信息获取应用的接入地址和端口信息。

例如设备管理服务在“华北-北京四”区域的应用对接地址为“iot-api.cn-north-4.myhuaweicloud.com”，端口为“8743”，所以Endpoint为“iot-api.cn-north-4.myhuaweicloud.com:8743”。

“Endpoint”：指定承载REST服务端点的服务器域名或IP，不同服务不同区域的Endpoint不同，您可以从地区和终端节点中获取。

例如设备管理服务在“华北-北京四”区域的Endpoint为“iotda.cn-north-4.myhuaweicloud.com”。

请求访问地址由物联网平台定义的域名或IP加端口的形式，变更为华为云统一的终端节点形式，变更后只有域名没有端口。

v3版本样例：

POST https://iot-api.cn-north-4.myhuaweicloud.com:8743/iocm/app/sec/v1.1.0/login

v5版本样例：

POST https://iotda.cn-north-4.myhuaweicloud.com/v3/auth/tokens

鉴权方式

v3版本鉴权接口

v5版本鉴权接口

差异说明

POST https://{host}:{port}/iocm/app/sec/v1.1.0/login

详见鉴权

POST https://{Endpoint}/v3/auth/tokens

详见IAM认证鉴权
  1. 鉴权方式变更，由物联网平台特有的应用鉴权变为华为云统一的IAM Token鉴权；
  2. v3版本鉴权接口仅与v3版本API配合使用，v5版本鉴权接口仅与v5版本API配合使用，不能在调用v5版本API时使用v3版本鉴权，或者在调用v3版本API时使用v5版本鉴权；
  3. v3版本鉴权时使用的是物联网平台的应用ID和secret，鉴权通过后可以访问该应用下所有资源；v5版本鉴权时使用的是华为云的账号名、用户名、密码，鉴权通过后可以访问该华为云账号下的所有资源。

证书资源

v3版本证书

v5版本证书

差异说明

访问应用侧API时需要加载证书，详见获取证书章节

无
  1. 访问v3版本应用侧API时需要加载物联网平台提供的特定证书，访问v5版本时不需要证书；
  2. v5版本应用侧API的访问协议跟v3版本一样也是https，v5版本使用华为云统一域名，仅开启单向认证。

授权方式

v3版本授权

v5版本授权

差异说明

可以通过应用授权，访问授权应用下的资源

暂不支持
  1. v3版本API中可以携带授权应用ID，用以访问授权应用下的设备、数据等资源；
  2. v5版本API由于采用IAM鉴权，也就是用户鉴权，鉴权通过后用户可以访问该用户下所有应用的资源，暂时不支持跨用户的应用授权。

分页查询方式

v3版本分页查询

v5版本分页查询

差异说明

请求参数：

pageNo——分页查询参数，查询结果分页显示时指定要查看的页信息，默认值0，查询第一页，取值范围为大于等于0的整数。）

pageSize——分页查询参数，查询结果分页显示时每页显示的记录数，默认值为1，取值范围为1-500的整数。

响应参数：

totalCount——查询结果的总记录数。

pageNo——查询结果页码。

pageSize——查询结果每页的记录数量。

请求参数：

limit——分页查询时每页显示的记录数，默认值为10，取值范围为1-50的整数。

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

offset——表示从marker后偏移offset条记录开始查询。默认为0，取值范围为0-500的整数。当offset为0时，表示从marker后第一条记录开始输出。限制offset最大值是出于API性能考虑，您可以搭配marker使用该参数实现翻页，例如每页50条记录，1-11页内都可以直接使用offset跳转到指定页，但到11页后，由于offset限制为500，您需要使用第11页返回的marker作为下次查询的marker，以实现翻页到12-22页。

响应参数：

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

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

v3版本分页在请求中直接传入页码和每页大小，根据返回的总记录数不断递增页码查询到所有记录即可；

v5版本分页在请求中传入的是起始位置、偏移量和每页大小，需要三个参数配合使用查询到所有记录。

例如：符合条件的数据有1000条，应用侧分页时需要每页50条数据。首次查询时，您可以携带limit=50，不携带marker、offset参数来查询，这时会返回第一页50条数据和符合条件的数据总量1000，您可以直接呈现这50条数据、数据总量，并根据您的分页大小50和数据总量1000计算出总的页码为20。接下来如果需要直接从第1页跳转至第5页，可以计算出偏移量为200，您需要设置limit=50，offset=200，可以不携带marker参数来查询，这时会返回第5页的50条数据。当您需要直接跳转至第11页时，偏移量为500，offset设置为500即可。当您需要跳转至12-20页时，由于offset上限为500，您需要先获取第11页数据返回的marker，查询第12页数据时以刚才获取到的marker为起始值查询，后续配合offset继续实现向后翻页。

接口风格

v3版本接口风格

v5版本接口风格

差异说明

接口url定义不统一，一般按微服务名开头定义，接口header、path、query、body参数均采用小驼峰定义。

接口url定义统一，格式：method /v5/iot/{project_id}/{资源名}；

接口header参数采用大驼峰加“-”连接符定义，例如：“X-Auth-Token”；

接口path、query和body参数采用全小写加“_”连接符定义，例如：“project_id”、“device_id”

v3版本接口风格不统一，v5版本接口完全遵循华为云统一规范设计，使用时能获得和华为云其它服务API一致的体验。

错误响应

v3版本错误响应

v5版本错误响应

差异说明

响应示例：

Status Code: 400 Bad Request
Content-Type: application/json

{
    "error_code": "100208",
    "error_desc": "AppId or secret is not right."
}

响应示例：

Status Code: 400 Bad Request
Content-Type: application/json

{
    "error_code": "IOTDA.000006",
    "error_msg": "Invalid input data."
}
  1. v3版本错误响应存在部分接口响应格式不统一，HTTP状态码为200的情况；v5版本错误响应格式统一，HTTP状态码均为4xx、5xx；
  2. v3版本错误响应中的错误码（error_code字段）为6位10进制数格式，v5版本错误响应中的错误码（error_code字段）格式为：“服务短名”+“.”+“6位10进制数”，其中设备管理的服务短名为“IOTDA”；
  3. v3版本错误响应中的错误描述为error_desc字段，v5版本错误响应中的错误描述为error_msg字段。

API能力

功能

v3版本

v5版本

差异说明

鉴权

POST /iocm/app/sec/v1.1.0/login

POST /v3/auth/tokens
  1. 鉴权方式变更，由物联网平台特有的应用

    鉴权变为华为云统一的IAM Token鉴权；

  2. v3版本鉴权接口仅与v3版本API配合使用，v5版本鉴权接口仅与v5版本API配合使用，不能在调用v5版本API时使用v3版本鉴权，或者在调用v3版本API时使用v5版本鉴权；
  3. v3版本鉴权时使用的是物联网平台的应用ID和secret，鉴权通过后可以访问该应用下所有资源；v5版本鉴权时使用的是华为云的账号名、用户名、密码，鉴权通过后可以访问该华为云账号下的所有资源。

刷新token

POST /iocm/app/sec/v1.1.0/refreshToken

无

v5版本鉴权能力由华为云IAM服务提供，无刷新token能力

查询订阅列表

GET /iocm/app/sub/v1.2.0/subscriptions

GET /v5/iot/{project_id}/subscriptions

1、v5版本分页方式变更，具体参考分页查询方式

2、v5版本新增支持按回调地址和协议类型查询

创建订阅

订阅平台业务数据：

POST /iocm/app/sub/v1.2.0/subscriptions

订阅平台管理数据：

POST /iodm/app/sub/v1.1.0/subscribe

POST /v5/iot/{project_id}/subscriptions

1、v3版本分为订阅平台业务数据和订阅平台管理数据，v5版本合一了；

2、v3版本订阅的通知类型为一个string参数，v5版本变更为一个结构体，结构体中将通知类型区分为资源和事件，资源加事件组合为一个类型；

3、v5版本新增了推送协议通道的参数；

4、v5版本删减了部分不再使用的通知类型，如果您发现缺少需要的订阅类型，请联系华为技术支持咨询

查询订阅

GET /iocm/app/sub/v1.2.0/subscriptions/{subscriptionId}

GET /v5/iot/{project_id}/subscriptions/{subscription_id}

功能无区别，参数上有差异

修改订阅

无

PUT /v5/iot/{project_id}/subscriptions/{subscription_id}

v5版本新增API，提供修改订阅的能力

删除订阅

DELETE /iocm/app/sub/v1.2.0/subscriptions/{subscriptionId}

DELETE /v5/iot/{project_id}/subscriptions/{subscription_id}

功能无区别，参数上有差异

批量删除订阅

DELETE /iocm/app/sub/v1.2.0/subscriptions

无

v5版本暂不单独提供该能力，后续考虑再批量任务接口中提供该能力

推送通知

POST xxx，其中xxx指应用服务器的URL，由应用服务器订阅请求消息中的回调地址决定

POST xxx,其中xxx指应用服务器的URL，由应用服务器订阅请求消息中的回调地址决定

v5版本删减了部分不再使用的通知类型，如果您发现缺少需要的订阅类型，请联系华为技术支持咨询

绑定标签

无

POST /v5/iot/{project_id}/tags/bind-resource

v5版本新增API，提供绑定标签到设备的能力

解绑标签

无

POST /v5/iot/{project_id}/tags/unbind-resource

v5版本新增API，提供给设备解绑标签的能力

按资源查询标签

无

POST /v5/iot/{project_id}/tags/query-resources

v5版本新增API，提供按标签查询设备的能力

查询批量任务列表

无

GET /v5/iot/{project_id}/batchtasks

v5版本新增API，提供查询批量任务列表的能力

创建批量任务

POST /iocm/app/batchtask/v1.1.0/tasks

POST /v5/iot/{project_id}/batchtasks

v3版本仅支持命令，v5版本仅支持软固件升级

查询批量任务

GET /iocm/app/batchtask/v1.1.0/tasks/{taskId}

GET /v5/iot/{project_id}/batchtasks/{taskId}

v3版本仅支持命令，v5版本仅支持软固件升级

查询批量任务的子任务信息

GET /iocm/app/batchtask/v1.1.0/taskDetails

GET /v5/iot/{project_id}/batchtasks/{taskId}

v3版本仅支持命令，v5版本仅支持软固件升级

获取设备CA证书列表

无

GET /v5/iot/{project_id}/certificates

v5版本新增API，提供获取设备的CA证书列表的能力

上传设备CA证书

无

POST /v5/iot/{project_id}/certificates

v5版本新增API，提供上传设备的CA证书的能力

删除设备CA证书

无

DELETE /v5/iot/{project_id}/certificates/{certificate_id}

v5版本新增API，提供删除设备的CA证书的能力

验证设备CA证书

无

POST /v5/iot/{project_id}/certificates/{certificate_id}/action

v5版本新增API，提供验证设备的CA证书的能力

查询设备组列表

GET /iocm/app/devgroup/v1.3.0/devGroups

GET /v5/iot/{project_id}/device-group

v5版本分页方式变更，具体参考分页查询方式

添加设备组

POST /iocm/app/devgroup/v1.3.0/devGroups

POST /v5/iot/{project_id}/device-group

1、v3版本可以设置设备组最大设备数，v5版本不能设置，统一为20000；

2、v3版本可以在创建设备组的同时添加设备到设备组中，v5版本不能，v5版本只能在创建设备组后再添加设备到设备组；

查询设备组

GET /iocm/app/devgroup/v1.3.0/devGroups/{devGroupId}

GET /v5/iot/{project_id}/device-group/{group_id}

功能无区别，参数上有差异

修改设备组

PUT /iocm/app/devgroup/v1.3.0/devGroups/{devGroupId}

PUT /v5/iot/{project_id}/device-group/{group_id}

v3版本可以修改设备组最大设备数，v5版本不能设置，统一为20000

删除设备组

DELETE /iocm/app/devgroup/v1.3.0/devGroups/{devGroupId}

DELETE /v5/iot/{project_id}/device-group/{group_id}

功能无区别，参数上有差异

管理设备组中的设备

增加设备组成员：POST /iocm/app/dm/v1.1.0/devices/addDevGroupTagToDevices

删除设备组成员：POST /iocm/app/dm/v1.1.0/devices/deleteDevGroupTagFromDevices

POST /v5/iot/{project_id}/device-group/{group_id}/action

1、v3版本添加设备到设备组和从设备组删除设备是两个接口，v5版本合并为一个接口；

2、v3版本可以一次添加或删除设备组中的多个设备，v5版本只能单个添加或删除，批量添加或删除的能力将在批量接口中提供

查询设备组设备列表

GET /iocm/app/dm/v1.2.0/devices/ids

GET /v5/iot/{project_id}/device-group/{group_id}/devices

v5版本分页方式变更，具体参考分页查询方式

查询设备消息

无

GET /v5/iot/{project_id}/devices/{device_id}/messages

v5版本新增API，物联网平台可查询指定设备下的消息，平台为每个设备默认最多保存20条消息，超过20条后， 后续的消息会替换下发最早的消息。

下发设备消息

无

POST /v5/iot/{project_id}/devices/{device_id}/messages

v5版本新增API，物联网平台可向设备下发消息，应用服务器可调用此接口向指定设备下发消息，以实现对设备的控制。应用将消息下发给平台后，平台返回应用响应结果，平台再将消息发送给设备。

查询指定消息id的消息

无

GET /v5/iot/{project_id}/devices/{device_id}/messages/{message_id}

v5版本新增API，物联网平台可查询指定消息id的消息。

查询产品列表

无

GET /v5/iot/{project_id}/products

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

创建产品

无

POST /v5/iot/{project_id}/products

v5版本新增API，应用服务器可调用此接口创建产品。此接口仅创建了产品，没有创建和安装插件，如果需要对数据进行编解码，还需要在平台开发和安装插件。

查询产品

无

GET /v5/iot/{project_id}/products/{product_id}

v5版本新增API，应用服务器可调用此接口查询已导入物联网平台的指定产品模型详细信息，包括产品模型的服务、属性、命令等。

修改产品

无

PUT /v5/iot/{project_id}/products/{product_id}

v5版本新增API，应用服务器可调用此接口修改已导入物联网平台的指定产品模型，包括产品模型的服务、属性、命令等。此接口仅修改了产品，未修改和安装插件，如果修改了产品中的service定义，且在平台中有对应的插件，请修改并重新安装插件。

删除产品

无

DELETE /v5/iot/{project_id}/products/{product_id}

v5版本新增API，应用服务器可调用此接口删除已导入物联网平台的指定产品模型。此接口仅删除了产品，未删除关联的插件，在产品下存在设备时，该产品不允许删除。

查询设备列表

GET /iocm/app/dm/v1.4.0/devices

GET /v5/iot/{project_id}/devices

v5版本分页方式变更，具体参考分页查询方式

注册设备

注册设备（验证码方式）：

POST /iocm/app/reg/v1.1.0/deviceCredentials

注册设备（密码方式）：

POST /iocm/app/reg/v2.0.0/deviceCredentials

POST /v5/iot/{project_id}/devices

1、v3版本注册设备接口区分了验证码方式、密码方式、注册设备、注册子设备，在v5版本注册设备中，注册直连设备和子设备在同一个接口就可以完成，验证码方式和密码方式统一为密钥认证方式，同时新增证书认证方式，这些都在注册设备这同一个接口中支持；

2、v3版本会校验设备识别码全局唯一，设备ID由平台生成一个全局唯一的ID；v5版本设备ID由产品ID和设备识别码拼接组成，会校验拼装后的设备ID全局唯一。

查询设备

GET /iocm/app/dm/v1.4.0/devices/{deviceId}

GET /v5/iot/{project_id}/devices/{device_id}

v3版本支持按设备识别码查询，v5版本不再支持

修改设备

PUT /iocm/app/dm/v1.4.0/devices/{deviceId}

PUT /v5/iot/{project_id}/devices/{device_id}

v3版本支持修改所属产品、标签，v5版本不再支持

删除设备

DELETE /iocm/app/dm/v1.4.0/devices/{deviceId}

DELETE /v5/iot/{project_id}/devices/{device_id}

v3版本支持删除直连设备和其下的非直连设备，v5版本不再支持

删除子设备

POST /iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand

DELETE /v5/iot/{project_id}/devices/{device_id}

v3版本单独区分了删除子设备，v5版本不再区分，只要该子设备下没有其它子设备，就可以直接调用删除设备接口删除子设备

查询设备激活状态

GET /iocm/app/reg/v1.1.0/deviceCredentials/{deviceId}

无

v5版本不单独提供该能力，在查询设备API返回的设备状态中INACTIVE为未激活，FREEZED为冻结，其它状态均属于激活状态，可以取代该接口

重置设备密钥

PUT /iocm/app/reg/v1.1.0/deviceCredentials/{deviceId}

POST /v5/iot/{project_id}/devices/{device_id}/action

v3版本可以刷新设备的唯一标识码和超时时间，v5版本不再支持

查询设备影子数据

GET /iocm/app/shadow/v1.5.0/devices/{deviceId}

GET /v5/iot/{project_id}/devices/{device_id}/shadow

v5版本相比v3版本在响应中删除了除预期数据和上报数据外的其它冗余信息

配置设备影子预期数据

PUT /iocm/app/shadow/v1.5.0/devices/{deviceId}

PUT /v5/iot/{project_id}/devices/{device_id}/shadow

v5版本相比v3版本新增了预期数据的版本信息

注册LoRa网关

POST /api/v3.0/devices/lora/gateway

无

v5版本API暂不提供该能力

注册LoRa节点

POST /api/v3.0/devices/lora/node

无

v5版本API暂不提供该能力

查询单个LoRa网关信息

GET /api/v3.0/devices/lora/gateway/{deviceId}

无

v5版本API暂不提供该能力

删除LoRa网关

DELETE /api/v3.0/devices/lora/gateway/{deviceId}

无

v5版本API暂不提供该能力

查询单个LoRa节点信息

GET /api/v3.0/devices/lora/node/{deviceId}

无

v5版本API暂不提供该能力

删除LoRa节点

DELETE /api/v3.0/devices/lora/node/{deviceId}

无

v5版本API暂不提供该能力

查询设备历史数据

GET /iocm/app/data/v1.2.0/deviceDataHistory

无

v5版本API暂不提供该能力

查询设备影子历史数据

GET /iocm/app/shadow/v1.5.0/deviceDesiredHistory

无

v5版本API暂不提供该能力

查询设备服务能力

GET /iocm/app/data/v1.1.0/deviceCapabilities

无

v5版本API暂不提供该能力

下发设备命令

POST /iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand

POST /v5/iot/{project_id}/devices/{device_id}/commands

v3版本是异步命令，v5版本按照物模型定义为同步命令。注：v3版本的method参数是必选，在v5版本对应的参数commandName为可选。如果使用v5版本的接口给v3版本设备下发命令，该参数必选。

创建设备命令

POST /iocm/app/cmd/v1.4.0/deviceCommands

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

查询设备命令

GET /iocm/app/cmd/v1.4.0/deviceCommands

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

修改设备命令

PUT /iocm/app/cmd/v1.4.0/deviceCommands/{deviceCommandId}

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

批量创建设备命令

POST /iocm/app/batchtask/v1.1.0/tasks

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

创建设备命令撤销任务

POST /iocm/app/cmd/v1.4.0/deviceCommandCancelTasks

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

查询设备命令撤销命令

GET /iocm/app/cmd/v1.4.0/deviceCommandCancelTasks

无

v3版本API为异步命令，v5版本按照物模型定义命令为同步，暂不提供该能力，v5版本提供设备消息、属性、事件等替代该能力。

查询设备属性

无

GET /v5/iot/{project_id}/devices/{device_id}/properties

v5版本新增API，设备的产品模型中定义了物联网平台可向设备下发的属性，应用服务器可调用此接口查询指定设备下属性。

修改设备属性

无

PUT /v5/iot/{project_id}/devices/{device_id}/properties

v5版本新增API，设备的产品模型中定义了物联网平台可向设备下发的属性，应用服务器可调用此接口向指定设备下属性。平台负责将属性以同步方式发送给设备，并将设备执行属性结果同步返回。

查询规则列表

无

GET /v5/iot/{project_id}/rules

v5版本新增API，应用服务器可调用此接口查询物联网平台中设置的规则列表。

创建规则

无

POST /v5/iot/{project_id}/rules

v5版本新增API，应用服务器可调用此接口在物联网平台创建一条规则，当指定设备上报的数据满足条件时，触发规则。

查询规则

无

GET /v5/iot/{project_id}/rules/{rule_id}

v5版本新增API，应用服务器可调用此接口查询物联网平台中指定规则的配置信息。

修改规则

无

PUT /v5/iot/{project_id}/rules/{rule_id}

v5版本新增API，应用服务器可调用此接口修改物联网平台中指定规则的配置。

删除规则

无

DELETE /v5/iot/{project_id}/rules/{rule_id}

v5版本新增API，应用服务器可调用此接口删除物联网平台中的指定规则。

修改规则状态

无

PUT /v5/iot/{project_id}/rules/{rule_id}/status

v5版本新增API，应用服务器可调用此接口修改物联网平台中指定规则的状态，激活或者去激活规则。
父主题： 接口演进指导