Java集成SDK-云控制API(Cloud Control API)-阿里云帮助中心

云控制API Java SDK 是一套专为 Java 开发者设计的工具包，基于云控制API（CloudControl API）构建。通过该 SDK，开发者可以轻松调用标准化接口，高效管理阿里云资源的全生命周期（创建、查询、更新、删除）。无论是多产品集成、快速适配新特性，还是处理异步任务，SDK 都能显著降低开发复杂度，让开发者专注于业务逻辑，无需关心底层接口差异。本文将详细介绍 SDK 的集成与使用方法。

前提条件

调用云控制API通常需要设置访问密钥（AccessKey）。由于阿里云账号（主账号）具有资源的所有权限，一旦发生泄露将面临重大风险。建议您使用RAM用户，并为该RAM用户创建AccessKey，具体操作方式，请参见创建RAM用户和创建AccessKey。
调用云控制API通常需要设置访问凭据，常见凭据类型为AccessKey（简称：AK）为防止凭据泄露，常用的方案是将其存储到环境变量中。
说明
本文以设置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET为例：
设置访问凭据到系统环境
Linux和macOS系统配置方法
通过export命令配置环境变量
重要
使用export命令配置的临时环境变量仅当前会话有效，当会话退出之后所设置的环境变量将会丢失。若需长期保留环境变量，可将export命令配置到对应操作系统的启动配置文件中。
配置AccessKey ID并按回车。
# 将<ACCESS_KEY_ID>替换为您自己的AccessKey ID。 export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID
配置AccessKey Secret并回车。
# 将<ACCESS_KEY_SECRET>替换为您自己的AccessKey Secret。 export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret
验证是否配置成功。
执行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令，如果返回正确的AccessKey ID，则说明配置成功。
Windows系统配置方法
通过图形用户界面GUI
操作步骤
以下为Windows 10中通过图形用户界面设置环境变量的步骤。
在桌面右键单击此电脑，选择属性>高级系统设置>环境变量>系统变量/用户变量>新建，完成以下配置：
变量
示例值
AccessKey ID
变量名：ALIBABA_CLOUD_ACCESS_KEY_ID
变量值：LTAI****************
AccessKey Secret
变量名：ALIBABA_CLOUD_ACCESS_KEY_SECRET
变量值：yourAccessKeySecret
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。
通过命令行提示符CMD
操作步骤
以管理员身份打开命令提示符，并使用以下命令在系统中新增环境变量。
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
其中/M表示系统级环境变量，设置用户级环境变量时可以不携带该参数。
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。
通过Windows PowerShell
在PowerShell中，设置新的环境变量（对所有新会话都有效）：
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User) [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)
为所有用户设置环境变量（需要管理员权限）：
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine) [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)
设置临时的环境变量（仅当前会话有效）：
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID" $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"
在PowerShell中，执行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey，则说明配置成功。
在调用云控制API之前，请首先为RAM用户授予相应资源的操作权限。有关具体操作方式请参见为RAM用户授权。
在实际使用过程中，若要实现权限的精细化管理，您可以创建自定义权限策略。具体操作请参见创建自定义权限策略。
说明
本文示例将以列举专有网络VPC资源为例进行说明：
- 快速授权：授予AliyunCloudControlAPIFullAccess权限，具备管理云控制API所有权限。
- 精细化授权：若您希望实现权限的精细化管理，则只需创建针对列举VPC资源的自定义权限策略：
  列举专有网络VPC资源自定义权限策略
  { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "cloudcontrol:List*", "Resource": "*" }, { "Effect": "Allow", "Action": "vpc:DescribeVpcs", "Resource": "*" } ] }

环境要求

JDK版本 >= 1.8。

引入 SDK

登录SDK中心，选择云控制API产品，例如您将要调用资源列举的API。

在安装页面，所有语言选择Java。然后在快速入门页签中，您可以获取云控制API的 SDK 安装方式。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>cloudcontrol20220830</artifactId>
  <version>1.1.1</version>
</dependency>

编写调用代码

本文展示了如何调用 GetResources接口，以发起列举专有网络 VPC 资源的请求。

初始化请求客户端

在 SDK 中，所有的云控制API均通过 SDK 提供的请求客户端（Client）发起调用。访问云控制API门户，在服务区域中根据所属地域正确填写服务接入地址（Endpoint）。关于服务地址更多信息，请参见支持的地域。本示例以使用AK进行初始化为例，更多初始化方式请参见Java SDK 管理访问凭据。

//      初始化客户端
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//      System.getenv()表示从环境变量获取AccessKey
    .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
    .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
//      服务地址    
config.endpoint = "cloudcontrol.aliyuncs.com";
com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);

//        使用默认凭据链初始化客户端
//        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
//        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//                .setCredential(credentialClient);
//        config.endpoint = "cloudcontrol.aliyuncs.com";
//        com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);

说明

getenv()函数的功能是读取环境变量。当您在机器上设置环境变量名称为ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET时，getenv将能够获取其对应的值。
当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。

定义请求路径

// 请求路径
String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";

说明

请求路径格式为： /api/v1/providers/{provider}/products/{product}/resources/{resourceTypeCode}。

请求路径中的变量说明如下：

字段	说明	示例值
`{provider}`	云厂商名称。目前仅支持 `Aliyun`。	`Aliyun`
`{product}`	产品 Code。通过调用列举产品接口获取。	`VPC`
`{resourceTypeCode}`	资源 Code。通过调用列举产品接口获取。	`VPC`

资源是否存在父资源，可以通过 resourceType 的格式进行判断：

resourceType 格式	说明	示例值
`****`	不包含 `/`，表示该资源没有父资源。	`VPC`
`**/**`	包含`/`，说明该资源存在父资源。例如产品云数据库Redis，拥有资源Redis实例（DBInstance）和数据库账号（DBInstance/Account），其中数据库账号的resourceType为”DBInstance/Account“，说明数据库账号存在父资源，父资源的resourceType为DBInstance，即Redis实例。	`DBInstance/Account`

具体说明，请参见父资源与子资源。

创建请求对象

创建请求对象时，使用的函数名称为<接口名称>Request。通过 request 类的属性设置必要的信息，即 API 中必须要提供的信息。

// 过滤条件（可选）
// java.util.Map < String, Object > filter = TeaConverter.buildMap(
//    new TeaPair("IsDefault", true), // 是否是默认VPC
//    new TeaPair("ResourceGroupId", "<YOUR_RESOURCEGROUPID>"), // 资源组ID
//    new TeaPair("DhcpOptionsSetId", "<YOUR_DHCPOPTIONSSETID>"), // DHCP选项集的ID
//    new TeaPair("VpcId", "<YOUR_VPCID>"), // VPC的ID
//    new TeaPair("VpcName", "<YOUR_VPCNAME>") // VPC的名称
// );
// 创建请求对象
com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
    .setRegionId("cn-hangzhou") // 地域ID
//    .setFilter(filter) // 查询过滤条件
//    .setNextToken("") // 标记当前开始读取的位置
    .setMaxResults(2); // 分页查询时每页行数

发起请求

通过请求客户端调用OpenAPI时，使用的函数名称为<接口名称>WithOptions，其中<接口名称>为OpenAPI名称的首字母小写格式。该函数包含四个参数：请求路径、请求对象、请求头参数和运行时参数。请求对象为上一步创建的请求对象；运行时参数用于配置请求的行为，例如超时设置、代理配置等。

// 运行时参数
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
//        // 忽略对 SSL 证书的验证
//        runtime.ignoreSSL = true;
//        // 代理配置
//        runtime.httpProxy = "http://127.0.0.1:9898";
//        runtime.httpsProxy = "http://user:password@127.0.0.1:8989";
//        runtime.noProxy = "127.0.0.1,localhost";
//        // 连接超时
//        runtime.connectTimeout = 5000;
//        // 读超时
//        runtime.readTimeout = 10000;
//        // 开启自动重试机制
//        runtime.autoretry = true;
//        // 设置自动重试次数
//        runtime.maxAttempts = 3;
// headers 参数，可自定义请求头，覆盖默认值或添加额外的信息。
java.util.Map < String, String > headers = new java.util.HashMap<>();
//        headers.put("x-acs-action", "GetResources"); // 设置接口名称
// 发起请求
GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);

异常处理

Java V2.0 SDK将异常进行了细致的分类，主要划分为TeaUnretryableException和TeaException。

TeaUnretryableException：主要是因为网络问题造成，一般是网络问题达到最大重试次数后抛出。
TeaException：主要以业务报错为主的异常。

重要

建议采取合理的措施来处理异常，例如有效地传播异常信息、记录日志、实施恢复尝试等，以确保系统的健壮性和稳定性。

完整示例代码

package com.aliyun.sample;

import com.aliyun.cloudcontrol20220830.models.*;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.google.gson.Gson;
public class Sample {


    public static com.aliyun.cloudcontrol20220830.Client createClient() throws Exception {
        // 使用默认凭据链初始化客户端，此方式为更安全的无AK方式
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            .setCredential(credential);
        config.endpoint = "cloudcontrol.aliyuncs.com";
        return new com.aliyun.cloudcontrol20220830.Client(config);
    }

    public static void main(String[] args_) throws Exception {

        com.aliyun.cloudcontrol20220830.Client client = Sample.createClient();
        // 请求路径
        String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";
        // 请求对象
        com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
            .setRegionId("cn-hangzhou");
        // 运行时参数    
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        // 自定义请求头参数
        java.util.Map < String, String > headers = new java.util.HashMap < > ();
        try {
            // 发起请求
            GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);
            // 结果打印
            System.out.println(new Gson().toJson(getResourcesResponse.getBody()));
            // 获取 requestId
            System.out.println(getResourcesResponse.body.requestId);
        } catch (TeaException error) {
            // 错误 message
            System.out.println(error.getMessage());
            // 诊断地址
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (TeaUnretryableException ue) {
            ue.printStackTrace();
            // 打印错误信息
            System.out.println(ue.getMessage());
            // 打印请求记录，查询错误发生时的请求信息
            System.out.println(ue.getLastRequest());
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // 错误 message
            System.out.println(error.getMessage());
            // 诊断地址
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
    }
}

常见问题

调用OpenAPI时报错，提示“You are not authorized to perform this operation”。
问题原因：您所使用的AccessKey对应的RAM用户没有权限调用该API。
解决方法：请为该RAM用户授予相应OpenAPI权限。关于如何为RAM用户进行授权，请参见为RAM用户授权。
例如，当您在调用GetResources 时提示“You are not authorized to perform this operation”，您可以创建如下所示的自定义权限策略，并为该RAM用户授予相应的权限。
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudcontrol:List*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "vpc:DescribeVpcs",
      "Resource": "*"
    }
  ]
}
```
调用OpenAPI时报错，提示“Cannot invoke "com.aliyun.credentials.Client.getCredential()" because "this._credential" is null”。
问题原因：没有将AccessKey正确设置环境变量。
解决方法：
设置访问凭据到系统环境
Linux和macOS系统配置方法
通过export命令配置环境变量
重要
使用export命令配置的临时环境变量仅当前会话有效，当会话退出之后所设置的环境变量将会丢失。若需长期保留环境变量，可将export命令配置到对应操作系统的启动配置文件中。
配置AccessKey ID并按回车。
# 将<ACCESS_KEY_ID>替换为您自己的AccessKey ID。 export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID
配置AccessKey Secret并回车。
# 将<ACCESS_KEY_SECRET>替换为您自己的AccessKey Secret。 export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret
验证是否配置成功。
执行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令，如果返回正确的AccessKey ID，则说明配置成功。
Windows系统配置方法
通过图形用户界面GUI
操作步骤
以下为Windows 10中通过图形用户界面设置环境变量的步骤。
在桌面右键单击此电脑，选择属性>高级系统设置>环境变量>系统变量/用户变量>新建，完成以下配置：
变量
示例值
AccessKey ID
变量名：ALIBABA_CLOUD_ACCESS_KEY_ID
变量值：LTAI****************
AccessKey Secret
变量名：ALIBABA_CLOUD_ACCESS_KEY_SECRET
变量值：yourAccessKeySecret
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。
通过命令行提示符CMD
操作步骤
以管理员身份打开命令提示符，并使用以下命令在系统中新增环境变量。
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
其中/M表示系统级环境变量，设置用户级环境变量时可以不携带该参数。
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。
通过Windows PowerShell
在PowerShell中，设置新的环境变量（对所有新会话都有效）：
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User) [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)
为所有用户设置环境变量（需要管理员权限）：
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine) [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)
设置临时的环境变量（仅当前会话有效）：
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID" $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"
在PowerShell中，执行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey，则说明配置成功。

变量	示例值
AccessKey ID	变量名：ALIBABA_CLOUD_ACCESS_KEY_ID 变量值：LTAI****************
AccessKey Secret	变量名：ALIBABA_CLOUD_ACCESS_KEY_SECRET 变量值：yourAccessKeySecret