Skip to content

README_zh.md

Latest commit

 

History

History
193 lines (171 loc) · 8.84 KB

README_zh.md

File metadata and controls

193 lines (171 loc) · 8.84 KB

阿里云开发者Java工具套件

Maven Central Build Status codecov Codacy Badge Appveyor Badge

English document

欢迎使用阿里云开发者工具套件（SDK）。阿里云Java SDK让您不用复杂编程即可访问云服务器、云监控等多个阿里云服务。这里向您介绍如何获取阿里云Java SDK并开始调用。 如果您在使用 SDK 的过程中遇到任何问题，欢迎前往阿里云SDK问答社区提问，提问前请阅读提问引导。亦可在当前 GitHub 提交 Issues。

环境准备

  1. 要使用阿里云Java SDK，您需要一个云账号以及一对Access Key ID和Access Key Secret。 请在阿里云控制台中的AccessKey管理页面上创建和查看您的Access Key，或者联系您的系统管理员。
  2. 要使用阿里云SDK访问某个产品的API，您需要事先在阿里云控制台中开通这个产品。
  3. 阿里云Java SDK需要1.6以上的JDK。

SDK获取和安装

无论您要使用哪个产品的开发工具包，都必须安装SDK核心库。比如，对云服务器SDK的调用，您需要安装SDK核心库和云服务器的SDK。

通过Maven来管理项目依赖(推荐)

如果您使用Apache Maven来管理Java项目，只需在项目的pom.xml文件加入相应的依赖项即可。您可以在阿里云开发工具包中下载各云产品的Maven依赖。 以最新版本的SDK核心库和最新版本的Ecs SDK为例，您只需在pom.xml中声明这两个开发工具包，如下所示：

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>[4.3.2,10.0.0)</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-ecs</artifactId>
    <version>[4.16.0,10.0.0)</version>
</dependency>

如果 maven 没有从中央存储库下载 jar 包，则需要将此依赖项添加到pom.xml文件中，否则将报告 NoClassDefFoundError 异常

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.5</version>
</dependency>

开始调用

以下这个代码示例向您展示了调用阿里云Java SDK的3个主要步骤：

  1. 创建DefaultAcsClient实例并初始化。
  2. 创建API请求并设置参数。
  3. 发起请求并处理应答或异常。

使用 AccessKey 调用

 package com.testprogram;
 import com.aliyuncs.profile.DefaultProfile;
 import com.aliyuncs.DefaultAcsClient;
 import com.aliyuncs.IAcsClient;
 import com.aliyuncs.exceptions.ClientException;
 import com.aliyuncs.exceptions.ServerException;
 import com.aliyuncs.ecs.model.v20140526.*;
 public class Main {
     public static void main(String[] args) {
         // 创建DefaultAcsClient实例并初始化
         DefaultProfile profile = DefaultProfile.getProfile(
             "<your-region-id>",          // 地域ID
             "<your-access-key-id>",      // RAM账号的AccessKey ID
             "<your-access-key-secret>"); // RAM账号Access Key Secret
         IAcsClient client = new DefaultAcsClient(profile);
         // 创建API请求并设置参数
         DescribeInstancesRequest request = new DescribeInstancesRequest();
         request.setPageSize(10);
         // 发起请求并处理应答或异常
         DescribeInstancesResponse response;
         try {
             response = client.getAcsResponse(request);
             for (DescribeInstancesResponse.Instance instance:response.getInstances()) {
                 System.out.println(instance.getPublicIpAddress());
             }
         } catch (ServerException e) {
             e.printStackTrace();
         } catch (ClientException e) {
             e.printStackTrace();
         }
     }
 }

使用 Bearertoken 调用

只有 CCC 这个产品支持此方式

 package com.testprogram;
 import com.aliyuncs.profile.DefaultProfile;
 import com.aliyuncs.DefaultAcsClient;
 import com.aliyuncs.IAcsClient;
 import com.aliyuncs.exceptions.ClientException;
 import com.aliyuncs.exceptions.ServerException;
 import com.aliyuncs.ccc.model.v20170705.ListPhoneNumbersRequest;
 import com.aliyuncs.ccc.model.v20170705.ListPhoneNumbersResponse;
 public class Main {
     public static void main(String[] args) {
         // 创建DefaultAcsClient实例并初始化
         DefaultProfile profile = DefaultProfile.getProfile(
             "<your-region-id>"         // 地域ID
         ); 
         BearerTokenCredentials bearerTokenCredential = new BearerTokenCredentials("<your-bearer-token>");
         DefaultAcsClient client = new DefaultAcsClient(profile, bearerTokenCredential);
         // 创建API请求并设置参数
         ListPhoneNumbersRequest request = new ListPhoneNumbersRequest();
         request.getInstanceId("yourId");
         request.setOutboundOnly(true);
         // 发起请求并处理应答或异常
         ListPhoneNumbersResponse response; 
         try {
             response = client.getAcsResponse(request);
             // 自己的逻辑
         } catch (ServerException e) {
             e.printStackTrace();
         } catch (ClientException e) {
             e.printStackTrace();
         }
     }
 }

调试

如果存在环境变量 DEBUG=sdk ，所有的http请求和响应都将启用调试输出。

配置连接池

默认多个SDK client共享一个连接池，可以在初始化client阶段设置连接池参数

// 创建DefaultAcsClient实例并初始化
DefaultProfile profile = DefaultProfile.getProfile(
"<your-region-id>",          // 地域ID
"<your-access-key-id>",      // RAM账号的AccessKey ID
"<your-access-key-secret>"); // RAM账号Access Key Secret

// 多个SDK client共享一个连接池，此处设置该连接池的参数，
// 比如每个host的最大连接数，超时时间等
HttpClientConfig clientConfig = HttpClientConfig.getDefault();
clientConfig.setMaxRequestsPerHost(6);
clientConfig.setConnectionTimeoutMillis(10000L);

profile.setHttpClientConfig(clientConfig);
IAcsClient client = new DefaultAcsClient(profile);

超时机制

Request 设置 -> Client 设置 -> 默认，优先级依次降低； 默认连接超时为5秒，读超时为10秒；

//Client超时设置，对当前所有request有效
HttpClientConfig clientConfig = HttpClientConfig.getDefault();
clientConfig.setReadTimeoutMillis(readTimeoutMillis);
clientConfig.setConnectionTimeoutMillis(connectionTimeoutMillis);
IClientProfile profile = DefaultProfile.getProfile(regionId, accesskeyId, accesskeySecret);
profile.setHttpClientConfig(clientConfig);
DefaultAcsClient client = new DefaultAcsClient(profile);

// request超时设置，仅对当前请求有效
request.setSysReadTimeout(readTimeoutMillis);
request.setConnectionTimeoutMillis(connectionTimeoutMillis);

HTTPS配置

优先级: Request > Client > Default

支持以下配置项:

  1. 是否校验服务端证书
  2. 设置X509TrustManagers(信任的服务端证书)
  3. 设置 KeyManagers(客户端证书)
// Client HTTPS配置
HttpClientConfig clientConfig = HttpClientConfig.getDefault();
// 设置不校验服务端证书
clientConfig.setIgnoreSSLCerts(true);
// 设置自定义的TrustManagers
clientConfig.setX509TrustManagers(clientTrustManagers);
// 设置自定义的KeyManagers
clientConfig.setKeyManagers(clientKeyManagers);

IClientProfile profile = DefaultProfile.getProfile(regionId, accesskeyId, accesskeySecret);
profile.setHttpClientConfig(clientConfig);
DefaultAcsClient client = new DefaultAcsClient(profile);
 
// Request HTTPS配置(ApacheHttpClient会忽略Request级别的HTTPS配置)
request.setIgnoreSSLCerts(true);
request.setX509TrustManagers(requestTrustManagers);
request.setKeyManagers(requestKeyManagers);

client.getAcsResponse(request)