集成SDK

更新时间:2025-03-21 07:25:01

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

环境要求

JDK版本 >= 1.8。

1. 引入SDK

  1. 登录SDK中心,选择将要使用产品,例如您将要调用短信服务 SMS(Short Message Service)API。

  2. 安装页面SDK 代系选择V2.0所有语言选择Java。然后在快速入门页签中,您可以获取短信服务 SMS(Short Message Service)SDK安装方式。image

2. 设置访问凭据

调用阿里云OpenAPI通常需要设置访问凭据,常见凭据类型为AccessKey(简称:AK)临时安全令牌STS Token。为防止凭据泄露,常用的方案是将其存储到环境变量中,更多安全方案请参见访问凭据的安全使用方案。本文以设置环境变量ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_CLOUD_ACCESS_KEY_SECRET为例:

Linux和macOS系统配置方法
Windows系统配置方法

通过export命令配置环境变量

重要

使用export命令配置的临时环境变量仅当前会话有效,当会话退出之后所设置的环境变量将会丢失。若需长期保留环境变量,可将export命令配置到对应操作系统的启动配置文件中。

  • 配置AccessKey ID并按回车。

    # 将<ACCESS_KEY_ID>替换为您自己的AccessKey ID。
    export ALIBABA_CLOUD_ACCESS_KEY_ID=<ACCESS_KEY_ID>
  • 配置AccessKey Secret并回车。

    # 将<ACCESS_KEY_SECRET>替换为您自己的AccessKey Secret。
    export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ACCESS_KEY_SECRET>
  • 验证是否配置成功。

    执行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令,如果返回正确的AccessKey ID,则说明配置成功。

通过图形用户界面GUI
通过命令行提示符CMD
通过Windows PowerShell
  • 操作步骤

    以下为Windows 10中通过图形用户界面设置环境变量的步骤。

    在桌面右键单击此电脑,选择属性>高级系统设置>环境变量>系统变量/用户变量>新建,完成以下配置:

    变量

    示例值

    AccessKey ID

    • 变量名:ALIBABA_CLOUD_ACCESS_KEY_ID

    • 变量值:LTAI4GDty8ab9W4Y1D****

    AccessKey Secret

    • 变量名:ALIBABA_CLOUD_ACCESS_KEY_SECRET

    • 变量值:IrVTNZNy5yQelTETg0cZML3TQn****

  • 测试设置是否成功

    单击开始(或快捷键:Win+R)> 运行(输入 cmd)> 确定(或按 Enter 键),打开命令提示符,执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey,则说明配置成功。

  • 操作步骤

    以管理员身份打开命令提示符,并使用以下命令在系统中新增环境变量。

    setx ALIBABA_CLOUD_ACCESS_KEY_ID LTAI4GDty8ab9W4Y1D**** /M
    setx ALIBABA_CLOUD_ACCESS_KEY_SECRET IrVTNZNy5yQelTETg0cZML3TQn**** /M

    其中/M表示系统级环境变量,设置用户级环境变量时可以不携带该参数。

  • 测试设置是否成功

    单击开始(或快捷键:Win+R)> 运行(输入 cmd)> 确定(或按 Enter 键),打开命令提示符,执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey,则说明配置成功。

PowerShell中,设置新的环境变量(对所有新会话都有效):

[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::User)

为所有用户设置环境变量(需要管理员权限):

[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::Machine)

设置临时的环境变量(仅当前会话有效):

$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "LTAI4GDty8ab9W4Y1D****"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "IrVTNZNy5yQelTETg0cZML3TQn****"

PowerShell中,执行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_IDGet-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey,则说明配置成功。

3. 编写调用代码

本文以调用短信服务 SMS(Short Message Service)SendSms接口为例,关于SendSms接口的API文档,请参见SendSms

3.1 初始化请求客户端

SDK中,所有的OpenAPI均通过SDK提供的请求客户端(Client)发起调用。因此,在调用OpenAPI之前,需要先对请求客户端进行初始化。请求客户端支持多种方式初始化,本示例以使用AK进行初始化为例,更多初始化方式请参见管理访问凭据

com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
        // 必填,System.getenv()表示从环境变量中获取AccessKey ID
        .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
        // 必填,System.getenv()表示从环境变量中获取AccessKey Secret
        .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// endpoint为对应产品的服务接入点    
config.endpoint = "dysmsapi.aliyuncs.com";
// 请求客户端
com.aliyun.dysmsapi20170525.Client dysmsapiClient = new com.aliyun.dysmsapi20170525.Client(config);

3.2 创建请求对象

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

说明

OpenAPI不支持请求参数,则无需创建请求对象。例如,在调用DescribeCdnSubList时,该接口不支持请求参数。

// 创建请求对象并设置入参
com.aliyun.dysmsapi20170525.models.SendSmsRequest sendSmsRequest = new com.aliyun.dysmsapi20170525.models.SendSmsRequest()
        .setSignName("<YOUR_VALUE>")
        .setTemplateCode("<YOUR_VALUE>")
        .setPhoneNumbers("<YOUR_VALUE>")
        .setTemplateParam("<YOUR_VALUE>");
说明

针对部分需要上传文件的OpenAPI,可以通过创建<OpenAPI名称>AdvanceRequest请求对象传递文件流。以视觉智能开放平台-人脸人体的DetectBodyCount接口为例:

com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
        .setImageURLObject(Files.newInputStream(Paths.get("<FILE_PATH>"))); // <FILE_PATH>需替换文件路径

3.3 发起请求

通过请求客户端调用OpenAPI时,建议使用的函数名称为<接口名称>WithOptions,其中<接口名称>OpenAPI名称的首字母小写格式。该函数包含两个参数:一个为请求对象,另一个为运行时参数。请求对象为上一步创建的请求对象;运行时参数用于配置请求的行为,例如超时设置、代理配置等。更多信息,请参见进阶配置

说明

OpenAPI不支持请求参数,则在发起请求时无需传递请求对象。例如,在调用DescribeCdnSubList时,函数只需传入运行时参数。

OpenAPI返回对象的命名方式为:<OpenAPI名称>Response,例如SendSms该接口的返回对象为SendSmsResponse。

//创建运行时参数
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
//发起请求
com.aliyun.dysmsapi20170525.models.SendSmsResponse resp = client.sendSmsWithOptions(sendSmsRequest, runtime);
说明

针对部分需要本地上传文件的OpenAPI,需调用函数<接口名称>Advance发起请求,其中<接口名称>OpenAPI名称的首字母小写格式以调用视觉智能开放平台-人脸人体的DetectBodyCount接口为例:

com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);

3.4 异常处理

Java SDK将异常进行了细致的分类,主要划分为TeaUnretryableExceptionTeaException。

  • TeaUnretryableException:主要是因为网络问题造成,一般是网络问题达到最大重试次数后抛出。

  • TeaException:主要以业务报错为主的异常。

更多关于异常处理的介绍,请参见异常处理

重要

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

完整代码示例

通用接口调用示例
上传文件接口调用示例
import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.Common;
import com.aliyun.teautil.models.RuntimeOptions;
public class Sample {
    /**
     * 使用AK/SK初始化账号Client
     *
     * @return Client
     * @throws Exception
     */
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 必填,System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")表示从环境变量中获取AccessKey ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 必填,System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")表示从环境变量中获取AccessKey Secret。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "dysmsapi.aliyuncs.com";
        return new Client(config);
    }
    public static void main(String[] args_) {
        try {
            Client client = Sample.createClient();
            //创建请求对象并设置入参
            SendSmsRequest sendSmsRequest = new SendSmsRequest()
                    .setSignName("test********")
                    .setTemplateCode("SMS**********")
                    .setPhoneNumbers("131********")
                    .setTemplateParam("{\"code\":\"1234\"}");
            //创建运行时配置对象
            RuntimeOptions runtime = new RuntimeOptions();
            //发起请求
            SendSmsResponse resp = client.sendSmsWithOptions(sendSmsRequest, runtime);
            System.out.println(Common.toJSONString(resp));
        } catch (TeaUnretryableException ue) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            ue.printStackTrace();
            // 打印错误信息
            System.out.println(ue.getMessage());
            // 打印请求记录,查询错误发生时的请求信息
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getCode());
            // 打印错误信息,错误信息中包含 RequestId
            System.out.println(e.getMessage());
            // 打印服务端返回的具体错误内容
            System.out.println(e.getData());
        } catch (Exception e) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            e.printStackTrace();
        }
    }
}
/**
 * <dependency>
 *   <groupId>com.aliyun</groupId>
 *   <artifactId>facebody20191230</artifactId>
 *   <version>5.1.2</version>
 * </dependency>
 */

import com.aliyun.tea.*;
import com.google.gson.Gson;

import java.nio.file.Files;
import java.nio.file.Paths;

public class Sample {

    public static com.aliyun.facebody20191230.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // 必填,System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")表示从环境变量中获取AccessKey ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 必填,System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")表示从环境变量中获取AccessKey Secret。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.endpoint = "facebody.cn-shanghai.aliyuncs.com";
        return new com.aliyun.facebody20191230.Client(config);
    }

    public static void main(String[] args_) {
        try {
            com.aliyun.facebody20191230.Client client = Sample.createClient();
            com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
                    .setImageURLObject(Files.newInputStream(Paths.get("D:\\test.jpg")));  // 需替换为实际的文件路径
            com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
            com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);
            System.out.println(new Gson().toJson(resp.body));
        } catch (TeaUnretryableException ue) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            ue.printStackTrace();
            // 打印错误信息
            System.out.println(ue.getMessage());
            // 打印请求记录,查询错误发生时的请求信息
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getCode());
            // 打印错误信息,错误信息中包含 RequestId
            System.out.println(e.getMessage());
            // 打印服务端返回的具体错误内容
            System.out.println(e.getData());
        } catch (Exception e) {
            // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
            e.printStackTrace();
        }
    }
}

常见问题

  • 调用OpenAPI时报错,提示“You are not authorized to perform this operation”。

    问题原因:您所使用的AccessKey对应的RAM用户没有权限调用该API。

    解决方法:请为该RAM用户授予相应OpenAPI权限。关于如何为RAM用户进行授权,请参见RAM用户授权

    例如,当您在调用SendSms时提示“You are not authorized to perform this operation”,您可以创建如下所示的自定义权限策略,并为该RAM用户授予相应的权限。

    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "dysms:SendSms",
          "Resource": "*"
        }
      ]
    }
  • 调用OpenAPI时报错,提示“The specified endpoint cant operate this region. ”。

    问题原因:您所调用的OpenAPI不支持在初始化请求客户端时填写的Endpoint。

    解决方法:请查看Endpoint配置,修改Endpoint后重新调用OpenAPI。

  • 调用OpenAPI时报错,提示“java.lang.NullPointerException\n at com.aliyun.teaopenapi.Client.doRequest(Client.java:916)\n at com.aliyun.teaopenapi.Client.callApi(Client.java:1207)”。

    问题原因:您的AccessKey未正确传递。

    解决方法:在初始化请求客户端时,检查是否正确传递AccessKey。请注意System.getenv("XXX")表示从环境变量中获取XXX的值。

更多SDK使用过程中的报错问题解决方案,请参见常见问题

  • 本页导读 (1)
  • 环境要求
  • 1. 引入SDK
  • 2. 设置访问凭据
  • 3. 编写调用代码
  • 3.1 初始化请求客户端
  • 3.2 创建请求对象
  • 3.3 发起请求
  • 3.4 异常处理
  • 完整代码示例
  • 常见问题