Before You Start

Overview

IoTDA provides abundant management capabilities through APIs, including product, device, device group, tag, device CA certificate, device shadow, device command, device message, device property, subscription, rule, and batch task management, which helps you quickly build applications based on the platform. You can use the platform services based on the APIs provided in this document. For details on all the APIs provided by the platform, see API.

Description

The platform supports RESTful APIs that allow HTTPS-based calling. For details on how to call an API, see Calling APIs.

Endpoints

An endpoint is the request address for calling an API. For endpoints of IoTDA, see Platform Connection Information.

Constraints

• Forward compatibility is supported. If an API is upgraded, the API of the earlier version can still be used, but its functions are not enhanced. The new functions are provided only in the new version.
• When receiving and processing response messages and push messages from the IoT platform, an application must support or ignore new parameters in the messages. It should not return an error because of the new parameters.
• For details on more restrictions on calling APIs, see Limitations.
• In gateway scenarios, the value of device_id is the child device ID unless otherwise specified.

Concepts

• Account

  An account is created upon successful registration with Huawei Cloud. The account has full access permissions for all of its cloud services and resources. It can be used to reset user passwords and grant user permissions. The account is a payment entity and should not be used directly to perform routine management. For security purposes, create users and grant them permissions for routine management.

• Users

  An Identity and Access Management (IAM) user is created by an account to use cloud services. Each IAM user has its own identity credentials (password and access keys).

  An IAM user can view the account ID and user ID on the My Credentials page of the management console. The account name, username, and password will be required for API authentication.

• Region

  Regions are divided from the dimensions of geographical location and network latency. Public services, such as Elastic Cloud Server (ECS), Elastic Volume Service (EVS), Object Storage Service (OBS), Virtual Private Cloud (VPC), Elastic IP (EIP), and Image Management Service (IMS), are shared within the same region. Regions are classified into universal regions and dedicated regions. A universal region provides universal cloud services for common tenants. A dedicated region provides specific services for specific tenants.

  For details, see Region and AZ.

• Availability zone (AZ)

  An availability zone (AZ) contains one or more physical data centers. Each AZ has independent cooling, fire extinguishing, moisture-proofing, and electricity facilities. Within an AZ, computing, network, storage, and other resources are logically divided into multiple clusters. AZs within a region are interconnected using high-speed optical fibers to support cross-AZ high-availability systems.

• Project

  Projects group and isolate resources (including compute, storage, network, and other resources) across physical regions. A default project is provided for each region, and subprojects can be created under each default project. Users can be granted permissions to access all resources in a specific project. If you need more refined access control, create subprojects under a default project and purchase resources in subprojects. Then you can assign users the permissions required to access only the resources in the specific subprojects.

  Figure 1 Project isolation model
  
• Enterprise project

  Enterprise projects group and manage resources across regions. Resources in enterprise projects are logically isolated. It contains resources in multiple regions, and allows resources to be added or removed. For details about how to obtain enterprise project IDs and features, see Applicable Scenarios.

• Resource spaces

  Resource space is a space allocated for your applications. Resources (such as products and devices) created on the platform must belong to a resource space. You can use the resource space for domain-based management. For details, see Resource Spaces.

• Products

  A product model describes the capabilities and features of a device. Developers can define product models to build an abstract model of a device on IoT platform. For details, see Product Model Definition.

• Message delivery

  Message delivery does not rely on product models. The platform provides one-way notifications for devices and caches messages. For details, see Message Delivery.

• Command delivery

  A product model defines commands that can be delivered to the devices. Applications can call platform APIs to deliver commands to the devices to effectively manage these devices. For details, see Command Delivery.

• Property delivery

  Property delivery is used for property query or modification. An application or the platform can obtain device property information or modify the properties, and synchronize the modification result to the device. For details, see Property Delivery.

• AMQP queue management

  AMQP is short for Advanced Queuing Message Protocol. You can use the AMQP client to establish a connection with IoTDA to receive data. For details, see AMQP Subscription/Push.

• Data forwarding

  A device can connect to and communicate with the platform. The device reports data to the platform using custom topics or product models. After the subscription/push configuration on the console is complete, the platform pushes messages about device lifecycle changes, reported device properties, reported device messages, device message status changes, device status changes, and batch task status changes to the application. For details, see Overview of Subscription and Push.

• Device shadow

  The IoT platform supports the creation of device shadows. A device shadow is a JSON file that stores the device status, latest device properties reported, and device configurations to deliver. Each device has only one shadow. A device can retrieve and set its shadow to synchronize properties, either from the shadow to the device or from the device to the shadow. For details, see Device Shadow.

• Device group

  A group is a collection of devices. You can create groups for all the devices in a resource space based on different rules, such as regions and types, and you can operate the devices by group. For example, you can perform a firmware upgrade on a group of water meters in the resource space. Devices in a group can be added, deleted, modified, and queried. A device can be bound to and unbound from multiple groups. For details, see Group.

• Tags

  You can add tags to cloud resources for quicker search. You can view, modify, and delete these tags in a unified manner, facilitating cloud resource management. For details, see Tag Overview.

• Linkage rules

  Linkage rules are classified into device-side rules and cloud rules. Device-side rules: Device-side rules are device linkage rules delivered to devices, where the device-side rule engine parses and executes the rules. Device-side rules can still run on devices when the network is interrupted or devices cannot communicate with the platform. Cloud rules: If you set a cloud rule, IoTDA determines whether the rule triggering condition is met. If the condition is met, IoTDA performs actions you set, such as alarm reporting, topic notification, and command delivery. For details, see Cloud Rules.

• Batch tasks

  You can use batch tasks to perform a batch operation on multiple devices. Supported batch operations: Upgrading software and firmware, creating, modifying, deleting, freezing, unfreezing, and updating devices, creating commands and messages, and setting device shadow.

• OTA upgrade

  OTA upgrade refers to software and firmware upgrade. Software upgrade refers to the upgrade of the system software and application software of the device. Firmware upgrade refers to the upgrade of the underlying driver of the device hardware. You can upload a software/firmware upgrade package to the IoTDA platform or use a file associated with an object on OBS for device remote upgrades. For details, see About OTA Upgrade.