V1.0 SDK和V2.0 SDK
如果您之前使用过阿里云SDK集成云产品,发现现在文档中的写法与以前不同,可参考本文了解不同版本SDK差异,若您是初次使用阿里云SDK,请直接使用V2.0版本SDK。
V1.0 SDK
以下是V1.0 SDK的简单模型图。
阿里云 V1.0 SDK 主要分为三层:
产品 SDK 层,处理 OpenAPI 业务相关的参数。
核心 SDK 层,过渡 OpenAPI 业务参数到 HTTP 请求参数。
HTTP Client 层,真正发起请求的部分。
在使用SDK方式集成云产品服务时,我们通常需要引入核心依赖SDK和产品SDK。由于V1.0 SDK存在体验不一致、身份鉴权信息无法隔离等问题,官方不再推荐您继续使用。
代码示例
当我们同时调用多个不同产品的OpenAPI时,通用的Client
对象无法按照产品维度进行隔离,且容易产生线程安全问题。
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.google.gson.Gson;
import java.util.*;
import com.aliyuncs.ecs.model.v20140526.*;
public class DescribeInstanceStatus {
public static void main(String[] args) {
// Please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET are set.
DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
/** use STS Token
DefaultProfile profile = DefaultProfile.getProfile(
"<your-region-id>", // The region ID
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), // The AccessKey ID of the RAM account
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), // The AccessKey Secret of the RAM account
System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN")); // STS Token
**/
IAcsClient client = new DefaultAcsClient(profile);
DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest();
request.setRegionId("cn-hangzhou");
try {
DescribeInstanceStatusResponse response = client.getAcsResponse(request);
System.out.println(new Gson().toJson(response));
} 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());
}
}
}
V2.0 SDK
阿里云 V1.0 SDK 是较早使用的版本,不少老用户习惯于 V1.0 的开发。阿里云 V2.0 SDK是通过总结开发者在 V1.0 中遇到的一系列问题后重新开发的一版 SDK,新增了许多特性,主要以易于用户理解,降低用户接入成本并提升 SDK 的健壮性为主。
V2.0 SDK 是基于阿里云自研的 DSL 语言 Darabonba 生成。DSL 的灵活性不仅可以进行更多表达,而且通过解析 DSL 生成的 AST 也能抹平阿里云不同产品生产的不同风格 OpenAPI 的差异,轻松实现 OpenAPI 到 SDK 的生成。与 V1.0 相比,阿里云 V2.0 SDK 具备以下新特性:
使用体验一致:解决 V1.0 SDK 中产品 OpenAPI 风格不同(RPC或ROA)造成使用方式不一致的问题。升级版 SDK 中所有云产品的 SDK 使用方式相同,使用体验一致。
开发成本降低:通过 DSL 使 SDK 具备逻辑表达能力,解决了V1.0 SDK 与 SDK Core耦合性高的问题,降低了开发者因为 SDK 的升级带来的开发成本。
身份和鉴权信息隔离:每个云产品的 SDK 提供一个 Client 对象,通过实例化 Client 对象就可以调用云产品的所有 API。通过这样的方式,不仅解决了V1.0 SDK 单 Client 容易造成线程安全的问题,同时通过该方式使每个云产品之间身份和鉴权信息隔离,从而解决了用户使用V1.0 SDK 造成的 profile 信息在不同产品之间混用导致的权限管理问题。用户也可以根据不同云产品 OpenAPI 的情况配置不同参数,例如服务地域、超时时间、HTTP 代理、重试配置等。
支持复杂场景:V2.0 SDK 支持更复杂的 OpenAPI 使用场景,例如智能视觉开放平台的人脸人体(FaceBody)功能需要上传图片到 OSS 以后,通过生成的链接对图片进行人工智能分析处理,就可以通过V2.0 SDK 将上传鉴权、上传图片、图片分析三个操作组合,从而简化 OpenAPI 的使用。
提供场景化示例:V2.0 SDK 不仅为 SDK 中的所有的 OpenAPI 请求生成相应的示例,同时也通过对 SDK 中的多个 OpenAPI 请求进行组合,从而提供 SDK 的场景化示例,这样的示例不仅可以帮助开发者降低接入 SDK 的成本,也可以帮助开发者更好地理解云产品的业务场景。
因此,对于新用户建议直接使用 V2.0 SDK,老用户也建议尽早迁移到 V2.0 SDK。
代码示例
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* 使用AK&SK初始化账号Client
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.ecs20140526.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// 必填,您的 AccessKey ID
.setAccessKeyId(accessKeyId)
// 必填,您的 AccessKey Secret
.setAccessKeySecret(accessKeySecret);
// Endpoint 请参考 https://api.aliyun.com/product/Ecs
config.endpoint = "ecs-cn-hangzhou.aliyuncs.com";
return new com.aliyun.ecs20140526.Client(config);
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
// 工程代码泄露可能会导致 AccessKey 泄露,并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取 AccessKey 的方式进行调用,仅供参考,建议使用更安全的 STS 方式。更多鉴权访问方式,请参见V2.0 Java SDK身份验证章节。
com.aliyun.ecs20140526.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest describeInstanceStatusRequest = new com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest()
.setRegionId("cn-hangzhou");
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
// 复制代码运行请自行打印 API 的返回值
client.describeInstanceStatusWithOptions(describeInstanceStatusRequest, runtime);
} catch (TeaException error) {
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
} catch (Exception _error) {
TeaException error = new TeaException(_error.getMessage(), _error);
// 如有需要,请打印 error
com.aliyun.teautil.Common.assertAsString(error.message);
}
}
}
V1.0 vs V2.0
对比项 | V1.0 SDK | V2.0 SDK |
生成方案 | 基于模板生成,各编程语言之间采用不同的模板方案,各个语言之间功能完备程度不一致,使用体验不一。 | 基于 DSL 语言 Darabonba 方案生成。新方案通过 DSL 语言进行统一的中间表达,并进行了语法校验,使用体验一致。 |
语言支持 | 大部分云产品的老版本 SDK 无法支持超过3门以上的主流语言。 | 支持主流 6 门语言的 SDK 生成。 |
语言扩展 | 模板化生成,扩展难度太高,老版本 SDK 很难扩展新语言。 | 新语言生成器只需接入 DSL 语言的 AST 即可完成扩展,未来还会新增更多的语言。 |
SDK 示例 | 各语言间的代码示例不一致,不能保证代码的正确性。 | 各语言间的代码在逻辑行为上保持一致,通过中间语言来统一生成,具有校验能力,有效保证示例代码的准确性。 |
SDK 场景化示例 | 多语言场景化示例编写困难,极少有产品提供,覆盖语言数极少。 | 通过 DSL 一次编写就能生成多语言的 SDK 场景化示例,可以协助开发者极大的简化 SDK 使用的理解成本,更多示例请参见SDK 示例中心。 |