V2.0 SDK 和 V1.0 SDK

更新时间:

本文通过生成方案、语言支持、语言拓展、SDK场景化示例等多方面为您详细介绍了阿里云SDK升级前后的差异。如果您之前使用过阿里云SDK集成云产品,发现现在文档中的写法与以前不同,可参考本文了解不同版本SDK差异,若您是初次使用阿里云SDK,请直接使用V2.0版本SDK。

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 示例中心

V1.0 SDK(不推荐)

说明

由于V1.0 SDK存在体验不一致、身份鉴权信息无法隔离等问题,官方不再推荐您继续使用。

以下是V1.0 SDK的简单模型图。

image

阿里云 V1.0 SDK 主要分为三层:

  1. 产品SDK层,处理OpenAPI业务相关的参数。

  2. 核心SDK层,过渡OpenAPI业务参数到HTTP请求参数。

  3. HTTP Client层,真正发起请求的部分。

在使用V1.0 SDK方式集成云产品服务时,我们通常需要引入核心SDK产品SDK

代码示例

当我们同时调用多个不同产品的OpenAPI时,通用的Client对象无法按照产品维度进行隔离,且容易产生线程安全问题。

<!-- ECS sdk -->
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-ecs</artifactId>
    <version>5.11.7</version>
</dependency>
<!-- core sdk -->
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.6.1</version>
</dependency>
package com.example;

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 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(
                "<YOUR-REGION-ID>",
                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
        // );

        // init acs client
        IAcsClient client = new DefaultAcsClient(profile);

        // Create the request to query instance status
        DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest();
        request.setRegionId("<YOUR-REGION-ID>");

        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。

代码示例

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>ecs20140526</artifactId>
  <version>5.1.8</version>
</dependency>
package com.example;

import com.aliyun.tea.TeaException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest;

public class Sample {

    public static void main(String[] args) throws Exception {
        Config config = new Config();
        // 必填,您的 AccessKey ID, 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID
        config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 必填,您的 AccessKey Secret, 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET
        config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // ECS 的 Endpoint, 请参考 https://api.aliyun.com/product/Ecs
        config.setEndpoint("<Endpoint>");
        Client client = new Client(config);
        DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest()
                .setRegionId("<YOUR-REGION-ID>");
        try {
            // 复制代码运行请自行打印 API 的返回值
            client.describeInstanceStatus(request);
        } catch (TeaException error) {
            error.printStackTrace();
        } catch (Exception error) {
            error.printStackTrace();
        }
    }
}

查看SDK的依赖信息

  1. 打开阿里云OpenAPI开发者门户,选择产品与服务,以专有网络为示例。

image

  1. 选择SDK 版本

image

  1. 选择语言,在安装方式中可以查看产品对应语言所需的SDK依赖信息,在概述中查看SDK最新版本。

image