CLI integration examples

Alibaba Cloud Command Line Interface (Alibaba Cloud CLI) is a general-purpose command-line tool built on OpenAPI. You can use Alibaba Cloud CLI to automate the management and maintenance of ApsaraMQ for RocketMQ. This topic uses an example of calling the ListInstances API operation to query a list of ApsaraMQ for RocketMQ instances to describe the steps for using Alibaba Cloud CLI to call the OpenAPI of ApsaraMQ for RocketMQ 5.0.

Background

Before you begin, ensure you are familiar with the Alibaba Cloud CLI. For more information, see What is Alibaba Cloud CLI?.

Step 1: Install the Alibaba Cloud CLI

To use the Alibaba Cloud CLI, you must first install it. Installation packages are available for Windows, Linux, and macOS. Select the package for your operating system.

You can also debug Alibaba Cloud CLI commands in Cloud Shell. The Alibaba Cloud CLI is pre-installed in Cloud Shell and is updated regularly. For more information, see What is Cloud Shell?.

Step 2: Configure the Alibaba Cloud CLI

Important

An Alibaba Cloud primary account has management and access permissions for the OpenAPI of all products, which poses high security risks. We strongly recommend that you create a RAM identity, grant permissions based on the principle of least privilege, and use the RAM identity to access OpenAPI. For more information about the policies supported by ApsaraMQ for RocketMQ 5.x, see RocketMQ System Policy Reference and Custom Policies for ApsaraMQ for RocketMQ.

Before using the Alibaba Cloud CLI, you must configure your credentials and a region ID. Alibaba Cloud CLI supports multiple types of credentials. For more information, see Configure and manage credentials. This topic uses an AccessKey credential as an example.

Create a RAM user and an AccessKey pair to use as your credentials. For more information, see Create a RAM user and Create an AccessKey pair.
Grant permissions to the RAM user. For this example, grant the RAM user the AliyunMQReadOnlyAccess policy, which provides read-only permissions for ApsaraMQ for RocketMQ 5.x. For more information, see Manage RAM user permissions.
Obtain an available region ID. The Alibaba Cloud CLI sends API requests to the specified region. For a list of available regions for ApsaraMQ for RocketMQ 5.x, see Endpoints.

Note
You can use the --region option to specify the region for a command. This option overrides the default region configured in your profile and environment variables. For more information, see Command-line options.
Use the RAM user's AccessKey pair to configure an AccessKey credential in a profile named AkProfile. For more information, see Configure and manage credentials.

Step 3: Generate a sample CLI command

In OpenAPI Explorer, access the ListInstances debugging page.

Click the CLI Example tab on the right to view the generated CLI command aliyun rocketmq GET /instances --header "Content-Type=application/json". You can click the run button next to the command to execute it.
On the Parameters tab, configure the request parameters. Then, click the CLI Example tab to view the generated CLI example.
Copy the CLI example or run it quickly in Cloud Shell:
- Click the Run command button to open Cloud Shell and debug the command.
- Click the Copy button to copy the CLI example to the clipboard, and then paste it into your local shell to run.
Note
When you paste the CLI example into your local shell for debugging, verify the parameter format. For more information about the parameter formats of Alibaba Cloud CLI, see Understand command-line parameters.

OpenAPI Explorer adds the --region option to the sample command by default. When you copy the command to run it locally, Alibaba Cloud CLI prioritizes the specified region and ignores the region information in your default profile and environment variables. You can keep or remove this option as needed.

Step 4: Call ApsaraMQ for RocketMQ 5.0 OpenAPI

Example 1: List of ApsaraMQ for RocketMQ 5.0 OpenAPI operations

The following example shows how to use the --help option to get the list of ApsaraMQ for RocketMQ 5.0 OpenAPI operations available in the Alibaba Cloud CLI. You can also view the supported OpenAPI operations in the API overview.

Run the command.
```
aliyun rocketmq --help
```

The command returns the following output:

Product: RocketMQ (ApsaraMQ for RocketMQ 5.0)
Version: 2022-08-01
Available Api List:
  ChangeResourceGroup          : POST /resourceGroup/change
  CreateConsumerGroup          : POST /instances/[instanceId]/consumerGroups/[consumerGroupId]
  CreateInstance               : POST /instances
  CreateInstanceAccount        : POST /instances/[instanceId]/accounts
  CreateInstanceAcl            : POST /instances/[instanceId]/acl/account/[username]
  CreateInstanceIpWhitelist    : POST /instances/[instanceId]/ip/whitelist
  CreateTopic                  : POST /instances/[instanceId]/topics/[topicName]
  DeleteConsumerGroup          : DELETE /instances/[instanceId]/consumerGroups/[consumerGroupId]
  DeleteConsumerGroupSubscription : DELETE /instances/[instanceId]/consumerGroups/[consumerGroupId]/subscriptions
  DeleteInstance               : DELETE /instances/[instanceId]
  DeleteInstanceAccount        : DELETE /instances/[instanceId]/accounts/[username]
  DeleteInstanceAcl            : DELETE /instances/[instanceId]/acl/account/[username]
  DeleteInstanceIpWhitelist    : DELETE /instances/[instanceId]/ip/whitelist
  DeleteTopic                  : DELETE /instances/[instanceId]/topics/[topicName]

Example 2: Query instance list

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

Run the command.

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

The command returns the following 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 occurs when you call an ApsaraMQ for RocketMQ 5.0 OpenAPI operation, use the returned error code to verify that your request parameters and values are valid.

You can also note the RequestId or SDK error message from the response and use the OpenAPI Diagnosis Service for self-service troubleshooting.