Alibaba Cloud CLI integration example - ApsaraDB RDS - Alibaba Cloud Documentation Center

Alibaba Cloud CLI is a general-purpose command-line tool that is developed based on APIs. You can use Alibaba Cloud CLI to interact with ApsaraDB RDS and manage ApsaraDB RDS instances in shell. This topic describes how to use Alibaba Cloud CLI to call ApsaraDB RDS API operations.

Before you start

For more information about Alibaba Cloud CLI, see What is Alibaba Cloud CLI?

Install Alibaba Cloud CLI

You must install Alibaba Cloud CLI before you can use Alibaba Cloud CLI. You can install Alibaba Cloud CLI in the Windows, Linux, and macOS operating systems. You must select an installation package of Alibaba Cloud CLI based on the operating system of 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 provided by Alibaba Cloud to debug the commands that you want to run in Alibaba Cloud CLI. For more information about Cloud Shell, see What is Cloud Shell?

Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has the permissions to manage and access the APIs 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 and use a RAM user to call API operations or perform routine O&M operations. If you want to use a RAM user to manage RDS instances, you must attach the AliyunRDSReadOnlyAccess policy to the RAM user. The policy grants the permissions to query RDS instances. You can also attach the AliyunRDSFullAccess policy to the RAM user based on your business requirements. The policy grants full permissions on RDS instances.

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

Create a RAM user and grant the RAM user the permissions to manage Alibaba Cloud services based on your business requirements. For more information, see Create a RAM user and Grant permissions to a RAM user.
Create an AccessKey pair for the RAM user and record the AccessKey ID and AccessKey secret for the configuration of identity credentials. For more information, see Create an AccessKey pair for a RAM user.
Obtain and record the ID of an available region for the configuration of identity credentials. Alibaba Cloud CLI uses the specified region ID to initiate API calls. For more information about the available regions, see Endpoints.
Note
When you use Alibaba Cloud CLI, you can use the --region option to run a command in a specific region. If you use the option, Alibaba Cloud CLI ignores the region information in the default 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 identity credentials in the configuration file named AkProfile. For more information, see Configuration examples.

Generate a CLI command

Go to the Debugging page of the ApsaraDB RDS API.
In the left-side search box of the page that appears, search for the operation that you want to call. On the Parameters tab, configure the parameters based on API documentation. You can click the CLI Example tab on the right to view the generated sample CLI command that contains the specified parameters.
- Click the icon to view information about Cloud Shell. For more information, see What is Cloud Shell? Then, complete the command debugging.
- Click the icon to copy the sample command to the clipboard. You can also paste the sample command into your shell to run.
  - When you paste the sample command into your shell for debugging, take note of the formats of parameters. For more information about the parameter formats of Alibaba Cloud CLI, see Parameter formats.
  - By default, OpenAPI Explorer adds the --region option to the generated CLI command. When you copy the command to your shell, Alibaba Cloud CLI ignores the region information in the default identity credential configurations and environment variable settings, and preferentially runs the command in the specified region. You can delete or retain the option based on your business requirements.

Call API operations of a cloud service

Syntax

In Alibaba Cloud CLI, you can use the following syntax to run commands. For more information, see Command structure.

aliyun <command> <subcommand> [options and parameters]

Command options

When you use Alibaba Cloud CLI, you can specify command options to change the behaviors of commands or implement the extended features of commands. In most cases, the following command options are used:

--profile<profileName>: You can use the --profile option and the profileName parameter to specify a configuration profile. After you specify a valid configuration profile, Alibaba Cloud CLI ignores the information in default credential configurations and environment variable settings and preferentially uses the configurations that you specify to run commands.
--help: You can use the --help option to obtain the help information about a command. For more information, see Use the help command.

For more information, see Command line options for API calls.

Sample code

Sample 1: The following sample code describes how to use the --help option to obtain the list of ApsaraDB RDS API operations supported by Alibaba Cloud CLI. You can also view the API operations that can be called in List of operations by function.

Run the following command:
```
aliyun rds --help
```

View the result.

Command output

Alibaba Cloud Command Line Interface Version 3.0.216

Usage:
  aliyun rds <ApiName> --parameter1 value1 --parameter2 value2 ...

Product: Rds (ApsaraDB for RDS)
Version: 2014-08-15

Available Api List:
  ActivateMigrationTargetInstance             Switches workloads over from the source PostgreSQL instance to the destination ApsaraDB RDS for PostgreSQL instance.
  AddTagsToResource                           Adds tags to an instance.
  AllocateInstancePublicConnection            Apply for a public endpoint for an ApsaraDB RDS instance
  AllocateReadWriteSplittingConnection        Applies for a read-only routing endpoint for an instance.
  AttachWhitelistTemplateToInstance           Associates a whitelist template with an instance.
  CalculateDBInstanceWeight                   Queries system-assigned read weights.

...

Sample 2: The following sample code describes how to use Alibaba Cloud CLI to call the DescribeDBInstanceAttribute operation of ApsaraDB RDS.

Run the following command:

aliyun rds DescribeDBInstanceAttribute --region cn-hangzhou --DBInstanceId 'pgm-bp16k272p478****'

View the result.

Command output

{
        "Items": {
                "DBInstanceAttribute": [
                        {
                                "AccountMaxQuantity": 99999,
                                "AccountType": "Mix",
                                "AdvancedFeatures": "LinkedServer,DistributeTransaction",
                                "AutoUpgradeMinorVersion": "Auto",
                                "AvailabilityValue": "100.0%",
                                "BabelfishConfig": {},
                                "CanTempUpgrade": false,
                                "Category": "HighAvailability",
                                "ColdDataEnabled": false,
                                "ConnectionMode": "Standard",
                                "ConnectionString": "pgm-bp16k272p478****.pg.rds.aliyuncs.com",
                                "ConsoleVersion": "2",
                                "CreationTime": "2024-08-06T06:18:48Z",
                                "CurrentKernelVersion": "rds_postgres_1400_20240530",
                                "DBClusterNodes": {
                                        "DBClusterNode": []
                                },
                                "DBInstanceCPU": "2",
                                "DBInstanceClass": "pg.n4.2c.2m",
                                "DBInstanceClassType": "x",
                                "DBInstanceDescription": "DB-test",
                                "DBInstanceDiskUsed": 3520069632,
                                "DBInstanceId": "pgm-bp16k272p478****",
                                "DBInstanceMemory": 8192,
                                "DBInstanceNetType": "Intranet",
                                "DBInstanceStatus": "Running",
                                "DBInstanceStorage": 100,
                                "DBInstanceStorageType": "cloud_essd",
                                "DBInstanceType": "Primary",
                                "DBMaxQuantity": 99999,
                                "DedicatedHostGroupId": "",
                                "DeletionProtection": false,
                                "DispenseMode": "MultiAVZDispenseMode",
                                "Engine": "PostgreSQL",
                                "EngineVersion": "14.0",
                                "ExpireTime": "",
                                "Extra": {
                                        "DBInstanceIds": {
                                                "DBInstanceId": []
                                        }
                                },
                                "IPType": "IPv4",
                                "InsId": 1,
                                "InstanceNetworkType": "VPC",
                                "InstructionSetArch": "x86",
                                "IoAccelerationEnabled": "0",
                                "LatestKernelVersion": "rds_postgres_1400_20240530",
                                "LockMode": "Unlock",
                                "MaintainTime": "18:00Z-22:00Z",
                                "MasterZone": "cn-hangzhou-j",
                                "MaxConnections": 800,
                                "MaxIOMBPS": 0,
                                "MaxIOPS": 6800,
                                "OriginConfiguration": "{\"KindCode\":\"18\"}",
                                "PayType": "Postpaid",
                                "Port": "5432",
                                "ProxyType": 2,
                                "ReadOnlyDBInstanceIds": {
                                        "ReadOnlyDBInstanceId": []
                                },
                                "RegionId": "cn-hangzhou",
                                "ResourceGroupId": "rg-acfmz7u4zzrngoa",
                                "SecurityIPList": "0.0.0.0/0,172.16.0.0/12",
                                "SecurityIPMode": "normal",
                                "ServerlessConfig": {},
                                "SlaveZones": {
                                        "SlaveZone": [
                                                {
                                                        "ZoneId": "cn-hangzhou-k"
                                                }
                                        ]
                                },
                                "SuperPermissionMode": "",
                                "SupportCreateSuperAccount": "Yes",
                                "SupportUpgradeAccountType": "Yes",
                                "Tips": "ok",
                                "TipsLevel": 1,
                                "VSwitchId": "vsw-bp1sxxsodv28ey5dl****",
                                "VpcCloudInstanceId": "pgm-bp16k272p478****-20240806141842",
                                "VpcId": "vpc-bp1ov7as4yvz4kxei****",
                                "ZoneId": "cn-hangzhou-j",
                                "kindCode": "18"
                        }
                ]
        },
        "RequestId": "14B99E32-4ECD-5B8E-A9C8-6738C8C95910"
}

Note

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

You can also use Alibaba Cloud OpenAPI Diagnostics to perform self-service diagnostics based on the returned request ID or SDK error information.