抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 快速入门
  • 开发指南
  • 功能服务
  • 行业解决方案
  • 迁移指南
  • API 参考
  • 云函数
  • 云托管
  • 触发器接口开发文档
  • 云数据库
  • 对象存储
  • 客户端SDK接口
  • 对象存储服务端 API
  • 媒资管理OpenApi
  • 配置中心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); }, })
    ​