文档

首次调用API

更新时间:

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

API基本信息

短信服务所提供的API基本信息参见如下:

接口版本

2017-05-25

接口风格

RPC

服务接入点

(Endpoint)

全局接入点域名dysmsapi.aliyuncs.com

  • 服务接入点即为您调用短信服务API的URL地址。

  • 请参见服务接入点,根据您的使用地域,选择对应的接入点地址。

说明
  • 如果您已经熟悉如何调用API,可直接查阅API目录,调用所需接口。

  • 推荐使用SDK集成的方法对API进行调用。如果您希望自定义封装请求对API进行调用,请参见V3版本请求体&签名机制

本文以发送短信(SendSms)接口为例,引导您完成短信服务API调用。您将了解到:

  • 如何设置账号权限

  • 如何配置本地开发环境

  • 如何调用短信服务API

账号设置

服务开通

  • 在通过API使用短信服务前,请确保您已开通短信服务并已完成资质申请,具体操作请参见新手指引

  • 在通过API发送短信前,您还需要完成短信签名、短信模板的申请,并等待审核通过。短信签名、短信模板的申请可通过控制台或API完成。具体操作请参见新手指引

为RAM用户开通权限

重要

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

  1. 创建RAM用户

    访问创建RAM用户,完成相关名称设置,并选择访问方式OpenAPI 调用访问,单击确定后即可完成RAM用户的创建。创建时会显示AccessKey信息,请妥善保管。

  2. 为RAM用户授权

    访问RAM用户列表,找到您所创建的RAM用户,单击操作列的添加权限。通过文本框搜索,选择AliyunDysmsFullAccess,单击确认新增授权,完成授权操作。

    说明
    • AliyunDysmsFullAccess:管理短信服务的权限。

    • AliyunDysmsReadOnlyAccess:只读访问短信服务的权限。

    如果您需要新建自定义权限,请参见授权信息

配置开发环境

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

配置Java环境

为使用SDK进行短信服务API的调用,您的Java版本需高于Java 8。您可以通过在终端运行以下命令,来检查您的Java环境:

java -version

若您尚未完成Java环境的配置或Java版本低于Java 8,请参见在Windows搭建Java开发环境

配置SDK

您可以通过配置Maven依赖来安装SDK。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dysmsapi20170525</artifactId>
  <version>3.0.0</version>
</dependency>

初始化请求客户端

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

配置AccessKey

为避免在代码中硬编码访问密钥(AccessKey)而造成泄露,请通过配置环境变量的方式获取AccessKey。环境变量配置方法,请参见在Linux、macOS和Windows系统配置环境变量

说明

您可以通过RAM控制台,单击RAM用户名称,查看AccessKey ID。AccessKey Secret创建后不支持查看,若本地无备份,建议重新创建一对AccessKey ID和AccessKey Secret使用。详情请参见创建AccessKey

本文以环境变量名ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_CLOUD_ACCESS_KEY_SECRET为例,进行后续操作。通过环境变量获取AccessKey的代码示例如下:

Config config = new Config()
        // 请确保代码运行环境配置了相应环境变量
        .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
        .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

配置服务接入点

配置服务接入点代码示例如下:

config.endpoint = "dysmsapi.aliyuncs.com";

请根据您的地域填入相应地址,参见服务接入点

调用API

构建API请求

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

说明

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

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

发送API请求

使用SendSms接口完成API请求。

说明

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

SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);

代码示例

完整代码示例如下:

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"));
        
        // 配置 Endpoint
        config.endpoint = "dysmsapi.aliyuncs.com";

        return new Client(config);
    }

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

        // 构造请求对象,请替换请求参数值
        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));
    }
}

常见问题

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

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

下一步