注意事项

•

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

tt.createCloud

返回一个 Cloud 云调用实例。

语法

JavaScript复制
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

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

Cloud.uploadFile

基础库 2.76.0 开始支持本方法。

支持已登录用户上传本地文件到抖音云对象存储，未登录用户调用接口会报错，登录依赖 tt.login。

语法

JavaScript复制
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

方法

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

CloudUploadTask.onProgressUpdate

监听上传进度变化事件

语法

JavaScript复制
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

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

语法

JavaScript复制
CloudUploadTask.offProgressUpdate(callback)

参数说明

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

返回值

无

代码示例

HTML复制
<!-- index.ttml -->
<view>
    <button size="default" bindtap="uploadImage"> 选择图片上传</button>
    <button size="default" bindtap="onProgressUpdate"> 开始监听上传进度 </button>
    <button size="default" bindtap="offProgressUpdate"> 停止监听上传进度 </button>
<view>

JavaScript复制
// 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。

语法

JavaScript复制
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

方法

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

CloudDownloadTask.onProgressUpdate

基础库2.78.0开始支持此方法，这是一个异步方法

监听下载进度变化事件

语法

JavaScript复制
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开始支持此方法，这是一个异步方法

取消监听下载进度变化事件

语法

JavaScript复制
CloudDownloadTask.offProgressUpdate(callback)

参数说明

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

返回值

无

代码示例

HTML复制
<!-- 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" />

JavaScript复制
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。

语法

JavaScript复制
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

返回值

无

代码示例

JavaScript复制
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

语法

JavaScript复制
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

返回值

无

代码示例

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

客户端SDK接口

​注意事项​

​tt.createCloud​

​语法​

​参数说明​

​options 说明​

​返回值​

​Cloud​

​Cloud.uploadFile​

​语法​

​参数说明​

​options 说明​

​成功回调​

​失败回调​

​返回值​

​CloudUploadTask​

​方法​

​CloudUploadTask.onProgressUpdate​

​语法​

​参数说明​

​返回值​

​CloudUploadTask.offProgressUpdate​

​语法​

​参数说明​

​返回值​

​代码示例​

​Cloud.downloadFile​

​语法​

​参数说明​

​options 说明​

​成功回调​

​失败回调​

​返回值​

​CloudDownloadTask​

​方法​

​CloudDownloadTask.onProgressUpdate​

​语法​

​参数说明​

​返回值​

​CloudDownloadTask.offProgressUpdate​

​语法​

​参数说明​

​返回值​

​代码示例​

​Cloud.deleteFile​

​语法​

​参数说明​

​options 说明​

​成功回调​

​失败回调​

​返回值​

​代码示例​

​Cloud.getTempFileURL​

​语法​

​参数说明​

​options 说明​

​成功回调​

​失败回调​

​返回值​

​代码示例​

注意事项

tt.createCloud

语法

参数说明

options 说明

返回值

Cloud

Cloud.uploadFile

语法

参数说明

options 说明

成功回调

失败回调

返回值

CloudUploadTask

方法

CloudUploadTask.onProgressUpdate

语法

参数说明

返回值

CloudUploadTask.offProgressUpdate

语法

参数说明

返回值

代码示例

Cloud.downloadFile

语法

参数说明

options 说明

成功回调

失败回调

返回值

CloudDownloadTask

方法

CloudDownloadTask.onProgressUpdate

语法

参数说明

返回值

CloudDownloadTask.offProgressUpdate

语法

参数说明

返回值

代码示例

Cloud.deleteFile

语法

参数说明

options 说明

成功回调

失败回调

返回值

代码示例

Cloud.getTempFileURL

语法

参数说明

options 说明

成功回调

失败回调

返回值

代码示例