泛化调用_阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

阿里云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	请求参数显示`"in":"query"`时，通过setQuery传递参数。
setBody	请求参数显示`"in":"body"`或`"in": "formData"`时，通过setBody传递参数。在使用请求体（body）传递参数时，需要根据请求体的类型设置`reqBodyType`的值。
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));
    }
}