注意事项

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

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); }, })