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

您可以通过SDK快速集成，调用API从而使用短信服务。

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

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

说明

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

准备工作

准备事项	说明	相关文档
资质申请	您可以在控制台资质管理页面查看资质信息。若无可用资质，请申请并等待审核通过。	申请资质
`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系统
在Windows系统中，您可以通过系统属性、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
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>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段不固定且不定期变更。若您的网络环境特殊，建议您安全策略方面调整为放行该域名。

视频介绍

下一步

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

准备工作

配置凭证

Windows系统

系统属性

CMD

添加永久性环境变量

添加临时性环境变量

PowerShell

添加永久性环境变量

添加临时性环境变量

Linux系统

添加永久性环境变量

添加临时性环境变量

macOS系统

添加永久性环境变量

Zsh

Bash

添加临时性环境变量

安装SDK

配置Java环境

使用SDK

1. 初始化客户端

2. 构建请求对象

3. 发起请求

代码示例

常见问题

如何查看AccessKey ID和AccessKey Secret？

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

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

视频介绍

下一步

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