文档

ECSJavaSDK的通用流程

更新时间:

以云服务器ECS Java SDK查询可用镜像资源的方法DescribeImages为例,介绍编写ECS Java SDK的通用流程。

前提条件

  1. 您已经创建了AccessKey。具体操作,请参见创建AccessKey

  2. 请确保代码运行环境设置了环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。具体配置方法,请参见在Linux、macOS和Windows系统配置环境变量

说明

为避免主账号泄露AccessKey带来的安全风险,建议您创建RAM用户,授予RAM用户云服务器ECS相关的访问权限,再使用RAM用户的AccessKey调用SDK。具体操作,请参见通过RAM用户控制ECS资源访问

背景信息

  • 本文示例中,IClientProfile和IAcsClient两个类包含在aliyun-java-sdk-core中,其他的类均包含在aliyun-java-sdk-ecs中。

  • 本文示例目的是查询云服务器ECS公共镜像,您可以参见镜像相关文档了解什么是公共镜像。更多详情,请参见公共镜像概述

  • 下表列举了旧版SDK与新版SDK的方法、类以及对象之间的区别。若您使用的是旧版SDK,建议您切换为新版SDK,获取最新功能。

    对比项

    新版SDK

    旧版SDK

    提交请求

    getAcsResponse()

    execute()

    存放AccessKey的类

    IClientProfile

    AliyunClient

    存放身份凭据对象

    DefaultProfile.getProfile(RegionId, AccessKey, AccessKeySecret)

    new DefaultAliyunClient(APIUrl, AccessKey, AccessKeySecret)

    包名前缀

    com.aliyuncs

    com.aliyun.api

  • 更多代码示例请参见阿里云代码示例库(CodeSample)

操作步骤

  1. 从IClientProfile类中生成对象Profile。

    Profile对象存放地域、AccessKeyID和AccessKeySecret,如示例中的cn-hangzhou。更多关于地域的信息,请参见地域和可用区

    // 请确保代码运行环境设置了环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。
    IClientProfile profile = DefaultProfile.getProfile("cn-hangzhou",System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
  2. 从IClientProfile类中生成IAcsClient的对象client。

    后续获得response从IClientProfile中获得。

    IAcsClient client = new DefaultAcsClient(profile);
  3. 创建一个对应方法的Request,使用构造函数生成一个默认的类request

    类的命名规则为API方法名加上Request。获得镜像列表的API方法名为DescribeImages,对应的请求类名就是DescribeImagesRequest

    DescribeImagesRequest request = new DescribeImagesRequest();
  4. 设置请求类request的参数。

    通过request类的setXxx方法设置必要的信息,即API中必须要提供的信息,通过setXxx方法设置参数。示例中:

    • DescribeImages的API方法RegionId用来指定地域。

    • DescribeImages的API方法ImageOwnerAlias用来设置要查询的镜像类型。设置setImageOwnerAlias的值为system,表示查询公共镜像。

    request.setImageOwnerAlias("system");
  5. 通过client对象获得对应request响应。

    DescribeImagesResponse response = client.getAcsResponse(request);
    System.out.println(JSON.toJSONString(response));
  6. 调用response中对应的getXxx方法获得返回的参数值。

    假设您需要获取某份镜像的名字,先通过getImages()获得Image对象的集合,再通过遍历等方法取得其中某个镜像的信息,调用getImageName()或者getImageId()获得具体的信息。

    for(DescribeImagesResponse.Image image:response.getImages())
                {
                    System.out.println(image.getImageId());
                    System.out.println(image.getImageName());
                }

    根据API方法的不同,返回的信息中可能会包含多层的信息,如DescribeImages返回的信息中镜像是以一个集合来表示的,集合中存放了每个镜像的信息,汇聚成一个列表。您需要通过getImages()获得Image对象的集合,通过遍历等方法取得其中某个镜像的信息,再调用getXxx方法获得具体的信息。

  7. 使用catch()处理服务器报错和客户端报错。

    • 服务端报错

      catch (ServerException e) {
                  e.printStackTrace();
                                 }
    • 客户端报错

      catch (ClientException e) {
                  System.out.println("ErrCode:" + e.getErrCode());
                  System.out.println("ErrMsg:" + e.getErrMsg());
                  System.out.println("RequestId:" + e.getRequestId());
                                 }

执行结果

  • 全部返回信息如下所示:

    {
        "PageNumber": 1,
        "TotalCount": 43,
        "PageSize": 1,
        "RegionId": "cn-hangzhou",
        "RequestId": "C93F3D9F-CF25-47DF-9C0F-614395E5DCAC",
        "Images": {
            "Image": [
                {
                    "ImageId": "freebsd_11_02_64_30G_alibase_20190722.vhd",
                    "Description": "",
                    "OSNameEn": "FreeBSD  11.2 64 bit",
                    "ProductCode": "",
                    "ResourceGroupId": "",
                    "OSType": "linux",
                    "Architecture": "x86_64",
                    "OSName": "FreeBSD  11.2 64位",
                    "DiskDeviceMappings": {
                        "DiskDeviceMapping": []
                    },
                    "ImageOwnerAlias": "system",
                    "Progress": "100%",
                    "IsSupportCloudinit": false,
                    "Usage": "instance",
                    "CreationTime": "2019-07-23T05:41:06Z",
                    "Tags": {
                        "Tag": []
                    },
                    "ImageVersion": "",
                    "Status": "Available",
                    "ImageName": "freebsd_11_02_64_30G_alibase_20190722.vhd",
                    "IsSupportIoOptimized": true,
                    "IsSelfShared": "",
                    "IsCopied": false,
                    "IsSubscribed": false,
                    "Platform": "Freebsd",
                    "Size": 30
                }
            ]
        }
    }
  • 获取具体返回参数的查询结果,例如ImageIdImageName

    freebsd_11_02_64_30G_alibase_20190722.vhd
    freebsd_11_02_64_30G_alibase_20190722.vhd

完整代码示例

以下为本文示例的完整Java SDK代码。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
import com.alibaba.fastjson.JSON;
import java.util.*;
import com.aliyuncs.ecs.model.v20140526.*;

public class DescribeImages {

    public static void main(String[] args) {
        // 请确保代码运行环境设置了环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。
        // 工程代码泄露可能会导致AccessKey泄露,并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取AccessKey的方式进行调用,建议使用更安全的STS方式。
        DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou",System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);

        DescribeImagesRequest request = new DescribeImagesRequest();
        request.setRegionId("cn-hangzhou");
        request.setImageOwnerAlias("system");
        request.setPageNumber(1);
        request.setPageSize(1);

        try {
            DescribeImagesResponse response = client.getAcsResponse(request);
            System.out.println(JSON.toJSONString(response));
            for(DescribeImagesResponse.Image image:response.getImages())
            {
                System.out.println(image.getImageId());
                System.out.println(image.getImageName());
            }
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            System.out.println("ErrCode:" + e.getErrCode());
            System.out.println("ErrMsg:" + e.getErrMsg());
            System.out.println("RequestId:" + e.getRequestId());
        }

    }
}