泛化调用
阿里云SDK支持一种通用的方式调用OpenAPI,此方式被称为泛化调用。本文将为您详细介绍如何使用泛化调用访问OpenAPI。
特点
轻量:仅需安装阿里云核心SDK,无需额外安装云产品SDK。
简单:只需构造通用的请求参数对象,然后利用通用请求客户端调用通用函数发起请求,调用结果也以通用格式返回。
更多介绍,请参见泛化调用与特化调用。
使用说明
使用泛化调用时,建议先查看OpenAPI元数据,获取OpenAPI的API风格、请求参数、资源路径等信息。具体信息,请参见OpenAPI元数据。
安装核心SDK
在pom.xml中添加以下依赖安装核心SDK,最新版本请参见Maven Repository。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>tea-openapi</artifactId>
<version>0.3.6</version>
</dependency>
调用OpenAPI
初始化请求客户端
通过创建com.aliyun.teaopenapi.Client
对象初始化请求客户端,并通过该Client发起OpenAPI调用。在初始化客户端时,也支持使用Credentials工具,关于Credentials工具的更多信息,请参见管理访问凭据。
请求客户端对象无需手动销毁,会自动被垃圾回收机制回收。
// 1.初始化请求客户端
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// 设置请求地址
config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
// 支持通过Config在初始化Client阶段设置配置(可选)。
// Client HTTPS 参数设置
// config.setProtocol("HTTPS");
// 地域ID
// config.setRegionId("<regionId>");
// Client代理参数设置
// config.setHttpProxy("http://127.0.0.1:9898");
// config.setHttpsProxy("http://user:password@127.0.0.1:8989");
// config.setNoProxy("127.0.0.1,localhost");
// Client 超时参数设置
// 连接超时默认 5 * 1000 毫秒
// config.setConnectTimeout(5000);
// 读超时默认 10 * 1000 毫秒
// config.setReadTimeout(10000);
com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);
// // 使用Credentials工具
// com.aliyun.credentials.models.Config credentialConfig = new com.aliyun.credentials.models.Config();
// credentialConfig.setType("access_key");
// credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
// credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
// com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// .setCredential(credentialClient)
// .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
// com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);
配置OpenAPI信息
通过com.aliyun.teaopenapi.models.Params
配置OpenAPI的基本信息,比如OpenAPI的风格、API版本、请求方式等信息。以调用DescribeInstanceTypeFamilies接口为例:
com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
.setStyle("RPC") // API风格:RPC或ROA。
.setVersion("2014-05-26") // API版本号。
.setMethod("POST") // 请求方法。
.setAction("DescribeInstanceTypeFamilies") // API名称。
.setPathname("/") // API资源路径,RPC接口默认"/",ROA接口从OpenAPI元数据中data.path获取资源路径。
.setProtocol("HTTPS") // 请求协议:HTTPS或HTTP,建议使用HTTPS。
.setAuthType("AK") // 认证类型,默认即可。当OpenAPI支持匿名请求时,您可以传入 Anonymous 发起匿名请求。
.setReqBodyType("json") // 请求body的类型,支持byte、json、formData。
.setBodyType("json"); // 返回数据格式,支持json。
配置请求参数
通过com.aliyun.teaopenapi.models.OpenApiRequest
配置请求参数,请求参数支持通过Query、Body或Stream传参,如何选择传参方式可根据元数据中的介绍选择,例如DescribeInstanceTypeFamilies
的请求参数RegionId在元数据中信息为{"name":"RegionId","in":"query",...}}
,其中"in":"query"
表示RegionId通过Query传递。
传参方式 | 描述 |
setQuery | 请求参数显示 |
setBody | 请求参数显示 |
setStream | 在需要上传文件的场景,可通过setStream传递文件流。 |
// 场景一:设置查询参数(query)
java.util.Map<String, Object> queries = new java.util.HashMap<>();
queries.put("RegionId", "cn-hangzhou");
com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
.setQuery(com.aliyun.openapiutil.Client.query(queries));
// // 场景二:设置body参数,reqBodyType的值为json
// java.util.Map<String, Object> body = new java.util.HashMap<>();
// body.put("param1", "value1");
// body.put("param2", "value2");
// com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
// .setBody(com.aliyun.openapiutil.Client.query(body));
// // 场景三:设置body参数,reqBodyType的值为formData
// java.util.Map<String, Object> formData = new java.util.HashMap<>();
// formData.put("param1", "value1");
// formData.put("param2", "value2");
// com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
// .setBody(formData);
// // 场景四:使用Stream参数传递文件流
// com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
// .setStream("<FILE_STREAM>"); // <FILE_STREAM>需替换为实际的文件流
发起请求
通过com.aliyun.teaopenapi.Client
调用callApi发起请求。同时,在请求过程中支持设置运行时参数,例如超时配置、代理配置等,更多信息请查看进阶配置。
// 设置运行时选项
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// 忽略对 SSL 证书的验证
// runtime.ignoreSSL = true;
// 开启自动重试机制
// runtime.autoretry = true;
// 设置自动重试次数
// runtime.maxAttempts = 3;
// 连接超时
// runtime.connectTimeout = 5000;
// 读取超时
// runtime.readTimeout = 10000;
// 返回值为Map类型,可从Map中获得三类数据:body、headers、statusCode(HTTP返回的状态码 )。
java.util.Map<String, ?> response = client.callApi(params, request, runtime);
System.out.println(new com.google.gson.Gson().toJson(response));
代码示例
示例:调用RPC风格的API
以调用ECS的DescribeInstanceTypeFamilies接口为例,展示如何使用泛化调用方式。
import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;
import java.util.HashMap;
import java.util.Map;
import static com.aliyun.openapiutil.Client.query;
public class Sample {
public static void main(String[] args) throws Exception {
Config config = new Config()
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
.setEndpoint("ecs-cn-hangzhou.aliyuncs.com");
Client client = new Client(config);
Params params = new Params()
.setStyle("RPC") // API风格
.setVersion("2014-05-26") // API版本号
.setMethod("POST") // 请求方法
.setAction("DescribeInstanceTypeFamilies") // API名称
.setPathname("/")
.setProtocol("HTTPS")
.setAuthType("AK")
.setReqBodyType("json")
.setBodyType("json");
// 设置查询参数
Map<String, Object> queries = new HashMap<>();
queries.put("RegionId", "cn-hangzhou");
// 设置运行时选项
RuntimeOptions runtime = new RuntimeOptions();
OpenApiRequest request = new OpenApiRequest()
.setQuery(query(queries));
// 返回值为Map类型,可从Map中获得三类数据:body、headers、statusCode(HTTP返回的状态码 )。
Map<String, ?> response = client.callApi(params, request, runtime);
System.out.println(new Gson().toJson(response));
}
}
示例:调用RESTful(ROA)风格的API
以调用容器服务查询集群列表信息为例,展示如何使用泛化调用。
import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;
import java.util.HashMap;
import java.util.Map;
import static com.aliyun.openapiutil.Client.query;
public class Test3 {
public static void main(String[] args_) throws Exception {
Config config = new Config()
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
.setEndpoint("cs.cn-hangzhou.aliyuncs.com");
Client client = new Client(config);
Params params = new Params()
.setStyle("ROA") // API风格
.setVersion("2015-12-15") // API版本号
.setAction("DescribeClustersV1") // API名称
.setPathname("/api/v1/clusters") // API资源路径
.setMethod("GET") // 请求方法
.setProtocol("HTTPS")
.setAuthType("AK")
.setReqBodyType("json")
.setBodyType("json");
// 设置查询参数
Map<String, Object> queries = new HashMap<>();
queries.put("name", "cluster-demo");
OpenApiRequest request = new OpenApiRequest()
.setQuery(query(queries));
RuntimeOptions runtime = new RuntimeOptions();
// 返回值为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
Map<String, ?> response = client.callApi(params, request, runtime);
System.out.println(new Gson().toJson(response));
}
}