阿里云SDK调用短信服务API，帮助开发者快速实现安全可靠的短信发送功能。 - 短信服务

在应用开发中，常常需要通过短信向用户发送验证码、通知或推广信息。例如，用户在注册时发送手机验证码，或在订单状态变更时发送通知。本文旨在为您提供一个快速、安全、可靠的SDK集成方式，以API方式调用阿里云短信服务，实现自动化短信发送。

方案架构

调用短信服务API的整体流程涉及到开发者应用、阿里云SDK、身份与权限管理（RAM）以及短信服务本身。

流程的核心逻辑：开发者将阿里云 SDK 集成至应用中，并通过 RAM 为应用分配具有短信服务权限的访问凭证。应用使用该凭证调用阿里云短信服务的API发送请求，阿里云服务端完成鉴权与合规校验后，将消息交由短信网关处理，并通过运营商网络最终将短信送达目标用户手机。

以发送短信（SendMessageToGlobe）接口为例，引导您完成短信服务API调用。您将了解到：

如何创建RAM用户并授权。
如何安装SDK。
如何调用短信服务API。

说明

如果您已经熟悉如何调用API，可直接查阅API目录，调用所需接口。
推荐使用SDK集成的方法对API进行调用。如果您希望自定义封装请求对API进行调用，请参见V3版本请求体&签名机制。

准备工作

准备事项	说明	相关文档
用户权限	您可以通过RAM控制台，单击RAM用户名称查看用户权限。请确保您需要调用API的RAM用户已有短信服务相关权限： AliyunDysmsFullAccess：管理短信服务的权限。	创建RAM用户并完成授权自定义授权信息
`AccessKey ID`	可以通过RAM控制台，单击RAM用户名称进入详情页，点击AccessKey页签，查看AccessKey ID。	创建RAM用户并完成授权
`AccessKey Secret`	创建后不支持二次查看，若本地无备份，建议重新创建一对AccessKey使用。	创建RAM用户并完成授权
账户余额/套餐包余量	确保账户余额充足或套餐包余量充足。您可以在控制台套餐包统计界面查看套餐包余量，或在费用与成本界面查看账户余额。	产品计费

配置凭证

步骤一：创建RAM用户并完成授权

重要

阿里云主账号拥有较高权限，建议您通过RAM用户进行API调用和日常运维。有关RAM用户的更多信息，请参见RAM用户概览。

创建RAM用户：访问创建RAM用户，完成相关名称设置，并选择访问配置为使用永久 AccessKey 访问，单击确定后即可完成RAM用户的创建。请及时保存AccessKey信息。
为RAM用户授权：访问RAM用户列表，找到您所创建的RAM用户，单击操作列的新增授权。在权限策略文本搜索框中输入AliyunDysmsFullAccess后选中此策略，单击确认新增授权，即可完成授权操作。

说明

AliyunDysmsFullAccess：管理短信服务的权限。
AliyunDysmsReadOnlyAccess：只读访问短信服务的权限。
如果您需要新建自定义权限，请参见授权信息。

步骤二：获取访问凭证

请配置环境变量，通过环境变量读取访问密钥（AccessKey）。环境变量配置方法，请参见在Linux、macOS和Windows系统配置环境变量。

说明

为避免在代码中硬编码AccessKey而造成泄露，请通过配置环境变量的方式，来获取AccessKey。
本文代码示例以环境变量名ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET为例，进行后续操作。

步骤三：环境变量配置步骤

Windows系统

在Windows系统中，您可以通过系统属性、CMD或PowerShell配置环境变量。

系统属性

说明

此方式配置的环境变量永久生效。
修改系统环境变量需具备管理员权限。
配置环境变量后不会立即影响已经打开的命令窗口、IDE或其他正在运行的应用程序。您需要重新启动这些程序或者打开新的命令行使环境变量生效。

在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。
在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入ALIBABA_CLOUD_ACCESS_KEY_ID，变量值填入您的AccessKey ID。设置ALIBABA_CLOUD_ACCESS_KEY_SECRET的操作相同。
依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。
打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。
1. CMD查询命令：
```
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
```
2. Windows PowerShell查询命令：
```
echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

CMD

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在CMD中运行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
setx ALIBABA_CLOUD_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

打开一个新的CMD窗口。

在新的CMD窗口运行以下命令，检查环境变量是否生效。

echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以在CMD中运行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
set ALIBABA_CLOUD_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
set ALIBABA_CLOUD_ACCESS_KEY_SECRET=YOUR_ACCESS_KEY_SECRET

您可以在当前会话运行以下命令检查环境变量是否生效。

echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

PowerShell

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以按如下操作。

在PowerShell中运行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
[Environment]::SetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
[Environment]::SetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

打开一个新的PowerShell窗口。

在新的PowerShell窗口运行以下命令，检查环境变量是否生效。

echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以在PowerShell中运行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "YOUR_ACCESS_KEY_SECRET"

您可以在当前会话运行以下命令检查环境变量是否生效。

echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET

Linux系统

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

也可以手动修改~/.bashrc 文件。

手动修改

执行以下命令，打开~/.bashrc 文件。

nano ~/.bashrc

在配置文件中添加以下内容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。

执行以下命令，使变更生效。
```
source ~/.bashrc
```
重新打开一个终端窗口，运行以下命令检查环境变量是否生效。建议您使用SDK前重启IDE。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

执行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

执行以下命令，验证该环境变量是否生效。

echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

macOS系统

添加永久性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。

在终端中执行以下命令，查看默认Shell类型。
```
echo $SHELL
```

根据默认Shell类型进行操作。

Zsh

执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

也可以手动修改~/.zshrc 文件。

手动修改

执行以下命令，打开Shell配置文件。

nano ~/.zshrc

在配置文件中添加以下内容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。

执行以下命令，使变更生效。
```
source ~/.zshrc
```
重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

Bash

执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

也可以手动修改~/.bash_profile 文件。

手动修改

执行以下命令，打开Shell配置文件。

nano ~/.bash_profile

在配置文件中添加以下内容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano编辑器中，按Ctrl + X，接着按Y，再按Enter以保存并关闭文件。

执行以下命令，使变更生效。
```
source ~/.bash_profile
```
重新打开一个终端窗口，运行以下命令检查环境变量是否生效。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

添加临时性环境变量

如果您仅希望在当前会话中使用该环境变量，可以添加临时性环境变量。

以下命令适用于 Zsh 和 Bash。

执行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

执行以下命令，验证该环境变量是否生效。

echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

修改系统环境变量后，请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

安装SDK

本文以Java语言为例，进行后续操作。如果您需要使用其他编程语言，请参见SDK参考。

已安装Java 8或以上版本。
配置Java环境
您可以通过在终端运行以下命令，来检查您的Java环境：
```
java -version
# 如果使用maven管理和构建java项目，还需确保maven已正确安装到您的开发环境中
mvn --version
```
以Windows的CMD为例：
为使用短信服务SDK，您的Java需要在Java 8或以上版本。您可以查看打印信息中的第一行确认Java版本，例如打印信息：openjdk version "16.0.1" 2021-04-20表明当前Java版本为Java 16。如果您当前计算环境没有Java、或版本低于Java 8，请前往Java下载进行下载与安装。
您可以通过配置Maven依赖来安装SDK。请配置以下信息并将 the-latest-version 替换为最新版本号。
```
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dysmsapi20180501</artifactId>
  
  <version>the-latest-version</version>
</dependency>
```
Maven配置步骤
1. 打开您的Maven项目的pom.xml文件。
2. 在<dependencies>标签内添加上述依赖信息。
3. 保存pom.xml文件。
4. 右键项目名称，选择Maven->Reload project，更新项目依赖，Maven会自动下载并添加短信服务SDK到您的项目中。

使用SDK

1. 初始化客户端

阿里云SDK支持多种访问凭据用于初始化客户端，例如AccessKey和STS Token等，更多方式请参见管理访问凭据。本文以AccessKey初始化客户端为例，进行后续操作。

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20180501.Client;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 配置 AccessKey ID，请确保代码运行环境配置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 配置 AccessKey Secret，请确保代码运行环境配置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                // System.getenv()方法表示获取系统环境变量，不要直接在getenv()中填入AccessKey信息。
        
        // 配置 Endpoint。
        config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";

        return new Client(config);
    }
}

2. 构建请求对象

构造API请求并根据您的业务需要传入参数。

说明

请求对象命名规则：{API名称}Request ，例如SendMessageToGlobe接口的请求对象为SendMessageToGlobeRequest。

SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
            .setTo("<YOUR_VALUE>")
            .setMessage("<YOUR_VALUE>");

3. 发起请求

使用SendMessageToGlobe接口完成API请求。

说明

返回对象命名规则：{API名称}Response ，例如SendMessageToGlobe接口的返回对象为SendMessageToGlobeResponse。

SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

您还可以配置请求参数，具体方法请参见发起请求。
关于超时和重试的设置，请参见超时机制和重试机制。
关于SDK异常种类及异常的处理，请参见异常处理。

代码示例

完整代码示例如下：

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20180501.Client;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeResponse;
import static com.aliyun.teautil.Common.toJSONString;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 配置 AccessKey ID，请确保代码运行环境配置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 配置 AccessKey Secret，请确保代码运行环境配置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

        // 配置 Endpoint。
        config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";

        return new Client(config);
    }

    public static void main(String[] args) throws Exception {
        // 初始化请求客户端
        Client client = Sample.createClient();

        // 构造请求对象，请填入请求参数值
        SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
                .setTo("<YOUR_VALUE>")
                .setMessage("<YOUR_VALUE>");

        // 获取响应对象
        SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

        // 响应包含服务端响应的 body 和 headers
        System.out.println(toJSONString(sendSmsResponse));
    }
}

运行后您将会看到对应的输出结果：

{
  "headers": {
    "date": "Tue, 24 Oct 2023 07:47:17 GMT",
    "content-type": "application/json;charset=utf-8",
    "content-length": "263",
    "connection": "keep-alive",
    "keep-alive": "timeout=25",
    "access-control-allow-origin": "*",
    "access-control-expose-headers": "*",
    "x-acs-request-id": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
    "x-acs-trace-id": "29c11fe4c778b74774d5f5602f0e7975",
    "etag": "2a+mcDRTDkXqx9VF7b6U57Q3"
  },
  "statusCode": 200,
  "body": {
    "ResponseCode": "OK",
    "NumberDetail": {
    "Region": "Taiwan",
    "Country": "Taiwan, Province of China",
    "Carrier": "FarEasTone"
  },
    "RequestId": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
    "Segments": "1",
    "ResponseDescription": "OK",
    "To": "88691567****",
    "MessageId": "191921698133637273"
  }
}

API错误码及解决方案

具体内容请参见错误码。

成本与风险说明

成本构成：短信主要按照发送条数计费，不同国家/地区的单价不同。详细价格请参考产品计费。
关键风险：
- 凭据泄露：AccessKey泄露会对该账号下所有资源的安全带来威胁，产生非预期的费用以及恶意勒索等，严重情况下甚至可能给阿里云或其他用户带来危害。具体内容请参见AccessKey泄露处理方案。
- 内容合规：发送的内容必须遵守目标国家/地区的法律法规，否则可能导致发送失败或账户被封禁。

短信服务：首次调用API

方案架构

准备工作

配置凭证

步骤一：创建RAM用户并完成授权

步骤二：获取访问凭证

步骤三：环境变量配置步骤

Windows系统

系统属性

CMD

添加永久性环境变量

添加临时性环境变量

PowerShell

添加永久性环境变量

添加临时性环境变量

Linux系统

添加永久性环境变量

添加临时性环境变量

macOS系统

添加永久性环境变量

Zsh

Bash

添加临时性环境变量

安装SDK

配置Java环境

使用SDK

1. 初始化客户端

2. 构建请求对象

3. 发起请求

代码示例

API错误码及解决方案

成本与风险说明

相关内容