# 使用前必读 #### 概述 物联网平台把自身丰富的管理能力通过API的形式对外开放，包括产品管理、设备管理、设备组管理、标签管理、设备CA证书管理、设备影子、设备命令、设备消息、设备属性、订阅管理、规则管理、批量任务等，帮助用户快速构筑基于物联网平台的行业应用。您可以根据本文档提供的API来使用物联网平台的服务，平台支持的全部API请参见[API](https://support.huaweicloud.com/api-iothub/iot_06_v5_0200.html)。 #### 调用说明 物联网平台提供了RESTful（Representational State Transfer）风格API，支持您通过HTTPS请求调用，调用方法请参见[如何调用API](https://support.huaweicloud.com/api-iothub/iot_06_v5_0004.html)。 #### 终端节点 终端节点（Endpoint）即调用API的请求地址，物联网平台的Endpoint请参见：[如何获取平台接入地址](https://support.huaweicloud.com/iothub_faq/iot_faq_00123.html)。 #### 约束与限制 - API的演进会保持前向兼容性，若接口升级了版本，其旧版本接口可以继续使用，但功能不再做增强，新增功能仅在新版本接口中提供。 - 应用在接收处理物联网平台发送的响应消息和推送消息时，需要兼容或忽略消息中的新增参数，不能因为消息中的新增参数导致应用的处理异常。 - 调用API的其他使用限制，请参见物联网平台的[使用限制](https://support.huaweicloud.com/productdesc-iothub/iot_04_0010.html)。 - API中参数device_id在网关场景下，除特殊说明外都为子设备ID。 #### 基本概念 - 账号 用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户来进行日常管理工作。 - 用户 由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在[我的凭证](https://console.huaweicloud.com/iam/#/myCredential)下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 - 区域（Region） 从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。 详情请参见[区域和可用区](https://support.huaweicloud.com/usermanual-iaas/zh-cn_topic_0184026189.html)。 - 可用区（AZ，Availability Zone） 一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 - 项目 华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。 图1项目隔离模型 ![](https://support.huaweicloud.com/api-iothub/figure/zh-cn_image_0000001737796261.png) - 企业项目 企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。关于企业项目ID的获取及企业项目特性的详细信息，请参见《[企业管理服务用户指南](https://support.huaweicloud.com/usermanual-em/em_am_0006.html)》。 - 资源空间 指在物联网平台中为您的业务划分的一个资源空间，您在平台中创建的资源（如产品、设备等）都需要归属到某个资源空间，您可以基于资源空间实现多业务应用的分域管理。详情请参见[资源空间](https://support.huaweicloud.com/usermanual-iothub/iot_01_0006.html)。 - 产品 产品模型用于描述设备具备的能力和特性。开发者通过定义产品模型，在物联网平台构建一款设备的抽象模型。详情请参见[什么是产品模型](https://support.huaweicloud.com/devg-iothub/iot_01_0017.html)。 - 消息下发 消息下发不依赖产品模型，提供给设备的单向通知，具有消息缓存功能；详情请参见[消息下发概述](https://support.huaweicloud.com/usermanual-iothub/iot_01_0331.html)。 - 命令下发 为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可向设备下发的命令，应用服务器可以调用物联网平台应用侧API接口向设备下发命令，以实现对设备的远程控制。详情请参见[命令下发概述](https://support.huaweicloud.com/usermanual-iothub/iot_01_0339.html)。 - 属性下发 属性下发分为查询设备属性和修改属性参数两种，查询设备属性用于应用侧或平台主动获取设备属性数据，修改属性参数用于应用侧或平台设置设备属性值并同步到设备侧。详情请参见[属性下发概述](https://support.huaweicloud.com/usermanual-iothub/iot_01_0335.html)。 - AMQP队列管理 AMQP（Advanced Message Queuing Protocol）即高级队列消息协议。用户可通过AMQP的客户端与IoT平台建立链接，来接收平台推送数据。详情请参见[AMQP订阅推送](https://support.huaweicloud.com/usermanual-iothub/iot_01_0003.html)。 - 数据流转 设备接入到物联网平台后，便可与物联网平台进行通信。设备通过自定义Topic或产品模型方式将数据上报到平台，在控制台设置后，通过订阅推送的方式，将设备生命周期变更、设备属性上报、设备消息上报、设备消息状态变更、设备状态变更、批量任务状态变更等消息推送到您指定的服务器。详情请参见[转发方式概述](https://support.huaweicloud.com/usermanual-iothub/iot_01_00140.html)。 - 设备影子 物联网平台支持创建设备的"影子"。设备影子是一个JSON文件，用于存储设备的在线状态、设备最近一次上报的设备属性值、应用服务器期望下发的配置。每个设备有且只有一个设备影子，设备可以获取和设置设备影子以此来同步设备属性值，这个同步可以是影子同步给设备，也可以是设备同步给影子。详情请参见[设备影子](https://support.huaweicloud.com/usermanual-iothub/iot_01_0049.html)。 - 设备组（群组） 群组是一系列设备的集合，用户可以对资源空间下所有设备，根据区域、类型等不同规则进行分类建立群组，以便处理对海量设备的批量操作。例如，对资源空间下所有水表设备的群组进行固件升级。平台支持群组的增删改查操作，支持给群组绑定和解绑设备，支持一个设备被添加到多个群组中。详情请参见[群组与标签](https://support.huaweicloud.com/usermanual-iothub/iot_01_0020.html)。 - 标签 对于拥有大量云资源的用户，可以通过给云资源打标签，快速查找具有某标签的云资源，可对这些资源标签统一进行检视、修改、删除等操作，方便用户对云资源的管理。详情请参见[标签概述](https://support.huaweicloud.com/usermanual-iothub/iot_01_0151.html)。 - 联动规则 联动规则分为端侧规则和云端规则。端侧规则：端侧规则是指用户在云平台创建的设备联动规则，可以下发到端侧设备，该设备上会运行端侧规则引擎，对云端下发的规则进行解析并执行。端侧规则可以在网络中断或设备无法与云端交互情况下，继续在端侧执行指定规则。云端规则：当用户设置云端规则时，物联网平台会判断是否满足规则触发条件，在条件满足时，平台会执行用户预设的动作。比如：事件告警、主题通知、设备命令下发等。详情请参见[云端规则](https://support.huaweicloud.com/usermanual-iothub/iot_01_0023.html)。 - 批量任务 当需要对多个设备进行批量操作时，可以选择批量任务执行该操作。当前支持批量软固件升级、批量创建设备、批量修改设备、批量删除设备、批量冻结设备、批量解冻设备、批量创建命令、批量创建消息、批量配置设备影子和批量更新设备任务。 - OTA升级 OTA升级指的是软固件升级，软件升级指升级设备的系统软件和应用软件，固件升级指升级设备硬件的底层"驱动程序"。升级方式均为将软/固件包上传到物联网平台或者关联用户OBS上的对象，设备从物联网平台或用户OBS获取软/固件包实现远程升级。详情请参见[OTA升级相关问题](https://support.huaweicloud.com/iothub_faq/iot_faq_01001.html)。