Use Alibaba Cloud CLI to call the API operations of ApsaraMQ for RocketMQ 5.0 - ApsaraMQ for RocketMQ

Alibaba Cloud Command Line Interface (CLI) is a general-purpose command-line tool that is developed based on OpenAPI Explorer. You can use Alibaba Cloud CLI to automate management and maintenance in ApsaraMQ for RocketMQ. This topic describes how to use Alibaba Cloud CLI to call the ListInstances operation of ApsaraMQ for RocketMQ 5.0 to query the list of ApsaraMQ for RocketMQ instances.

Before you start

Make sure that you are familiar with Alibaba Cloud CLI. For more information, see What is Alibaba Cloud CLI?

Step 1: Install Alibaba Cloud CLI

You must install Alibaba Cloud CLI before you can use Alibaba Cloud CLI. You can install Alibaba Cloud CLI in Windows, Linux, and macOS operating systems. You must select an installation package of Alibaba Cloud CLI based on the operating system that runs on your device. For more information, see the following topics:

Windows operating system: Windows
Linux operating system: Linux
macOS operating system: macOS

You can also use Cloud Shell to debug the commands that you want to run in Alibaba Cloud CLI. Alibaba Cloud CLI is built into Cloud Shell, which regularly updates the software version. For more information, see What is Cloud Shell?

Step 2: Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has the permissions to manage and access the API operations of all Alibaba Cloud services. If you use an Alibaba Cloud account to call API operations, security risks may arise. We recommend that you create a Resource Access Management (RAM) identity, grant the required permissions to the RAM identity based on the principle of least privilege, and then use the RAM identity to call API operations. For information about the policies supported by ApsaraMQ for RocketMQ 5.x, see System policies for RocketMQ and Custom policies for ApsaraMQ for RocketMQ.

Before you use Alibaba Cloud CLI, you must configure information, such as identity credentials and a region ID, in Alibaba Cloud CLI. Alibaba Cloud CLI supports various types of identity credentials. For more information, see Credential types. In this example, AccessKey pairs are used as identity credentials.

Create a RAM user and then create an AccessKey pair for the RAM user. For more information, see Create a RAM user and Create an AccessKey pair for a RAM user.
Grant permissions to the RAM user. In this topic, the AliyunMQReadOnlyAccess policy is attached to the RAM user that you use to access Alibaba Cloud CLI. The AliyunMQReadOnlyAccess policy is used to grant the read-only permissions on ApsaraMQ for RocketMQ 5.x resources. For more information, see Grant permissions to a RAM user.
Obtain the ID of the region that you want to use to configure identity credentials. Alibaba Cloud CLI uses the specified region ID to initiate API calls. For information about the supported regions of ApsaraMQ for RocketMQ 5.x, see Endpoints.
Note
When you use Alibaba Cloud CLI, you can specify the --region option to run a command in a specific region. If you specify the --region option, Alibaba Cloud CLI ignores the region information in the default identity credential configurations and environment variable settings. For more information, see Command line options for API calls.
Use the AccessKey pair of the RAM user to configure AccessKey credentials in the profile named AkProfile. For more information, see Configuration examples.

Step 3: Generate a CLI command

In OpenAPI Explorer, call the ListInstances operation.
On the Parameters tab, configure the parameters. Then, click the CLI Example tab to view the generated sample CLI command.
Copy the CLI command or debug the CLI command in Cloud Shell.
- Click the icon to start Cloud Shell and then debug the CLI command in Cloud Shell.
- Click the icon to copy the CLI command to the clipboard and then paste the CLI command to a text editor. You can also paste the CLI command to your on-premises shell to run the command.
Note
When you paste the CLI command to your on-premises shell for debugging, take note of the parameter formats. For information about the parameter formats of Alibaba Cloud CLI, see Parameter formats.
By default, OpenAPI Explorer adds the --region option to the generated sample command. When you copy the command to your on-premises shell, Alibaba Cloud CLI ignores the region information in the default identity credential configurations and environment variable settings and then runs the command in the specified region. You can remove or retain the option based on your business requirements.

Step 4: Call the API operations of ApsaraMQ for RocketMQ 5.0

Example 1: Query the supported API operations of ApsaraMQ for RocketMQ 5.0 by using Alibaba Cloud CLI

The following example describes how to use the --help option to query the supported API operations of ApsaraMQ for RocketMQ 5.0. You can also view the supported API operations in List of operations by function.

Run the following command:
```
aliyun rocketmq --help
```
View the command output.

Example 2: Query a list of ApsaraMQ for RocketMQ instances

The following example shows how to use Alibaba Cloud CLI to call the ListInstances operation of ApsaraMQ for RocketMQ 5.x to query the list of ApsaraMQ for RocketMQ instances.

Run the following command:

aliyun rocketmq GET /instances --pageNumber 1 --pageSize 10

View the command output.

{
  "data": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalCount": 1,
    "list": [
      {
        "regionId": "cn-hangzhou",
        "instanceId": "rmq-cn-7e22ody****",
        "instanceName": "test instance",
        "status": "RUNNING",
        "startTime": "2022-08-01 00:00:00",
        "expireTime": "2022-09-01 00:00:00",
        "releaseTime": "2022-09-07 00:00:00",
        "userId": "6W0xz2uPfiwp****",
        "commodityCode": "ons_rmqsub_public_cn",
        "serviceCode": "rmq",
        "seriesCode": "standard",
        "subSeriesCode": "cluster_ha",
        "paymentType": "Subscription",
        "remark": "This is remark for instance.",
        "topicCount": 20,
        "groupCount": 10,
        "createTime": "2022-08-01 00:00:00",
        "updateTime": "2022-08-02 00:00:00",
        "resourceGroupId": "rg-acfmx7caj******",
        "tags": [
          {
            "key": "key",
            "value": "value"
          }
        ],
        "productInfo": {
          "traceOn": true
        }
      }
    ]
  },
  "requestId": "AF9A8B10-C426-530F-A0DD-96320B39****",
  "success": true,
  "httpStatusCode": 200
}

Note

If an error is returned after you call an API operation of ApsaraMQ for RocketMQ 5.0, check whether the input parameters and values are valid based on the error code.

You can also perform self-service diagnostics based on the returned request ID or SDK error message on the OpenAPI problem diagnosis page.