快速使用短信服务API_短信服务(SMS)-阿里云帮助中心

准备工作

准备事项	说明	相关文档

准备事项	说明	相关文档
资质申请	您可以在控制台资质管理页面查看资质信息。若无可用资质，请申请并等待审核通过。	申请资质
`SignName` 短信签名	您可以在控制台签名管理页面获取签名名称。若无可用签名，请申请并等待审核通过。	申请短信签名 CreateSmsSign
`TemplateCode` 短信模板	您可以在控制台模板管理页面获取模板CODE。若无可用模板，请申请并等待审核通过。	申请短信模板 CreateSmsTemplate
用户权限	您可以通过RAM控制台，单击RAM用户名称查看用户权限。请确保您需要调用API的RAM用户已有短信服务相关权限： AliyunDysmsFullAccess：管理短信服务的权限。	创建RAM用户为RAM用户授权自定义授权信息
`AccessKey ID`	您可以通过RAM控制台，单击RAM用户名称查看AccessKey ID。	创建AccessKey
`AccessKey Secret`	创建后不支持二次查看，若本地无备份，建议重新创建一对AccessKey使用。	创建AccessKey

配置凭证

创建有短信服务管理权限的RAM用户，并创建AccessKey。
说明
阿里云主账号拥有较高权限，强烈建议您通过RAM用户进行API调用和日常运维。
创建RAM用户并授权
1. 创建RAM用户并创建访问密钥（AccessKey）
  访问创建RAM用户，设置用户账号信息，并选择访问方式为使用永久 AccessKey 访问，单击确定，通过安全验证后即可完成RAM用户的创建。RAM用户创建成功后会显示AccessKey ID和AccessKey Secret，请及时保管。
2. 为RAM用户授权
  访问RAM用户列表，找到您所创建的RAM用户，单击操作列的添加权限。通过文本框搜索，选择AliyunDysmsFullAccess，单击确认新增授权，完成授权操作。
使用RAM用户AccessKey配置环境变量。本文以环境变量名ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET为例，进行后续操作。
说明
为避免在代码中硬编码AccessKey而造成泄露，强烈建议您通过配置环境变量的方式获取AccessKey。
环境变量配置步骤
Windows系统
Linux系统
macOS系统
在Windows系统中，您可以通过系统属性、CMD或PowerShell配置环境变量。
系统属性
CMD
PowerShell

说明
此方式配置的环境变量永久生效。
修改系统环境变量需具备管理员权限。
配置环境变量后不会立即影响已经打开的命令窗口、IDE或其他正在运行的应用程序。您需要重新启动这些程序或者打开新的命令行使环境变量生效。
在Windows系统桌面中按Win+Q键，在搜索框中搜索编辑系统环境变量，单击打开系统属性界面。
在系统属性窗口，单击环境变量，然后在系统变量区域下单击新建，变量名填入ALIBABA_CLOUD_ACCESS_KEY_ID，变量值填入您的AccessKey ID。设置ALIBABA_CLOUD_ACCESS_KEY_SECRET的操作相同。
依次单击三个窗口的确定，关闭系统属性配置页面，完成环境变量配置。
打开CMD（命令提示符）窗口或Windows PowerShell窗口，执行如下命令检查环境变量是否生效。
CMD查询命令：

echo %ALIBABA_CLOUD_ACCESS_KEY_ID% echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

Windows PowerShell查询命令：

echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET

添加永久性环境变量
添加临时性环境变量

如果您希望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%

添加永久性环境变量
添加临时性环境变量

如果您希望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
添加永久性环境变量
添加临时性环境变量

如果您希望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
添加永久性环境变量
添加临时性环境变量

如果您希望API Key环境变量在当前用户的所有新会话中生效，可以添加永久性环境变量。
在终端中执行以下命令，查看默认Shell类型。

echo $SHELL

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

执行以下命令来将环境变量设置追加到 ~/.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_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>dysmsapi20170525</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.dysmsapi20170525.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。中国站请使用dysmsapi.aliyuncs.com
        config.endpoint = "dysmsapi.aliyuncs.com";

        return new Client(config);
    }
}

2. 构建请求对象

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

说明

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

SendSmsRequest sendSmsRequest = new SendSmsRequest()
            .setPhoneNumbers("1390000****")
            .setSignName("阿里云")
            .setTemplateCode("SMS_15305****")
            // TemplateParam为序列化后的JSON字符串。其中\"表示转义后的双引号。
            .setTemplateParam("{\"name\":\"张三\",\"number\":\"1390000****\"}");

3. 发起请求

使用SendSms接口完成API请求。

说明

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

SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);

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

代码示例

完整代码示例如下：

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
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"));
                // System.getenv()方法表示获取系统环境变量，不要直接在getenv()中填入AccessKey信息。
        
        // 配置 Endpoint。中国站使用dysmsapi.aliyuncs.com
        config.endpoint = "dysmsapi.aliyuncs.com";

        return new Client(config);
    }

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

        // 构造API请求对象，请替换请求参数值
        SendSmsRequest sendSmsRequest = new SendSmsRequest()
                .setPhoneNumbers("1390000****")
                .setSignName("阿里云")
                .setTemplateCode("SMS_15305****")
                .setTemplateParam("{\"name\":\"张三\",\"number\":\"1390000****\"}"); // TemplateParam为序列化后的JSON字符串。

        // 获取响应对象
        SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);

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

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

{
  "headers": {
    "access-control-allow-origin": "*",
    "date": "Mon, 17 Jul 2023 16:21:50 GMT",
    "content-length": "110",
    "keep-alive": "timeout=25",
    "x-acs-request-id": "F59B3F78-D9CD-5D01-A9CC-AE5C921ED9C0",
    "connection": "keep-alive",
    "content-type": "application/json;charset=utf-8",
    "etag": "1MzEw7RSXKXTkIJ1thYGmCw0",
    "access-control-expose-headers": "*",
    "x-acs-trace-id": "5ecfe30b412fb6e09a86d651ccbe13db"
  },
  "statusCode": 200,
  "body": {
    "bizId": "695425589610909881^0",
    "code": "OK",
    "message": "OK",
    "requestId": "F59B3F78-D9CD-5D01-A9CC-AE5C921ED9C0"
  }
}

常见问题

如何查看AccessKey ID和AccessKey Secret？

AccessKey Secret创建后不支持查看，若本地无备份，建议重新创建一对AccessKey ID和AccessKey Secret使用。

如何自定义封装HTTP请求，然后使用`curl`命令或Postman等工具进行API调用？

阿里云SDK已经封装了签名、超时、重试等机制，我们建议您使用SDK进行集成，降低开发成本。如果您需要自行封装请求来进行API测试，请参见V3版签名机制和SendSms请求示例。

短信服务API调用阿里云的IP服务器地址是固定的吗？

短信服务接口对外只提供域名地址形式，没有提供固定的调用IP地址。中国站请使用域名dysmsapi.aliyuncs.com，HTTP调用使用端口80，HTTPS调用使用端口443。您的网络IP不必报备至阿里云侧，只要能ping通上述地址即可，其对应的IP段不固定且不定期变更。若您的网络环境特殊，建议您安全策略方面调整为放行该域名。

视频介绍

首次调用API

下一步

通过OpenAPI门户进行在线调试，请访问短信服务在线调试入口。
批量发送短信，请使用SendBatchSms接口。
了解短信服务其他应用场景，请参见SDK示例。
发送富媒体短信，请了解什么是多媒体短信。
获取短信发送量等统计数据，请访问业务统计。
获取短信发送状态结果或用户回复的短信内容，请配置回执消息。