Use Alibaba Cloud CLI to call DataWorks OpenAPI-DataWorks(DataWorks)-阿里云帮助中心

This topic describes how to use Alibaba Cloud CLI to call a DataWorks OpenAPI, using a call to the DataWorks ListProjects API to query a list of DataWorks workspaces as an example.

Concepts

Alibaba Cloud Command Line Interface (CLI) is a general-purpose command-line tool built on OpenAPI. The CLI lets you automate the management and maintenance of DataWorks. For more information, see What is Alibaba Cloud CLI?.

Step 1: Install the Alibaba Cloud CLI

You must install the Alibaba Cloud CLI before you can use it. The Alibaba Cloud CLI can be installed on Windows, Linux, and macOS operating systems. Choose the installation instructions for your operating system.

Cloud Shell comes pre-installed with the Alibaba Cloud CLI and automatically configures your identity credentials. No manual configuration is required. You can debug CLI commands in Cloud Shell. For more information, see What is Cloud Shell?.

Step 2: Configure the Alibaba Cloud CLI

Important

An Alibaba Cloud account has full access to all OpenAPI operations, which poses a high security risk. We recommend that you create a Resource Access Management (RAM) user, grant permissions based on the principle of least privilege, and use the RAM user to access OpenAPI. For more information about the access policies that DataWorks supports, see DataWorks System Policies and DataWorks Custom Policies.

Before you use the Alibaba Cloud CLI, you must configure information, such as your identity credentials and a region ID. The Alibaba Cloud CLI supports multiple types of identity credentials. For more information, see Identity Credential Types. The Alibaba Cloud CLI supports using the AccessKey of a Resource Access Management (RAM) user to configure AK-type identity credentials. The procedure is as follows:

Create a RAM user and an AccessKey. You will use them to configure your identity credentials. For more information, see Create a RAM user and Create an AccessKey.
Attach a policy to the RAM user. In this example, you must attach the AliyunDataWorksReadOnlyAccess policy to grant read-only access to DataWorks. For more information, see Manage RAM user permissions.
Obtain the ID of an available region to configure your identity credentials. The CLI uses the specified region to make OpenAPI calls. For a list of regions where DataWorks is available, see Endpoints.
Note
When you use the CLI, you can use the --region option to specify a region for a command. This option overrides the region settings in your default credential configuration and environment variables. For more information, see Command-line options.
Use the AccessKey pair of the RAM user to configure AK credentials. Name the configuration profile AkProfile. For more information, see Configuration example.

Step 3: Generate a CLI command example

In the OpenAPI Portal, go to the ListProjects debugging page.
In the Parameter Settings section, enter the request parameters. Click the CLI Example tab to view the generated CLI example.
Copy the CLI example or run it in Cloud Shell:
- Click the Run Command button to open Cloud Shell and quickly debug the command.
- Click the Copy button to copy the CLI example to the clipboard. You can then paste it into a local shell tool to run it or use it to edit an automated command-line script.
Note
When you copy the CLI example to a local shell tool for debugging, take note of the parameter format. For more information about the parameter format for CLI commands, see Parameter format.
The example generated by the OpenAPI Portal includes the --region option by default. When you copy the command to run it locally, the CLI uses the specified region and ignores the region settings in your default credential configuration and environment variables. You can remove or keep this option as needed.

Step 4: Call a DataWorks OpenAPI operation

Example 1: Get a list of OpenAPI operations

This example shows how to use the --help option to obtain a list of DataWorks OpenAPI operations that you can call using the CLI. For more information, see API overview.

Run the following command.
```
aliyun dataworks-public --help
```
Expected output.

Example 2: Query a list of workspaces

This example shows how to use the CLI to call the ListProjects operation of DataWorks. This operation queries for a list of available standard-mode workspaces in your tenant. For more information about this API operation, see ListProjects - Get a list of workspace details.

Run the command.

aliyun dataworks-public ListProjects --Status Available --DevEnvironmentEnabled true

Output.

{
  "RequestId": "6D24AD9A-652F-59E2-AC1F-05029300F8A4",
  "PagingInfo": {
    "PageSize": 1,
    "PageNumber": 10,
    "TotalCount": 1,
    "Projects": [
      {
        "Id": 123456,
        "Name": "sora_finance",
        "DisplayName": "Sora Finance Analysis",
        "Description": "Data development for the finance analysis group project",
        "Owner": "12353215****",
        "AliyunResourceGroupId": "rg-acfmzbn7pti****",
        "Status": "Available",
        "PaiTaskEnabled": true,
        "DevEnvironmentEnabled": true,
        "DevRoleDisabled": false,
        "AliyunResourceTags": [
          {
            "Key": "batch",
            "Value": "blue"
          }
        ]
      }
    ]
  }
}

Note

If an error is returned after you call a DataWorks OpenAPI operation, use the error code to check your request parameters and their values.

You can record the RequestID or SDK error message and use the Alibaba Cloud OpenAPI Diagnostic Platform to diagnose the issue.