qcloudsms python sdk
Project description
腾讯云短信 Python SDK
===
## 腾讯短信服务
目前`腾讯云短信`为客户提供`国内短信`、`国内语音`和`海外短信`三大服务,腾讯云短信SDK支持以下操作:
### 国内短信
国内短信支持操作:
- 单发短信
- 指定模板单发短信
- 群发短信
- 指定模板群发短信
- 拉取短信回执和短信回复状态
> `Note` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限,量大客户可以使用此功能批量拉取,其他客户不建议使用。
### 海外短信
海外短信支持操作:
- 单发短信
- 指定模板单发短信
- 群发短信
- 指定模板群发短信
- 拉取短信回执和短信回复状态
> `Note` 海外短信和国内短信使用同一接口,只需替换相应的国家码与手机号码,每次请求群发接口手机号码需全部为国内或者海外手机号码。
### 语音通知
语音通知支持操作:
- 发送语音验证码
- 发送语音通知
- 上传语音文件
- 按语音文件fid发送语音通知
- 指定模板发送语音通知类
## 开发
### 准备
在开始开发云短信应用之前,需要准备如下信息:
- [x] 获取SDK AppID和AppKey
云短信应用SDK `AppID`和`AppKey`可在[短信控制台](https://console.cloud.tencent.com/sms)的应用信息里获取,如您尚未添加应用,请到[短信控制台](https://console.cloud.tencent.com/sms)中添加应用。
- [x] 申请签名
一个完整的短信由短信`签名`和短信正文内容两部分组成,短信`签名`须申请和审核,`签名`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
- [x] 申请模板
同样短信或语音正文内容`模板`须申请和审核,`模板`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
### 安装
#### pip
qcloudsms_py采用pip进行安装,要使用qcloudsms功能, 只需要执行:
```shell
pip install qcloudsms_py
```
#### 手动
1. 手动下载或clone最新版本qcloudsms_py代码
2. 在qcloudsms_py目录运行 `python setup.py install`或直接把qcloudsms_py所在目录加入`sys.path`
> `Note` python2/python3都支持
### 文档
若您对接口存在疑问,可以查阅:
* [API开发指南](https://cloud.tencent.com/document/product/382/5808)
* [SDK文档](https://qcloudsms.github.io/qcloudsms_py/)
* [错误码](https://cloud.tencent.com/document/product/382/3771)
### 示例
- **准备必要参数**
```python
# 短信应用SDK AppID
appid = 1400009099 # SDK AppID是1400开头
# 短信应用SDK AppKey
appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad"
# 需要发送短信的手机号码
phone_numbers = ["21212313123", "12345678902", "12345678903"]
# 短信模板ID,需要在短信应用中申请
template_id = 7839 # NOTE: 这里的模板ID`7839`只是一个示例,真实的模板ID需要在短信控制台中申请
# 签名
sms_sign = "腾讯云" # NOTE: 这里的签名"腾讯云"只是一个示例,真实的签名需要在短信控制台中申请,另外签名参数使用的是`签名内容`,而不是`签名ID`
```
- **单发短信**
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPError
sms_type = 0 # Enum{0: 普通短信, 1: 营销短信}
ssender = SmsSingleSender(appid, appkey)
try:
result = ssender.send(sms_type, 86, phone_numbers[0],
"【腾讯云】您的验证码是: 5678", extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 如需发送海外短信,同样可以使用此接口,只需将国家码 `86` 改写成对应国家码号。
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **指定模板ID单发短信**
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPError
ssender = SmsSingleSender(appid, appkey)
params = ["5678"] # 当模板没有参数时,`params = []`
try:
result = ssender.send_with_param(86, phone_numbers[0],
template_id, params, sign=sms_sign, extend="", ext="") # 签名参数未提供或者为空时,会使用默认签名发送短信
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **群发**
```python
from qcloudsms_py import SmsMultiSender
from qcloudsms_py.httpclient import HTTPError
sms_type = 0 # Enum{0: 普通短信, 1: 营销短信}
msender = SmsMultiSender(appid, appkey)
try:
result = msender.send(sms_type, "86", phone_numbers,
"【腾讯云】您的验证码是: 5678", extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **指定模板ID群发**
```python
from qcloudsms_py import SmsMultiSender
from qcloudsms_py.httpclient import HTTPError
msender = SmsMultiSender(appid, appkey)
params = ["5678"]
try:
result = msender.send_with_param(86, phone_numbers,
template_id, params, sign=sms_sign, extend="", ext="") # 签名参数未提供或者为空时,会使用默认签名发送短信
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note:`群发一次请求最多支持200个号码,如有对号码数量有特殊需求请联系腾讯云短信技术支持(QQ:3012203387)。
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **发送语音验证码**
```python
from qcloudsms_py import SmsVoiceVerifyCodeSender
from qcloudsms_py.httpclient import HTTPError
vvcsender = SmsVoiceVerifyCodeSender(appid, appkey)
try:
result = vvcsender.send("86", phone_numbers[0], "5678",
playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 语音验证码发送只需提供验证码数字,例如当msg=“5678”时,您收到的语音通知为“您的语音验证码是5678”,如需自定义内容,可以使用语音通知。
- **发送语音通知**
```python
from qcloudsms_py import SmsVoicePromptSender
from qcloudsms_py.httpclient import HTTPError
vpsender = SmsVoicePromptSender(appid, appkey)
try:
result = vpsender.send("86", phone_numbers[0], 2, "5678",
playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
- **拉取短信回执以及回复**
```python
from qcloudsms_py import SmsStatusPuller
from qcloudsms_py.httpclient import HTTPError
max_num = 10 # 单次拉取最大量
spuller = SmsStatusPuller(appid, appkey)
try:
# 拉取短信回执
callback_result = spuller.pull_callback(max_num)
# 拉取回复
reply_result = spuller.pull_reply(max_num)
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(callback_result)
print(reply_result)
```
> `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387),量大客户可以使用此功能批量拉取,其他客户不建议使用。
- **拉取单个手机短信状态**
```python
from qcloudsms_py import SmsMobileStatusPuller
from qcloudsms_py.httpclient import HTTPError
begin_time = 1511125600 # 开始时间(unix timestamp)
end_time = 1511841600 # 结束时间(unix timestamp)
max_num = 10 # 单次拉取最大量
mspuller = SmsMobileStatusPuller(appid, appkey)
try:
# 拉取短信回执
callback_result = mspuller.pull_callback("86", phone_numbers[0],
begin_time, end_time, max_num)
# 拉取回复
reply_result = mspuller.pull_reply("86", phone_numbers[0],
begin_time, end_time, max_num)
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(callback_result)
print(reply_result)
```
> `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387),量大客户可以使用此功能批量拉取,其他客户不建议使用。
- **发送海外短信**
海外短信与国内短信发送类似, 发送海外短信只需替换相应国家码。
- **上传语音文件**
```python
from qcloudsms_py import VoiceFileUploader
from qcloudsms_py.httpclient import HTTPError
# Note: 语音文件大小上传限制400K字节
with open("/path/to/example.mp3", "rb") as f:
content = f.read()
uploader = VoiceFileUploader(appid, appkey)
try:
result = uploader.upload(content, content_type="mp3")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
# 上传成功后,result里会带有语音文件的fid
print(result)
```
> `Note` '语音文件上传'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
- **按语音文件fid发送语音通知**
```python
from qcloudsms_py import FileVoiceSender
from qcloudsms_py.httpclient import HTTPError
# Note:这里fid来自`上传语音文件`接口返回的响应,要按语音
# 文件fid发送语音通知,需要先上传语音文件获取fid
fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3"
fvsender = FileVoiceSender(appid, appkey)
try:
result = fvsender.send(fid, phone_numbers[0],
nationcode="86", playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 按'语音文件fid发送语音通知'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
- **指定模板发送语音通知**
```python
from qcloudsms_py import TtsVoiceSender
from qcloudsms_py.httpclient import HTTPError
template_id = 12345
params = ["5678"]
tvsender = TtsVoiceSender(appid, appkey)
Try:
result = tvsender.send(template_id, params, phone_numbers[0],
nationcode="86", playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
#### 使用代理
有的环境需要使用代理才能上网,可以指定HTTPSimpleClient的proxy参数来实现, 示例如下:
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPSimpleClient, HTTPError
httpclient = HTTPSimpleClient(proxy="www.proxysever.com:8080")
ssender = SmsSingleSender(appid, appkey, httpclient=httpclient)
template_id = 7839
params = ["5678"]
try:
result = ssender.send_with_param(86, phone_numbers[0],
template_id, params, sign=sms_sign, extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
#### 统一创建对象
短信和语音各类的对象可以通过 `qcloudsms_py.QcloudSms` 统一创建,这种
方式可以避免创建对象时多次传入参数`appid` 和 `appkey`, 示例如下:
```python
from qcloudsms_py import QcloudSms
# 创建QcloudSms对象
qcloudsms = QcloudSms(appid, appkey)
# 创建单发短信(SmsSingleSender)对象
ssender = qcloudsms.SmsSingleSender()
# 创建上传语音文件(VoiceFileUploader)对象
uploader = qcloudsms.VoiceFileUploader()
```
===
## 腾讯短信服务
目前`腾讯云短信`为客户提供`国内短信`、`国内语音`和`海外短信`三大服务,腾讯云短信SDK支持以下操作:
### 国内短信
国内短信支持操作:
- 单发短信
- 指定模板单发短信
- 群发短信
- 指定模板群发短信
- 拉取短信回执和短信回复状态
> `Note` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限,量大客户可以使用此功能批量拉取,其他客户不建议使用。
### 海外短信
海外短信支持操作:
- 单发短信
- 指定模板单发短信
- 群发短信
- 指定模板群发短信
- 拉取短信回执和短信回复状态
> `Note` 海外短信和国内短信使用同一接口,只需替换相应的国家码与手机号码,每次请求群发接口手机号码需全部为国内或者海外手机号码。
### 语音通知
语音通知支持操作:
- 发送语音验证码
- 发送语音通知
- 上传语音文件
- 按语音文件fid发送语音通知
- 指定模板发送语音通知类
## 开发
### 准备
在开始开发云短信应用之前,需要准备如下信息:
- [x] 获取SDK AppID和AppKey
云短信应用SDK `AppID`和`AppKey`可在[短信控制台](https://console.cloud.tencent.com/sms)的应用信息里获取,如您尚未添加应用,请到[短信控制台](https://console.cloud.tencent.com/sms)中添加应用。
- [x] 申请签名
一个完整的短信由短信`签名`和短信正文内容两部分组成,短信`签名`须申请和审核,`签名`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
- [x] 申请模板
同样短信或语音正文内容`模板`须申请和审核,`模板`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
### 安装
#### pip
qcloudsms_py采用pip进行安装,要使用qcloudsms功能, 只需要执行:
```shell
pip install qcloudsms_py
```
#### 手动
1. 手动下载或clone最新版本qcloudsms_py代码
2. 在qcloudsms_py目录运行 `python setup.py install`或直接把qcloudsms_py所在目录加入`sys.path`
> `Note` python2/python3都支持
### 文档
若您对接口存在疑问,可以查阅:
* [API开发指南](https://cloud.tencent.com/document/product/382/5808)
* [SDK文档](https://qcloudsms.github.io/qcloudsms_py/)
* [错误码](https://cloud.tencent.com/document/product/382/3771)
### 示例
- **准备必要参数**
```python
# 短信应用SDK AppID
appid = 1400009099 # SDK AppID是1400开头
# 短信应用SDK AppKey
appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad"
# 需要发送短信的手机号码
phone_numbers = ["21212313123", "12345678902", "12345678903"]
# 短信模板ID,需要在短信应用中申请
template_id = 7839 # NOTE: 这里的模板ID`7839`只是一个示例,真实的模板ID需要在短信控制台中申请
# 签名
sms_sign = "腾讯云" # NOTE: 这里的签名"腾讯云"只是一个示例,真实的签名需要在短信控制台中申请,另外签名参数使用的是`签名内容`,而不是`签名ID`
```
- **单发短信**
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPError
sms_type = 0 # Enum{0: 普通短信, 1: 营销短信}
ssender = SmsSingleSender(appid, appkey)
try:
result = ssender.send(sms_type, 86, phone_numbers[0],
"【腾讯云】您的验证码是: 5678", extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 如需发送海外短信,同样可以使用此接口,只需将国家码 `86` 改写成对应国家码号。
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **指定模板ID单发短信**
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPError
ssender = SmsSingleSender(appid, appkey)
params = ["5678"] # 当模板没有参数时,`params = []`
try:
result = ssender.send_with_param(86, phone_numbers[0],
template_id, params, sign=sms_sign, extend="", ext="") # 签名参数未提供或者为空时,会使用默认签名发送短信
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **群发**
```python
from qcloudsms_py import SmsMultiSender
from qcloudsms_py.httpclient import HTTPError
sms_type = 0 # Enum{0: 普通短信, 1: 营销短信}
msender = SmsMultiSender(appid, appkey)
try:
result = msender.send(sms_type, "86", phone_numbers,
"【腾讯云】您的验证码是: 5678", extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **指定模板ID群发**
```python
from qcloudsms_py import SmsMultiSender
from qcloudsms_py.httpclient import HTTPError
msender = SmsMultiSender(appid, appkey)
params = ["5678"]
try:
result = msender.send_with_param(86, phone_numbers,
template_id, params, sign=sms_sign, extend="", ext="") # 签名参数未提供或者为空时,会使用默认签名发送短信
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note:`群发一次请求最多支持200个号码,如有对号码数量有特殊需求请联系腾讯云短信技术支持(QQ:3012203387)。
> `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过,才可能下发成功,否则返回失败。
- **发送语音验证码**
```python
from qcloudsms_py import SmsVoiceVerifyCodeSender
from qcloudsms_py.httpclient import HTTPError
vvcsender = SmsVoiceVerifyCodeSender(appid, appkey)
try:
result = vvcsender.send("86", phone_numbers[0], "5678",
playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 语音验证码发送只需提供验证码数字,例如当msg=“5678”时,您收到的语音通知为“您的语音验证码是5678”,如需自定义内容,可以使用语音通知。
- **发送语音通知**
```python
from qcloudsms_py import SmsVoicePromptSender
from qcloudsms_py.httpclient import HTTPError
vpsender = SmsVoicePromptSender(appid, appkey)
try:
result = vpsender.send("86", phone_numbers[0], 2, "5678",
playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
- **拉取短信回执以及回复**
```python
from qcloudsms_py import SmsStatusPuller
from qcloudsms_py.httpclient import HTTPError
max_num = 10 # 单次拉取最大量
spuller = SmsStatusPuller(appid, appkey)
try:
# 拉取短信回执
callback_result = spuller.pull_callback(max_num)
# 拉取回复
reply_result = spuller.pull_reply(max_num)
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(callback_result)
print(reply_result)
```
> `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387),量大客户可以使用此功能批量拉取,其他客户不建议使用。
- **拉取单个手机短信状态**
```python
from qcloudsms_py import SmsMobileStatusPuller
from qcloudsms_py.httpclient import HTTPError
begin_time = 1511125600 # 开始时间(unix timestamp)
end_time = 1511841600 # 结束时间(unix timestamp)
max_num = 10 # 单次拉取最大量
mspuller = SmsMobileStatusPuller(appid, appkey)
try:
# 拉取短信回执
callback_result = mspuller.pull_callback("86", phone_numbers[0],
begin_time, end_time, max_num)
# 拉取回复
reply_result = mspuller.pull_reply("86", phone_numbers[0],
begin_time, end_time, max_num)
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(callback_result)
print(reply_result)
```
> `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387),量大客户可以使用此功能批量拉取,其他客户不建议使用。
- **发送海外短信**
海外短信与国内短信发送类似, 发送海外短信只需替换相应国家码。
- **上传语音文件**
```python
from qcloudsms_py import VoiceFileUploader
from qcloudsms_py.httpclient import HTTPError
# Note: 语音文件大小上传限制400K字节
with open("/path/to/example.mp3", "rb") as f:
content = f.read()
uploader = VoiceFileUploader(appid, appkey)
try:
result = uploader.upload(content, content_type="mp3")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
# 上传成功后,result里会带有语音文件的fid
print(result)
```
> `Note` '语音文件上传'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
- **按语音文件fid发送语音通知**
```python
from qcloudsms_py import FileVoiceSender
from qcloudsms_py.httpclient import HTTPError
# Note:这里fid来自`上传语音文件`接口返回的响应,要按语音
# 文件fid发送语音通知,需要先上传语音文件获取fid
fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3"
fvsender = FileVoiceSender(appid, appkey)
try:
result = fvsender.send(fid, phone_numbers[0],
nationcode="86", playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
> `Note` 按'语音文件fid发送语音通知'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
- **指定模板发送语音通知**
```python
from qcloudsms_py import TtsVoiceSender
from qcloudsms_py.httpclient import HTTPError
template_id = 12345
params = ["5678"]
tvsender = TtsVoiceSender(appid, appkey)
Try:
result = tvsender.send(template_id, params, phone_numbers[0],
nationcode="86", playtimes=2, ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
#### 使用代理
有的环境需要使用代理才能上网,可以指定HTTPSimpleClient的proxy参数来实现, 示例如下:
```python
from qcloudsms_py import SmsSingleSender
from qcloudsms_py.httpclient import HTTPSimpleClient, HTTPError
httpclient = HTTPSimpleClient(proxy="www.proxysever.com:8080")
ssender = SmsSingleSender(appid, appkey, httpclient=httpclient)
template_id = 7839
params = ["5678"]
try:
result = ssender.send_with_param(86, phone_numbers[0],
template_id, params, sign=sms_sign, extend="", ext="")
except HTTPError as e:
print(e)
except Exception as e:
print(e)
print(result)
```
#### 统一创建对象
短信和语音各类的对象可以通过 `qcloudsms_py.QcloudSms` 统一创建,这种
方式可以避免创建对象时多次传入参数`appid` 和 `appkey`, 示例如下:
```python
from qcloudsms_py import QcloudSms
# 创建QcloudSms对象
qcloudsms = QcloudSms(appid, appkey)
# 创建单发短信(SmsSingleSender)对象
ssender = qcloudsms.SmsSingleSender()
# 创建上传语音文件(VoiceFileUploader)对象
uploader = qcloudsms.VoiceFileUploader()
```
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
qcloudsms_py-0.1.3.tar.gz
(59.2 kB
view hashes)