Use Alibaba Cloud CLI to call the OOS API - CloudOps Orchestration Service

Alibaba Cloud CLI is a general-purpose command-line tool that is developed based on OpenAPI. You can use Alibaba Cloud CLI to automate management and maintenance in CloudOps Orchestration Service. This topic describes how to use Alibaba Cloud CLI to call the CloudOps Orchestration Service API by providing several examples.

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 use it. You can install Alibaba Cloud CLI in the Windows, Linux, and macOS operating systems. 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 Resource Access Management (RAM) user to call API operations or perform routine O&M operations.

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 identity credentials. For more information, see the "Identity credential types" section of the Configure identity credentials topic. In this example, AccessKey credentials are used. Perform the following steps:

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 Use RAM for access control.
Create an AccessKey pair for the RAM user and record the AccessKey ID and AccessKey secret for the subsequent configuration of identity credentials. For more information, see Create an AccessKey pair.
Specify a region ID. Alibaba Cloud CLI calls API operations in the specified region. For more information about available regions, 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 this 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 AccessKey credentials in the configuration file named AkProfile. For more information, see the "Configuration examples" section of the Configure identity credentials topic.

Generate a CLI command

Go to the API debugging page of OOS.
In the left-side search box of the API debugging page, search for the API operation that you want to call. On the Parameters tab of the API operation, specify the parameters based on the API reference. Click the CLI Example tab on the right to view the generated sample command that contains the specified parameters.
- Click the icon to start Cloud Shell and debug the command in Cloud Shell.
- Click the icon to copy the sample command to the clipboard. Then, paste the sample command into your local shell to run the sample command.
  - Pay attention to the formats of parameters when you paste the sample command into your local shell for debugging. For more information about the parameter formats in Alibaba Cloud CLI commands, see Parameter formats.
  - By default, the --region option is added to the sample command that is generated in OpenAPI Explorer. When you copy the command to your local shell, Alibaba Cloud CLI ignores the region information in the default credential configurations and environment variable settings, and preferentially runs the command in the specified region. You can delete or retain this option based on your business requirements.

Call API operations

Syntax

In Alibaba Cloud CLI, you can use the following syntax to run commands. For more information, see the "Syntax" section of the Generate and run CLI commands topic.

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

Common command options

When you use Alibaba Cloud CLI, you can specify command options to change the behaviors of commands or implement extended features of commands. The following common 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 the 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 CloudOps Orchestration Service 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 oos --help
```
View the result.

Sample 2: The following sample code describes how to use Alibaba Cloud CLI to call the CreateTemplate operation of OOS to create a template named CLI_Template.

Run the following command:

Note

The input format of string-type JSON array list parameters varies depending on your operating system. Choose and run the corresponding command based on your operating system. For more information, see Parameter formats.

Linux/macOS

aliyun oos CreateTemplate --RegionId 'cn-hangzhou' --TemplateName CLI_Template --Content '{"FormatVersion": "OOS-2019-06-01", "Description": "Describe instances of given status", "Parameters": {"Status": {"Type": "String", "Description": "(Required) The status of the Ecs instance."}}, "Tasks": [{"Properties": {"Parameters": {"Status": "{{ Status }}"}, "API": "DescribeInstances", "Service": "Ecs"}, "Name": "foo", "Action": "ACS::ExecuteApi"}]}'

Windows

aliyun oos CreateTemplate --RegionId 'cn-hangzhou' --TemplateName CLI_Template --Content "{'FormatVersion': 'OOS-2019-06-01', 'Description': 'Describe instances of given status', 'Parameters': {'Status': {'Type': 'String', 'Description': '(Required) The status of the Ecs instance.'}}, 'Tasks': [{'Properties': {'Parameters': {'Status': '{{ Status }}'}, 'API': 'DescribeInstances', 'Service': 'Ecs'}, 'Name': 'foo', 'Action': 'ACS::ExecuteApi'}]}"

View the result.

{
  "RequestId": "989F0944-E653-5826-9FA7-8ADE6E66F485",
  "Template": {
    "Description": "Describe instances of given status",
    "CreatedBy": "test(2039927162697*****)",
    "TemplateFormat": "JSON",
    "ResourceGroupId": "rg-acfmykd6*****",
    "UpdatedDate": "2024-08-05T10:28:24Z",
    "TemplateVersion": "v1",
    "Hash": "8abc5921b5a05051992*****",
    "UpdatedBy": "test(2039927162697*****)",
    "HasTrigger": false,
    "CreatedDate": "2024-08-05T10:28:24Z",
    "TemplateName": "CLI_Template",
    "Tags": {},
    "TemplateId": "t-9246d5246f*****",
    "ShareType": "Private"
  }
}

Note

If an error is returned after you call an API operation of CloudOps Orchestration Service, 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 error information.