Call WAF 3.0 with Alibaba Cloud CLI-Web Application Firewall(WAF)-阿里云帮助中心

Alibaba Cloud Command Line Interface (Alibaba Cloud CLI) is a general-purpose tool built on OpenAPI that you can use to automate the management and maintenance of Web Application Firewall 3.0. If you are not familiar with Alibaba Cloud CLI, see What is Alibaba Cloud CLI?. This topic describes how to use Alibaba Cloud CLI to call Web Application Firewall 3.0, using the DescribeVisitTopIp API operation as an example. This operation queries the top 10 IP addresses that send the most requests.

Install Alibaba Cloud CLI

Before using Alibaba Cloud CLI, you must install it. Installation packages are available for Windows, Linux, and macOS. Select the appropriate installation method for your operating system.

You can also use Cloud Shell to debug Alibaba Cloud CLI commands. For more information about Cloud Shell, see What is Cloud Shell?.

Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has full access to all product OpenAPI operations, which poses a high security risk. We strongly recommend creating a RAM identity, granting it permissions based on the principle of least privilege, and using it to access OpenAPI.

Before using Alibaba Cloud CLI, you must configure information such as your identity credentials and a region ID. Alibaba Cloud CLI supports multiple types of identity credentials. For more information, see Credential types. This topic uses an AccessKey pair as an example.

Create a RAM user and an AccessKey pair to configure your identity credentials. For more information, see Create a RAM user and Create an AccessKey.
Grant the necessary permissions to the RAM user. For this example, you must grant the RAM user read-only access to Web Application Firewall 3.0 by attaching the AliyunYundunWAFv3ReadOnlyAccess policy. For more information about system policies, see Web Application Firewall system permission policy reference.
Obtain and record an available region ID. The Alibaba Cloud CLI sends OpenAPI calls to the specified region. For a list of available regions, see Endpoints.
Note
When using Alibaba Cloud CLI, you can add the --region option to a command to specify a target region. This option overrides the default region configured in your identity credentials and environment variables. For more information, see Available options for OpenAPI commands.
Use the AccessKey pair to configure credentials and save them in a configuration profile named AkProfile. For more information, see Configuration examples.

Generate a CLI example

Click DescribeVisitTopIp to open OpenAPI Explorer.
In the Parameters section, enter the request parameters. Then, click the CLI Example tab to view the generated CLI example.
Copy the CLI example or quickly 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 your clipboard. You can then paste it into your local shell to run it.
  Note
  - When you debug the CLI example in a local shell, ensure the parameter format is correct. For more information about Alibaba Cloud CLI parameter formats, see Parameter formats.
  - OpenAPI Explorer automatically adds the --region option to the generated command example. When you run the command locally, Alibaba Cloud CLI prioritizes this specified region and ignores the region information in your default credential configuration and environment variables. You can keep or remove this option as needed.

Call an OpenAPI

Note

Alibaba Cloud CLI is integrated with the OpenAPI of Web Application Firewall 2.0. To call a Web Application Firewall 3.0 OpenAPI operation, you must append the --force --version 2021-10-01 options to the command. For more information, see Forceful calls.
When OpenAPI Explorer generates a command example for a Web Application Firewall 3.0 OpenAPI operation, it automatically includes the required options for a forceful call. No manual changes are needed.
See the API overview for other available OpenAPI operations.

Query top 10 IP addresses

This example calls the DescribeVisitTopIp operation of Web Application Firewall 3.0 to query the top 10 IP addresses that send the most requests.

Run the command.

aliyun waf-openapi DescribeVisitTopIp \
  --region cn-hangzhou \
  --RegionId 'cn-hangzhou' \
  --StartTimestamp 1665331200 \
  --EndTimestamp 1665386280 \
  --InstanceId 'waf_cdnsdf3****' \
  --version 2021-10-01 \
  --method POST \
  --force

The following output is returned.
```
{
  "RequestId": "5D2B8DAE-A761-58CB-A68D-74989E4831DA",
  "TopIp": [
    {
      "Area": "310000",
      "Ip": "1.1.XX.XX",
      "Isp": "AAA",
      "Count": 2622
    }
  ]
}
```
Note
If a call to a Web Application Firewall 3.0 OpenAPI operation returns an error, check the request parameters and their values based on the returned error code.
You can also record the returned request ID or SDK error message and use Alibaba Cloud OpenAPI Diagnostics for self-service troubleshooting.