客户端SDK接口

收藏
我的收藏

注意事项​

    小程序开发和小游戏开发对基础库的最低版本要求不一致,具体参考每个接口说明。​

tt.createCloud​

返回一个 Cloud 云调用实例。​

语法​

tt.createCloud(options)

参数说明​

参数​
类型​
默认值​
必填​
说明​
最低基础库支持版本​
options​
object​
-​
是​
cloud 配置​
小程序端为2.70.0​
小游戏端为2.88.0.0

options 说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
envID​
string​
-​
是​
云环境ID​
小程序端为2.70.0​
小游戏端为2.88.0.0​
serviceID​
string​
-​
否​
云服务ID​
小程序端为2.70.0​
小游戏端为2.88.0.0​

返回值​

Cloud​

Cloud​

通过 tt.createCloud 获取的实例,通过它访问云托管服务。​

Cloud.uploadFile​

基础库 2.76.0 开始支持本方法。​
支持已登录用户上传本地文件到抖音云对象存储,未登录用户调用接口会报错,登录依赖 tt.login。​

语法​

Cloud.uploadFile(options);

参数说明​

参数​
类型​
默认值​
必填​
说明​
最低基础库支持版本​
options​
object​
-​
是​
请求配置​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

options 说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
cloudPath​
string​
是​
对象存储路径​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
filePath​
string​
是​
本地文件路径​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
timeout​
number​
60000​
否​
超时时间,单位为毫秒​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
success​
function​
否​
文件上传成功后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
fail​
function​
否​
接口调用失败后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
complete​
function​
否​
接口调用结束后的回调函数(调用成功、失败都会执行)​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

成功回调​

参数为 Object 类型,属性如下:​
属性名
类型
说明
最低基础库支持版本
errMsg​
string​
"Cloud.uploadFile:ok"​
小程序端为2.76.0.0​
小游戏端为2.88.0.0​

失败回调​

返回参数如下:​
属性名
类型
说明
最低基础库支持版本
errMsg​
string​
"Cloud.uploadFile:fail " + 详细错误信息​
小程序端为2.76.0.0​
小游戏端为2.88.0.0​
errNo​
number​
错误码​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

返回值​

CloudUploadTask​

CloudUploadTask​

方法​

方法名
说明
最低基础库支持版本
onProgressUpdate​
开始监听上传任务​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
offProgressUpdate​
停止监听上传任务​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

CloudUploadTask.onProgressUpdate​

监听上传进度变化事件​

语法​

CloudUploadTask.onProgressUpdate(callback)

参数说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
callback​
function​
是​
回调函数​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
callback回调函数入参为 Object 类型,属性如下:​
属性名
类型
说明
最低基础库支持版本
progress​
number​
上传进度百分比​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
totalBytesSent​
number​
已经上传的数据长度,单位 byte
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
totalBytesExpectedToSend​
number​
预期需要上传的数据总长度,单位 byte
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

返回值​

无​

CloudUploadTask.offProgressUpdate​

取消监听上传进度变化事件​

语法​

CloudUploadTask.offProgressUpdate(callback)

参数说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
callback​
function​
是​
回调函数​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

返回值​

无​

代码示例​

<!-- index.ttml --> <view> <button size="default" bindtap="uploadImage"> 选择图片上传</button> <button size="default" bindtap="onProgressUpdate"> 开始监听上传进度 </button> <button size="default" bindtap="offProgressUpdate"> 停止监听上传进度 </button> <view>
// index.js let uploadTask; let cloud; // 需传入与监听时同一个的函数对象 const listener = function (res) { console.log(res) } Page({ onLoad(){ cloud = tt.createCloud({envID:'envID',serviceID:'serviceID'}) }, uploadImage(){ tt.chooseImage({ count: 1, sizeType: ["compressed"], sourceType: ["album"], success: (res) => { uploadTask = cloud.uploadFile({ cloudPath: "myDir/path1.png", filePath: res.tempFilePaths[0], timeout: 80000, success: (uploadRes) => { console.log("Cloud.uploadFile success", uploadRes); }, fail: (uploadRes) => { console.log("Cloud.uploadFile fail", uploadRes); }, complete: (uploadRes) => { console.log("Cloud.uploadFile complete", uploadRes); }, }) console.log("tt.chooseImage success", res); }, fail: (res) => { console.log("tt.chooseImage fail", res); }, complete: (res) => { console.log("tt.chooseImage complete", res); }, }); }, onProgressUpdate(){ if(uploadTask){ uploadTask.onProgressUpdate(listener) } }, offProgressUpdate(){ if(uploadTask){ uploadTask.offProgressUpdate(listener) } } });

Cloud.downloadFile​

基础库 2.76.0 开始支持本方法。​
支持已登录用户下载抖音云对象存储空间的文件,未登录用户调用接口会报错,登录依赖 tt.login。​

语法​

Cloud.downloadFile(options);

参数说明​

参数​
类型​
默认值​
必填​
说明​
最低基础库支持版本​
options​
object​
-​
是​
请求配置​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

options 说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
cloudPath​
string​
是​
对象存储路径​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
filePath​
string​
否​
指定文件下载后存储的路径 ,只支持以 ttfile://user 开头的用户目录路径。若不传,文件会保存在临时目录​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
timeout​
number​
60000​
否​
超时时间,单位为毫秒​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
success​
function​
否​
文件下载成功后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
fail​
function​
否​
接口调用失败后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
complete​
function​
否​
接口调用结束后的回调函数(调用成功、失败都会执行)​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

成功回调​

参数为 Object 类型,属性如下。​
属性名
类型
说明
最低基础库支持版本
tempFilePath​
string​
临时文件路径 (本地路径)。没传入 filePath 指定文件存储路径时会返回,下载后的文件会存储到一个临时文件​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
filePath​
string​
用户文件路径 (本地路径)。传入 filePath 时会返回,跟传入的 filePath 一致​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errMsg​
string​
"Cloud.downloadFile:ok"​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

失败回调​

返回参数如下:​
属性名
类型
说明
最低基础库支持版本
errMsg​
string​
"Cloud.downloadFile:fail " + 详细错误信息​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errNo​
number​
错误码​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

返回值​

CloudDownloadTask​

CloudDownloadTask​

方法​

方法名
说明
最低基础库支持版本
onProgressUpdate​
开始监听下载任务​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
offProgressUpdate​
停止监听下载任务​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

CloudDownloadTask.onProgressUpdate​

基础库2.78.0开始支持此方法,这是一个异步方法​
监听下载进度变化事件​

语法​

CloudDownloadTask.onProgressUpdate(callback)

参数说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
callback​
function​
是​
回调函数​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
callback回调函数入参为 Object 类型,属性如下:​
属性名
类型
说明
最低基础库支持版本
progress​
number​
上传进度百分比​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
totalBytesWritten​
number​
已经上传的数据长度,单位 byte
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​
totalBytesExpectedToWrite​
number​
预期需要上传的数据总长度,单位 byte
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

返回值​

无​

CloudDownloadTask.offProgressUpdate​

基础库2.78.0开始支持此方法,这是一个异步方法​
取消监听下载进度变化事件​

语法​

CloudDownloadTask.offProgressUpdate(callback)

参数说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
callback​
function​
是​
回调函数​
小程序端为 2.78.0.0​
小游戏端为2.88.0.0​

返回值​

无​

代码示例​

<!-- index.ttml --> <view> <button size="default" bindtap="downloadImage"> 下载云图片</button> <button size="default" bindtap="onProgressUpdate"> 开始监听下载进度 </button> <button size="default" bindtap="offProgressUpdate"> 停止监听下载进度 </button> <view> 图片展示: <image tt:if="{{imageSrc}}" src="{{imageSrc}}" mode="center" />
let downloadTask; let cloud; // 需传入与监听时同一个的函数对象 const listener = function (res) { console.log(res) } Page({ data: { imageSrc: "", }, onLoad(){ cloud = tt.createCloud({envID:'envID',serviceID:'serviceID'}) }, downloadImage() { downloadTask = cloud.downloadFile({ cloudPath: "myDir/path1.png", filePath: "ttfile://user/test.png", timeout: 80000, success: (res) => { console.log("Cloud.downloadFile success", res); this.setData({ imageSrc: res.filePath, }); }, fail: (res) => { console.log("Cloud.downloadFile fail", res); }, complete: (res) => { console.log("Cloud.uploadFile complete", res); }, }) }, onProgressUpdate(){ if(downloadTask){ uploadTask.onProgressUpdate(listener) } }, offProgressUpdate(){ if(downloadTask){ uploadTask.offProgressUpdate(listener) } } });

Cloud.deleteFile​

支持已登录用户删除抖音云对象存储空间的文件,未登录用户调用接口会报错,登录依赖 tt.login。​

语法​

Cloud.deleteFile(options);

参数说明​

参数​
类型​
默认值​
必填​
说明​
最低基础库支持版本​
options​
object​
-​
是​
请求配置​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

options 说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
cloudPaths​
string[]​
是​
对象存储路径,最少1个,最多50个​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
timeout​
number​
60000​
否​
超时时间,单位为毫秒​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
success​
function​
否​
接口调用成功后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
fail​
function​
否​
接口调用失败后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
complete​
function​
否​
接口调用结束后的回调函数(调用成功、失败都会执行)​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

成功回调​

参数为 Object 类型,属性如下:​
属性名
类型
说明
最低基础库支持版本
fileLists​
DeletedFile[]​
删除的文件集合​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errMsg​
string​
"Cloud.deleteFile:ok"​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
DeletedFile 类型说明
object 类型,属性如下:​
属性名
类型
说明
最低支持版本
fileName​
string​
被删除的存储对象​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
status​
number​
状态码,成功为0​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
message​
string​
成功为success,失败为错误原因,参照下表​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
删除文件状态:​
status
message
错误描述
0​
success​
删除成功​
1001​
unkonwn error​
未知错误​
1002​
service unavailable​
服务不可用​
1003​
no file exist​
文件不存在​
1004​
request invalid ​
非法请求​
1005​
service internal error​
服务内部错误​
1006​
permission denied​
权限错误​

失败回调​

返回参数如下:​
属性名
类型
说明
最低支持版本
errMsg​
string​
"Cloud.deleteFile:fail " + 详细错误信息​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errNo​
number​
错误码​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

返回值​

无​

代码示例​

const cloud=tt.createCloud({ envID:'envID', serviceID:'serviceID' }); cloud.deleteFile({ cloudPaths: ["myDir/path1.png", "myDir/path2.png"], success: (res) => { console.log("Cloud.deleteFile success", res); }, fail: (res) => { console.log("Cloud.deleteFile fail", res); }, complete: (res) => { console.log("Cloud.deleteFile complete", res); }, })

Cloud.getTempFileURL​

基础库 2.76.0 开始支持本方法。​
支持已登录用户获取抖音云对象存储空间文件的临时访问地址,未登录用户调用接口会报错,登录依赖tt.login

语法​

Cloud.getTempFileURL(options);

参数说明​

参数​
类型​
默认值​
必填​
说明​
最低基础库支持版本​
options​
object​
-​
是​
请求配置​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

options 说明​

参数
类型
默认值
必填
说明
最低基础库支持版本
cloudPaths​
string[]​
是​
对象存储路径,最少1个,最多50个​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
timeout​
number​
60000​
否​
超时时间,单位为毫秒​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
maxAge​
number​
86400​
否​
私有文件的有效期,单位为秒,默认24小时​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
success​
function​
否​
接口调用成功后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
fail​
function​
否​
接口调用失败后的回调函数​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
complete​
function​
否​
接口调用结束后的回调函数(调用成功、失败都会执行)​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

成功回调​

参数为 Object 类型,属性如下。​
属性名
类型
说明
最低基础库支持版本
fileLists​
TempFile[]​
临时文件集合​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errMsg​
string​
"Cloud.getTempFileURL:ok"​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
TempFile说明
object类型,属性如下​
属性名
类型
说明
最低基础库支持版本
fileName​
string​
对象存储路径​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
url​
string​
文件地址​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
maxAge​
number​
文件链接过期时间​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
status​
number​
状态码,成功为0​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
message​
string​
成功为success,失败为错误原因,参照下表​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
文件状态:​
status
message
错误描述
0​
success​
获取文件地址成功​
1001​
Unkonwn error​
未知错误​
1002​
service unavailable​
服务不可用​
1003​
no file exist​
文件不存在​
1004​
request invalid ​
非法请求​
1005​
service internal error​
服务内部错误​
1006​
permission denied​
权限错误​

失败回调​

返回参数如下:​
属性名
类型
说明
最低基础库支持版本
errMsg​
string​
"Cloud.getTempFileURL:fail " + 详细错误信息​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​
errNo​
number​
错误码​
小程序端为 2.76.0.0​
小游戏端为2.88.0.0​

返回值​

无​

代码示例​

const cloud=tt.createCloud({ envID:'envID', serviceID:'serviceID' }); cloud.getTempFileURL({ cloudPaths: ["myDir/path1.png"], success: (res) => { console.log("Cloud.getTempFileURL success", res.fileLists); }, fail: (res) => { console.log("Cloud.getTempFileURL fail", res); }, complete: (res) => { console.log("Cloud.getTempFileURL complete", res); }, })