客户端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 开始支持本方法。
语法
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 开始支持本方法。
语法
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
语法
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); }, })