Java如何异步调用阿里云OpenAPI-阿里云帮助中心

在调用OpenAPI时，建议采用在项目中集成SDK的方式。使用SDK可以简化开发流程，实现功能的快速集成，同时有效降低维护成本。集成阿里云SDK主要包括三个步骤：引入阿里云SDK、设置访问凭据以及使用SDK。本文将详细介绍SDK集成的具体流程。

使用说明

Java（异步）SDK只有V2.0代系SDK。
请求参数中包含上传文件或文件URL地址的OpenAPI不支持通过Java（异步）SDK进行调用，需使用Java SDK进行调用。

环境要求

JDK版本 >= 1.8。

引入SDK

登录SDK中心，选择将要使用的产品，例如您将要调用云服务器 ECS的API。
根据以下截图中的步骤获取SDK的安装方式。

设置访问凭据

调用阿里云 OpenAPI 时，通常需要配置访问凭据。常见的凭据类型包括AccessKey（简称AK）和临时安全令牌STS Token。为防止凭据泄露，常用的方案是将其存储到环境变量中，更多安全方案请参见访问凭据的安全使用方案。本文以设置环境变量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，则说明配置成功。

说明

配置完成之后需要重启开发工具。

使用SDK

本文以调用云服务器 ECS的DescribeInstances接口为例，关于DescribeInstances接口的API文档，请参见DescribeInstances。

1. 初始化异步客户端

在SDK中，所有OpenAPI的调用均通过SDK提供的异步客户端进行。因此在调用OpenAPI之前，必须首先对异步客户端进行初始化。同时在初始化异步客户端的过程中，还需传入访问凭据提供者，本文以使用静态凭据提供者为例，更多访问凭据提供者获取方式，请参见管理访问凭据。

说明

该方式创建的异步客户端实例是线程安全的，能够在多线程环境中安全使用。实际开发过程中建议采用单例模式封装异步客户端，确保在整个应用程序生命周期中针对相同的访问凭据和Endpoint仅初始化一个异步客户端实例。
SDK中默认使用连接池管理异步HTTP请求，当默认配置不符合您的业务需求时，您可通过重新配置连接池参数进行调整。具体操作请参见HTTP连接池配置。
异步客户端的更多配置，请参见进阶配置。

// 静态凭证提供者
com.aliyun.auth.credentials.provider.StaticCredentialProvider provider = com.aliyun.auth.credentials.provider.StaticCredentialProvider.create(
  com.aliyun.auth.credentials.Credential.builder()                                                                                                                                        
  // 必填，此处以从环境变量中获取AccessKey ID为例
  .accessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
  // 必填，此处以从环境变量中获取AccessKey Secret为例
  .accessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
  .build());

// 初始化客户端
com.aliyun.sdk.service.ecs20140526.AsyncClient client = com.aliyun.sdk.service.ecs20140526.AsyncClient.builder()
  .credentialsProvider(provider)
  .overrideConfiguration(
    darabonba.core.client.ClientOverrideConfiguration.create()
    // Endpoint配置
    .setEndpointOverride("ecs.cn-hangzhou.aliyuncs.com")
  )
  .build();

2. 创建请求对象

在调用OpenAPI进行参数传递时，需使用SDK提供的请求对象来实现参数的传递。OpenAPI请求对象的命名方式为：<OpenAPI名称>Request，例如DescribeInstances该接口的请求对象为DescribeInstancesRequest。有关请求参数的详细信息，请查阅相应的API文档，本示例API文档请参见DescribeInstances。

com.aliyun.sdk.service.ecs20140526.models.DescribeInstancesRequest describeInstancesRequest = com.aliyun.sdk.service.ecs20140526.models.DescribeInstancesRequest.builder()
  .regionId("cn-hangzhou")
  .build();

3. 发起请求

通过请求客户端调用OpenAPI时，调用的函数名为OpenAPI名称的camelCase形式，该函数的入参为上一步创建的请求对象。

try {
  java.util.concurrent.CompletableFuture<com.aliyun.sdk.service.ecs20140526.models.DescribeInstancesResponse> response = client.describeInstances(describeInstancesRequest);
  // 获取结果
  response.thenAccept(resp -> {
    System.out.println(new Gson().toJson(resp));
  }).exceptionally(throwable -> { 
    // Handling exceptions
    System.out.println(throwable.getMessage());
    return null;
  });
} finally {
  client.close();
}

4. 异常处理

在异步编程中，会抛ClientException、ServerException。

重要

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

本文涉及代码的完整示例

import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.sdk.gateway.pop.exception.PopClientException;
import com.aliyun.sdk.service.ecs20140526.AsyncClient;
import com.aliyun.sdk.service.ecs20140526.models.DescribeInstancesRequest;
import com.aliyun.sdk.service.ecs20140526.models.DescribeInstancesResponse;
import darabonba.core.client.ClientOverrideConfiguration;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

import com.google.gson.Gson;
import darabonba.core.exception.ValidateException;

public class Demo {

  private static final String ACCESS_KEY_ID = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
  private static final String ACCESS_KEY_SECRET = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
  private static final String ENDPOINT = "ecs.cn-hangzhou.aliyuncs.com";

  public static void main(String[] args) {
    // 初始化凭证提供者
    StaticCredentialProvider credentialProvider = StaticCredentialProvider.create(
      Credential.builder()
      .accessKeyId(ACCESS_KEY_ID)
      .accessKeySecret(ACCESS_KEY_SECRET)
      .build()
    );

    // 构建异步客户端配置
    AsyncClient client = AsyncClient.builder()
      .credentialsProvider(credentialProvider)
      .overrideConfiguration(
        ClientOverrideConfiguration.create()
        .setEndpointOverride(ENDPOINT)
      )
      .build();

    // 构建请求对象
    DescribeInstancesRequest request = DescribeInstancesRequest.builder()
      .regionId("cn-hangzhou")
      .build();

    try {
      // 发起异步请求
      CompletableFuture<DescribeInstancesResponse> response = client.describeInstances(request);
      response.thenAccept(resp -> {
        System.out.println(new Gson().toJson(resp));
      }).exceptionally(throwable -> { 
        // Handling exceptions
        System.out.println(throwable.getMessage());
        return null;
      });
    } finally {
      client.close();
    }
  }
}

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