Tolan/sendmsg/docs/阿里云短信服务Python SDK调用指南.md

阿里云短信服务 Python SDK 调用指南

前置准备

步骤	说明	参考链接
1. 查看 API 文档	了解 SendSms 接口参数	API 文档
2. 创建 RAM 用户	建议使用 RAM 用户而非主账号	RAM 用户概览
3. 创建 AccessKey	获取 AccessKey ID 和 Secret	创建访问密钥

环境配置

Python 版本要求

• Python >= 3.7

安装 SDK

pip install alibabacloud_dysmsapi20170525==4.3.0

最新版本：https://pypi.org/project/alibabacloud_dysmsapi20170525/

环境变量配置

环境变量名	说明	示例值
ALIBABA_CLOUD_ACCESS_KEY_ID	AccessKey ID	LTAI5t...
ALIBABA_CLOUD_ACCESS_KEY_SECRET	AccessKey Secret	xxx...

推荐使用无 AK 方式（凭据配置），详见：凭据配置文档

代码示例

同步调用示例

# -*- coding: utf-8 -*-
import os
import sys
from typing import List
from alibabacloud_dysmsapi20170525.client import Client as Dysmsapi20170525Client
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dysmsapi20170525 import models as dysmsapi_20170525_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient

class Sample:
    @staticmethod
    def create_client() -> Dysmsapi20170525Client:
        """
        使用凭据初始化账号 Client
        @return: Client
        """
        # 使用凭据客户端（推荐方式，支持无 AK）
        credential = CredentialClient()
        config = open_api_models.Config(
            credential=credential
        )
        # 配置 Endpoint
        config.endpoint = 'dysmsapi.aliyuncs.com'
        return Dysmsapi20170525Client(config)
    
    @staticmethod
    def main(args: List[str]) -> None:
        # 初始化客户端
        client = Sample.create_client()
        
        # 构造请求对象
        send_sms_request = dysmsapi_20170525_models.SendSmsRequest(
            phone_numbers='1390000****',           # 接收短信的手机号
            sign_name='阿里云',                    # 短信签名
            template_code='SMS_15305****',         # 短信模板代码
            template_param='{"name":"张三","number":"1390000****"}'  # 模板参数（JSON 字符串）
        )
        
        try:
            # 发送短信
            response = client.send_sms_with_options(
                send_sms_request, 
                util_models.RuntimeOptions()
            )
            # 打印响应
            print(response)
        except Exception as error:
            # 错误处理
            print(f"错误信息: {error.message}")
            if hasattr(error, 'data') and error.data:
                print(f"诊断地址: {error.data.get('Recommend')}")
            UtilClient.assert_as_string(error.message)

if __name__ == '__main__':
    Sample.main(sys.argv[1:])

异步调用示例

import asyncio
from alibabacloud_dysmsapi20170525.client import Client as Dysmsapi20170525Client
from alibabacloud_dysmsapi20170525 import models as dysmsapi_20170525_models
from alibabacloud_tea_util import models as util_models

class Sample:
    @staticmethod
    async def main_async(args: List[str]) -> None:
        client = Sample.create_client()
        send_sms_request = dysmsapi_20170525_models.SendSmsRequest(
            phone_numbers='1390000****',
            sign_name='阿里云',
            template_code='SMS_15305****',
            template_param='{"name":"张三"}'
        )
        
        try:
            # 异步调用
            response = await client.send_sms_with_options_async(
                send_sms_request, 
                util_models.RuntimeOptions()
            )
            print(response)
        except Exception as error:
            print(f"错误信息: {error.message}")

# 运行异步示例
if __name__ == '__main__':
    asyncio.run(Sample.main_async(sys.argv[1:]))

使用环境变量直接配置（传统方式）

import os
from alibabacloud_tea_openapi import models as open_api_models

# 直接使用 AccessKey（不推荐，建议使用凭据客户端）
config = open_api_models.Config(
    access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
    access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
config.endpoint = 'dysmsapi.aliyuncs.com'

请求参数说明

参数	类型	必填	说明
phone_numbers	String	是	接收短信的手机号，多个号码用逗号分隔
sign_name	String	是	短信签名，需在控制台审核通过
template_code	String	是	短信模板代码，需在控制台审核通过
template_param	String	否	模板参数，JSON 格式字符串

响应格式

# 响应对象结构
response.body.request_id      # 请求 ID
response.body.biz_id          # 业务流水号
response.body.code            # 状态码（OK 表示成功）
response.body.message         # 状态描述

响应字段说明

字段	类型	说明
biz_id	String	业务流水号，用于查询发送状态
code	String	状态码，OK 表示成功
message	String	状态描述
request_id	String	请求 ID，用于问题排查

异常处理

from Tea.exceptions import UnretryableException, TeaException

try:
    response = client.send_sms_with_options(request, util_models.RuntimeOptions())
except UnretryableException as e:
    # 网络异常
    print(f"网络异常: {e}")
except TeaException as e:
    # 业务异常
    print(f"业务异常: {e.message}")
    if e.data:
        print(f"诊断地址: {e.data.get('Recommend')}")
except Exception as e:
    # 其他异常
    print(f"其他异常: {e}")

注意事项

1. 凭据配置：推荐使用 CredentialClient 进行无 AK 配置，更安全
2. 环境变量：如使用传统方式，确保设置 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET
3. 签名和模板：需在阿里云控制台提前申请并审核通过
4. 模板参数：必须是有效的 JSON 字符串，参数名需与模板中的变量名一致
5. 异步调用：使用 send_sms_with_options_async 进行异步调用，需要配合 asyncio

相关链接

• SDK 源码仓库
• SDK 示例代码
• API 文档
• 凭据配置文档