文档

Android SDK 简介

更新时间:

接入指南

接入SDK

通过gradle引入SDK。

implementation 'com.aliyun.pds:android-sdk:0.1.4'

源码地址 aliyun-pds-android-sdk

重要

支持的Android SDK最低版本为API 21

初始化

在使用SDK之前,请确保您已经开通PDS服务,并且在控制台创建了实例,参见快速搭建云盘服务

// 这个通用流程是你们登入自己的账号系统后获取,后端使用 PDS 平台申请的 appKey & appSecret 换取 token 返回给客户端
val token = SDToken("you access token") 
// 请在PDS控制台获取您的 api host
val apiHost = "you api host"            
val config = SDConfig.Builder(token, apiHost, 3600)
    // 是否支持妙传,默认true (选填)
    .canFastUpload() 
    // 请求的ua (选填)
    .userAgent() 
    // 最大重试次数,默认3  (选填)
    .maxRetryCount()
    // 是否开启调试模式,默认false (选填)
    .isDebug()
    // 下载分片大小,默认10M,不要填过小或者过大(选填)
    .downloadBlockSize() 
    // 上传分片大小,默认4M,不要填过小或者过大(选填)
    .uploadBlockSize() 
    // 建立网络连接超时时间设置,默认15s (选填)
    .connectTimeout()
    // 网络连接响应超时时间设置,默认60s (选填)
    .readTimeout()
    // 网络传输响应超时时间设置,默认60s (选填)
    .writeTimeout()         
    .build()
SDClient.instance.init(this, config)
说明

需要注意的是,当前 SDK 不负责刷新 accessToken。需要使用方从自己的服务器定时刷新token后传递给SDK,使用如下代码更新token。

SDClient.instance.updateToken(token)

上传下载使用

说明

请注意任务的进度和状态回调都在子线程中,若要更新UI,请自行切换到主线程。

下载任务

// 初始化下载信息
val downloadInfo = DownloadRequestInfo.Builder()
    .downloadUrl(url)
    .driveId(driveId)
    .fileId(fileId)
    .fileName(fileName)
    .fileSize(fileSize)
    // 文件保存路径
    .filePath(dir.path)
    // 文件来自分享:id(不涉及分享业务可不传)
    .shareId(shareId)
    // 文件来自分享:token(不涉及分享业务可不传)
    .shareToken(shareToken) 
    // 文件来自分享:pwd(不涉及分享业务可不传)
    .sharePwd(sharePwd)
    // 历史版本相关:id(下载文件的历史版本时,需要传入,不涉及可不传)
    .revisionId(revisionId)
    // hash 效验值
    .contentHash(hash)
    // hash 效验算法名 当前只支持 crc64
    .contentHashName("crc64")       
    .build()

/* 
* 创建任务并启动任务
* 如果将taskId指定为之前未完成的任务则会根据之前的进度进行断点续传
* 不要将taskId指定为之前已经成功的任务,这样会直接触发完成回调
* 不同的任务需要指定不同的TaskId,只有在续传场景才能指定为之前的taskId
*/
val task = SDClient.instance.startDownloadTask(
    taskId,                 
    downloadInfo,
    // 下载完成监听(成功,失败都会回调。失败时会返回错误信息)
    completeListener,
    // 下载进度监听
    progressListener        	
)

/*
* 默认startDownloadTask即会启动任务,
* 任务被stop后需要再次启动可以调用此方法继续运行
*/
task.start()

/* 
* 停止任务,clean参数false代表不清理临时文件,继续start会断点续传,
* 参数为true则代表会清理临时文件及数据,再次start会重头进行任务
*/
task.stop(clean)

上传任务

// 初始化上传信息
val uploadInfo = UploadRequestInfo.Builder()
    .fileName("edmDrive")
    .filePath(file.absolutePath)
    .fileSize(file.length())
    .parentId(parentId)
    .driveId(driveId)
    .mimeType(mimeType)
    // 指定文件ID,需要覆盖上传时必填
    .fileId(fileId)
    /* 
    * 同名文件处理模式,默认为"auto_rename",具体参数说明如下:
    *  auto_rename: 当发现同名文件是,云端自动重命名,默认为追加当前时间点,如 xxx _20060102_150405;
    *  ignore: 允许同名文件;
    *  refuse:当云端存在同名文件时,拒绝创建新文件,直接提示上传成功
    */
    .checkNameMode(checkNameMode)       
    // 分享相关, 不涉及可以不传                                
    .shareId(shareId)                   
    .shareToken(shareToken)             
    .sharePwd(sharePwd)                 
    .build()

// 创建任务并启动
val task = SDClient.instance.startUploadTask(
    taskId,                 
    uploadInfo,
    // 上传完成监听(成功,失败都会回调。失败时会返回错误信息)
    completeListener,
    // 上传进度监听
    progressListener        
)

/* 
* 默认startUploadTask即会启动任务,
* 任务被stop后需要再次启动可以调用此方法继续运行
*/
task.start()

/*
* 停止任务,clean参数false代表不清理临时文件,继续start会断点续传,
* 参数为true则代表会清理临时文件及数据,再次start会重头进行任务
*/
task.stop(clean)

任务进度回调

// currentSize 为当前的进度,注意回调不在主线程
interface OnProgressListener {
    fun onProgressChange(currentSize : Long)
}

任务结束回调

interface OnCompleteListener {
    fun onComplete(taskId: String, fileMeta : SDFileMeta, errorInfo: SDErrorInfo?)
}

其中fileMeta 为文件相关信息

class SDFileMeta(
    // 文件id
    val fileId: String?,
    // 文件名
    val fileName: String?,
    // 文件路径,上传任务为要上传文件的路径,下载任务为文件保存路径
    val filePath: String?,
    // 上传任务的 uploadId,不涉及相关业务可以忽略
    val uploadId: String? = "" 
)

class SDErrorInfo(
    // 相关错误码
    val code: SDTransferError,
    // 错误描述
    val message: String,
    // 异常,用于查看堆栈, 以及错误处理
    val exception: Exception?,
    // 如果是后端请求相关错误,则会有该值用于和后端排查问题
    var requestId: String? = "" 
)

错误信息错误码说明

SDTransferError.Unknown // 未知错误
SDTransferError.Network // 网络错误
SDTransferError.Server // 服务器错误
SDTransferError.FileNotExist // 上传时,本地文件没有找到
SDTransferError.SpaceNotEnough // 下载时,本地空间不足
SDTransferError.TmpFileNotExist // 下载时,本地临时文件不存在
SDTransferError.PathRuleError // 下载时,保存路径规则错误

创建任务后任务自动启动,可以通过进度回调得知当前任务进度,任务成功或失败则会调用完成监听

文件API操作

具体请求参数和返回值参考官方 API 文档 文件操作API

通过 SDClient.fileApi 拿到 fileApi 对象后调用如下方法访问对应 API。

说明

注:请求示例中的参数仅为基础参数,其它参数请参考官方API文档。

列举文件或文件夹

fun fileList(fileListRequest: FileListRequest): FileListResp?

// FileListRequest 示例 其他参数参考 FileListRequest 实现
val request = FileListRequest()
// 所获取文件夹的fileId(root为根目录)
request.parentId = "root"
// 列表所属的 driveId
request.driveId = ""                    

创建文件、文件夹

// FileCreateRequest示例
val createRequest = FileCreateRequest()
// enum (ignore, auto_rename, refuse)
createRequest.checkNameMode = "auto_rename"
// 指定创建的文件在哪个 driveId
createRequest.driveId = "" 
// 新建文件的名称
createRequest.name = ""
// 文件的父目录fileId(root为根目录)
createRequest.parentFileId = "root"
// enum (file, folder)
createRequest.type = "folder"                   

获取文件、文件夹

// 获取文件、文件夹信息
fun fileGet(getResp: FileGetRequest): FileGetResp?

// FileGetRequest 示例
val getRequest = FileGetRequest()
// 文件所属的 driveId
getRequest.driveId = "" 
// 文件的fileId
getRequest.fileId = ""                      

拷贝文件、文件夹

// 拷贝文件、文件夹
fun fileCopy(fileCopyRequest: FileCopyRequest): FileCopyResp?

// FileCopyRequest 示例
val copyRequest = FileCopyRequest()
// 文件的所属的 driveId
copyRequest.driveId = ""  
// 文件的fileId
copyRequest.fileId = ""
// 目标文件夹的driveId
copyRequest.toDriveId = ""
// 文件拷贝后的新名字
copyRequest.newName = ""
// 目标文件夹的fufileId(root为根目录)
copyRequest.toParentId = "root"         

移动文件、文件夹

// 移动文件、文件夹
fun fileMove(fileMoveRequest: FileMoveRequest): FileMoveResp?

// FileMoveRequest 示例
val moveRequest = FileMoveRequest() 
// 文件的driveId
moveRequest.driveId = "" 
// 文件的fileId
moveRequest.fileId = ""
// 目标文件夹的driveId
moveRequest.toDriveId = ""
// 文件移动后的新名字
moveRequest.newName = "" 
// 目标文件夹的父目录fileId(root为根目录)
moveRequest.toParentId = "root"             

更新文件、文件夹

fun fileUpdate(updateRequest: FileUpdateRequest): FileGetResp?

// FileUpdateRequest 示例
val updateRequest = FileUpdateRequest()
// 文件所属的 driveId
updateRequest.driveId = item.driveId!!
// 文件的fileId
updateRequest.fileId = item.fileId 
// 文件更新后的新名字
updateRequest.name = ""                     

删除文件、文件夹

fun fileDelete(deleteRequest: FileDeleteRequest): FileDeleteResp?

// FileDeleteRequest 示例
val delRequest = FileDeleteRequest()
// 文件所属的driverId
delRequest.driveId = ""
// 需要删除文件或文件夹的fileId
delRequest.fileId = ""                      

搜索文件

fun fileSearch(fileSearchRequest: FileSearchRequest): FileListResp?

// FileSearchRequest示例  
// query规则可参考 https://help.aliyun.com/document_detail/175890.html
val request = FileSearchRequest()
// keyStr:搜索关键词
request.query = "name match '$keyStr' and status = 'available'"     
request.driveId = ""  

其他

// 获取文件分片的上传地址
fun fileGetUploadUrl(getUploadUrlRequest: FileGetUploadUrlRequest): FileGetUploadUrlResp?

// 完成文件上传
fun fileComplete(completeRequest: FileCompleteRequest): FileGetResp?

// 获取文件下载地址
fun fileGetDownloadUrl(getDownloadUrlRequest: FileGetDownloadUrlRequest): FileGetDownloadUrlResp?

// 异步任务状态,例如删除包含多个文件的文件夹,此时是一个异步任务,可以通过这个接口获取任务状态
fun getAsyncTask(getAsyncTaskRequest: AsyncTaskRequest): AsyncTaskResp?

  • 本页导读 (0)
文档反馈