使用前必读

概述

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

调用说明

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

终端节点

终端节点（Endpoint）即调用API的请求地址，物联网平台的Endpoint请参见：平台对接信息中的接入地址。

约束与限制

• API的演进会保持前向兼容性，若接口升级了版本，其旧版本接口可以继续使用，但功能不再做增强，新增功能仅在新版本接口中提供。
• 应用在接收处理物联网平台发送的响应消息和推送消息时，需要兼容或忽略消息中的新增参数，不能因为消息中的新增参数导致应用的处理异常。
• 调用API的其他使用限制，请参见物联网平台的使用限制。

基本概念

• 账号

  用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

• 用户

  由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。

  在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。

• 区域（Region）

  从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。

  详情请参见区域和可用区。

• 可用区（AZ，Availability Zone）

  一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

• 项目

  华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

  图1 项目隔离模型
  
• 企业项目

  企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理服务用户指南》。

• 资源空间

  指在物联网平台中为您的业务划分的一个资源空间，您在平台中创建的资源（如产品、设备等）都需要归属到某个资源空间，您可以基于资源空间实现多业务应用的分域管理。详情请参见资源空间。

• 产品

  产品模型用于描述设备具备的能力和特性。开发者通过定义产品模型，在物联网平台构建一款设备的抽象模型。详情请参见什么是产品模型。

• 消息下发

  消息下发不依赖产品模型，提供给设备的单向通知，具有消息缓存功能；详情请参见消息下发概述。

• 命令下发

  为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可以调用物联网平台应用侧API接口向设备下发命令，以实现对设备的远程控制。详情请参见命令下发概述。

• 属性下发

  属性下发分为查询设备属性和修改属性参数两种，查询设备属性用于应用侧或平台主动获取设备属性数据，修改属性参数用于应用侧或平台设置设备属性值并同步到设备侧。详情请参见属性下发概述。

• AMQP队列管理

  AMQP（Advanced Message Queuing Protocol）即高级队列消息协议。用户可通过AMQP的客户端与IoT平台建立链接，来接收平台推送数据。详情请参见AMQP订阅推送。

• 数据流转

  设备接入到物联网平台后，便可与物联网平台进行通信。设备通过自定义Topic或产品模型方式将数据上报到平台，在控制台设置后，通过订阅推送的方式，将设备生命周期变更、设备属性上报、设备消息上报、设备消息状态变更、设备状态变更、批量任务状态变更等消息推送到您指定的服务器。详情请参见订阅推送方式概述。

• 设备影子

  物联网平台支持创建设备的“影子”。设备影子是一个JSON文件，用于存储设备的在线状态、设备最近一次上报的设备属性值、应用服务器期望下发的配置。每个设备有且只有一个设备影子，设备可以获取和设置设备影子以此来同步设备属性值，这个同步可以是影子同步给设备，也可以是设备同步给影子。详情请参见设备影子。

• 设备组（群组）

  群组是一系列设备的集合，用户可以对资源空间下所有设备，根据区域、类型等不同规则进行分类建立群组，以便处理对海量设备的批量操作。例如，对资源空间下所有水表设备的群组进行固件升级。平台支持群组的增删改查操作，支持给群组绑定和解绑设备，支持一个设备被添加到多个群组中。详情请参见群组。

• 标签

  对于拥有大量云资源的用户，可以通过给云资源打标签，快速查找具有某标签的云资源，可对这些资源标签统一进行检视、修改、删除等操作，方便用户对云资源的管理。详情请参见标签概述。

• 联动规则

  联动规则分为端侧规则和云端规则。端侧规则：端侧规则是指用户在云平台创建的设备联动规则，可以下发到端侧设备，该设备上会运行端侧规则引擎，对云端下发的规则进行解析并执行。端侧规则可以在网络中断或设备无法与云端交互情况下，继续在端侧执行指定规则。云端规则：当用户设置云端规则时，物联网平台会判断是否满足规则触发条件，在条件满足时，平台会执行用户预设的动作。比如：事件告警、主题通知、设备命令下发等。详情请参见云端规则。

• 批量任务

  当需要对多个设备进行批量操作时，可以选择批量任务执行该操作。当前支持批量软固件升级、批量创建设备、批量修改设备、批量删除设备、批量冻结设备、批量解冻设备、批量创建命令、批量创建消息、批量配置设备影子和批量更新设备任务。

• OTA升级

  OTA升级指的是软固件升级，软件升级指升级设备的系统软件和应用软件，固件升级指升级设备硬件的底层“驱动程序”。升级方式均为将软/固件包上传到物联网平台或者关联用户OBS上的对象，设备从物联网平台或用户OBS获取软/固件包实现远程升级。详情请参见OTA升级相关问题。