ECS Java V2.0 SDK调用示例 - 云服务器 ECS

本文以调用查询一台或多台ECS实例的详细信息（DescribeInstances）接口为例，为您介绍Java V2.0 SDK的安装和使用。

前提条件

由于阿里云账号（主账号）拥有资源的所有权限，其AccessKey一旦泄露风险巨大，所以建议您使用满足最小化权限需求的RAM用户的AccessKey。具体操作方式请参见创建AccessKey。
给RAM用户授予操作云服务器ECS相关资源的权限。本文提供的示例代码为查询示例，所以选择AliyunECSReadonlyAccess系统权限策略，您在使用的时候可以根据业务需求进行自定义授权。
1. 使用自定义权限策略。
  关于如何创建自定义权限策略，请参见创建自定义权限策略和授权信息。
  云服务器ECS依据最佳实践提供了一些自定义权限策略示例，您可以参考这些示例以快速创建符合自身业务需求的自定义权限策略，具体详情请参见云服务器ECS自定义权限策略参考。
2. 使用系统权限策略。
  云服务器ECS支持的所有系统权限策略及其对应的权限描述，请参见云服务器 ECS系统权限策略参考。
在环境变量中配置AccessKey，具体操作步骤请参见在Linux、macOS和Windows系统配置环境变量。

安装SDK

Java SDK支持多种安装方式，本示例以Apache Maven安装方式为例，更多安装方式获取方式，请参见SDK中心。

打开Maven项目的pom.xml文件，在<dependencies>节点中加入依赖配置，并刷新Maven配置。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>ecs20140526</artifactId>
  <version>5.3.0</version>
</dependency>

使用SDK

1. 初始化客户端

阿里云SDK支持多种访问凭据用于初始化客户端，例如AccessKey和STS Token等，更多方式请参见管理访问凭据。本示例以通过AccessKey初始化客户端为例。

import com.aliyun.ecs20140526.Client;
import com.aliyun.teaopenapi.models.Config;

public class Sample {
    private static Client createClient() throws Exception {
        Config config = new Config()
                // 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // Endpoint 请参考 https://api.aliyun.com/product/Ecs
                .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        return new Client(config);
    }
}

2. 构建接口的请求对象

在构建请求对象之前，请查看该接口的API文档获取参数信息。

说明

请求对象命名规则：{API名称}Request，例如DescribeInstances该接口的请求对象为DescribeInstancesRequest。

// 构造请求对象
DescribeInstancesRequest request = new DescribeInstancesRequest().setRegionId("cn-hangzhou");

3. 发起调用

通过客户端调用OpenAPI时，支持设置运行时参数，例如超时配置、代理配置等，更多信息请查看进阶配置。

说明

接口返回对象命名规则：{API名称}Response，例如DescribeInstances该接口的返回对象为DescribeInstancesResponse。

// 设置运行时参数
RuntimeOptions runtime = new RuntimeOptions();
// 调用 DescribeInstances 接口
DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
System.out.println(response.body.toMap());

4. 异常处理

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

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

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

5. 完整示例

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeInstancesRequest;
import com.aliyun.ecs20140526.models.DescribeInstancesResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    private static Client createClient() throws Exception {
        Config config = new Config()
                // 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 必填，请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // Endpoint 请参考 https://api.aliyun.com/product/Ecs
                .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        return new Client(config);
    }

    public static void main(String[] args) {
        try {
            Client client = Sample.createClient();
            // 构造请求对象
            DescribeInstancesRequest request = new DescribeInstancesRequest()
                    .setRegionId("cn-hangzhou");
            // 设置运行时参数
            RuntimeOptions runtime = new RuntimeOptions();
            // 调用 DescribeInstances 接口
            DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
            System.out.println(response.body.toMap());
        } catch (TeaUnretryableException ue) {
            // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
            ue.printStackTrace();
            // 打印错误信息
            System.out.println(ue.getMessage());
            // 打印请求记录，查询错误发生时的请求信息
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getCode());
            // 打印错误信息，错误信息中包含 RequestId
            System.out.println(e.getMessage());
            // 打印服务端返回的具体错误内容
            System.out.println(e.getData());
        } catch (Exception e) {
            // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
            e.printStackTrace();
        }
    }
}

云服务器 ECS：ECS Java V2.0 SDK调用示例