Example of calling an API operation - IoT Platform - Alibaba Cloud Documentation Center

This topic describes how to call an API operation of IoT Platform. In this example, the Pub operation is called to publish a message to a device by using a custom topic.

View the API documentation

You can call the Pub operation to publish a message to a device by using a custom topic. For more information, see List of operations by function. Read the API reference of the operation to get familiar with the data and permissions that are required to call this operation.

Create a RAM user and grant permissions to the RAM user

Identities

You can use an Alibaba Cloud account, a Resource Access Management (RAM) user, or a RAM role to call this operation. For information about the differences among these identities, see Identity, credential, and authorization. In this example, a RAM user is used to call this operation.

Log on to the RAM console. Create a RAM user, select only the OpenAPI Access option for the Access Mode parameter, and then record the AccessKey pair. For more information, see Create a RAM user.

Authorization

On the Users page of the RAM console, find the RAM user that you want to manage and click Add Permissions in the Actions column.
In the Select Policy section of the Add Permissions panel, enter IoT in the search box to search for and select the AliyunIOTFullAccess policy.
Note
- You can attach the following system policies of IoT Platform to a RAM user:
  - AliyunIOTFullAccess: grants full permissions on IoT Platform.
  - AliyunIOTReadOnlyAccess: grants the read-only permissions on IoT Platform.
- For more information about how to create a custom policy, see Custom permissions.
Click OK.

Credentials

By default, an AccessKey pair is generated when you create a RAM user. You can directly use the AccessKey pair.

You can also perform the following operations to create an AccessKey pair: Go to the details page of a RAM user. On the Authentication tab, click Create AccessKey. For more information, see Create an AccessKey pair.

Call the operation

In this example, IoT Platform SDK for Python is used to call the operation.

Prepare a Python environment

Check whether Python 3 is installed.
Linux or macOS
Open the terminal and run the python3 --version command.
If the version number of Python 3 is returned, Python 3 is installed. Otherwise, Python 3 is not installed. Go to the next step to install Python 3.
Windows
In the Python installation directory, double-click python.exe to start Command Prompt. You can also press Win+R. In the Run dialog box, enter python and click OK.
If an output similar to the following one is returned, Python 3 is installed:
```
Python 3.9.6 (tags/v3.9.6:db3ff76, Jun 28 2021, 15:26:21) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>  
```
Download and install Python.
For more information about how to download Python 3, visit the official website of Python.
Linux
1. Obtain the Python package.
```
wget https://www.python.org/ftp/python/3.9.6/Python-3.9.6.tgz
```
2. Decompress the Python package.
```
tar -zxvf Python-3.9.6.tgz
```
3. Switch to the path to which the Python package is decompressed and specify the installation path.
```
cd Python-3.9.6
sudo ./configure --prefix=/usr/bin/python3
```
4. Compile and install Python.
```
make
make install
```
5. Configure an environment variable to store the installation path of Python 3.
  For example, if you use the Ubuntu Linux operating system, perform the following steps:
  1. Open the .bashrc file.
    nano ~/.bashrc
  2. Add the following content to the end of the file. Save and close the file.
    export PATH=$PATH:/usr/bin/python3
  3. Run the following command to update environment variables:
    source ~/.bashrc
  4. Run the following command to check whether the PATH environment variable contains the installation path of Python 3:
    echo $PATH
macOS
Python 2.7 is installed on macOS by default. We recommend that you download and install the latest version of Python 3.
1. After you download the Python package, double-click the installation package to open the wizard.
2. Click Continue and install Python 3 as prompted.
3. Configure an environment variable to store the installation path of Python 3.
Windows
1. After you download the Python package, double-click the installation package to open the wizard. Use the default settings and select Add Python 3.9 to PATH.
2. Click Install Now to install Python.
3. After the installation is complete, click Close.
Repeat Step 1 to check the version of Python 3. If the version number of Python 3 is displayed, Python 3 is installed.

Configure environment variables

In this example, environment variables are configured to manage the AccessKey pair. This prevents security risks that are caused by hard-coding the AccessKey pair into your business code.

Linux or macOS
Replace <access_key_id> and <access_key_secret> in the following commands with the AccessKey ID and AccessKey secret of the RAM user and run the commands on the terminal:
```
export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>
```
Windows
Create an environment variable file, add the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to the file, and then specify your AccessKey ID for ALIBABA_CLOUD_ACCESS_KEY_ID and your AccessKey secret for ALIBABA_CLOUD_ACCESS_KEY_SECRET. Then, restart the Windows operating system.

Install dependencies

pip3 install alibabacloud_tea_openapi
pip3 install alibabacloud_iot20180120
pip3 install alibabacloud-tea-console

Download the sample code

Go to the Pub debugging page in OpenAPI Explorer. For more information about the operation, see Pub.
Specify the IotInstanceId, ProductKey, TopicFullName, and MessageContent request parameters. You do not need to specify other parameters.
Click Initiate Call.
After Call success is displayed on the Response tab, click the SDK Sample Code tab and select Python.
Click Download Project to download the sample code package.
Decompress the sample code package on your computer and go to the alibabacloud_sample directory.

Run the code

Run the following command:

python sample.py

The following output is returned:

{
    "headers": {
        "date": "Thu, 10 Aug 2023 09:26:52 GMT",
        "content-type": "application/json;charset=utf-8",
        "content-length": "99",
        "connection": "keep-alive",
        "keep-alive": "timeout=25",
        "access-control-allow-origin": "*",
        "access-control-expose-headers": "*",
        "x-acs-request-id": "1296FD43-4BD3-5F80-AB2C-1ADF99B02253",
        "x-acs-trace-id": "aee72e4c5e***************77fc9d",
        "etag": "9umD************cjYJ8og9"
	},
    "statusCode": 200,
    "body": {
        "MessageId": 1689000000000004736,
        "RequestId": "1296FD43-4BD3-5F80-AB2C-1ADF99B02253",
        "Success": true
    }
}