You need to enable JavaScript to run this app.
文档中心
对象存储

对象存储

请输入
  • 文档首页
    • 对象存储SDK 参考iOS对象接口上传对象断点续传（iOS SDK）
复制全文
下载 pdf
我的收藏
上传对象
断点续传（iOS SDK）
复制全文
下载 pdf
我的收藏
断点续传（iOS SDK）
断点续传适用于大文件传输或网络不稳定的场景。TOS iOS SDK 将对象拆分为多个分片并保存至 checkpoint。任务暂停或异常中断后，再次发起相同请求即可从已完成的分片继续传输，无需重新传输整个文件。​
前提条件​
  • 已准备可用的 Endpoint、Region 和 Bucket。​
  • 确保上传源文件路径、下载目标目录及 checkpoint 目录均可正常访问。​
  • 示例代码使用 Objective-C，可放入工程的 .m 文件中。​
注意事项​
​
注意事项​
说明​
版本与接口兼容性​
  • 原有TOSUploadFileInput 和 uploadFile 接口行为不变。​
  • 断点续传的上传请使用 TOSUploadFileInputV2 SDK 接口。​
  • 当前断点续传接口不支持 SSE 相关参数。​
任务管理​
  • 同一 checkpoint 路径不能同时用于多个传输任务，恢复前应等待原任务结束。​
  • 恢复任务时，Bucket、Object、文件路径、分片大小、版本号和条件参数等必须与原任务保持一致。​
  • 每次恢复传输任务均需创建新的请求对象和 TOSCancelHook。​
  • checkpoint 不包含访问凭证，也不保证与其他语言的 SDK 互通。​
运行环境​
  • 断点续传沿用前台传输边界：App 进入后台或进程被系统终止后不保证继续执行，下次启动可通过 checkpoint 恢复。​
  • 传输进度和事件回调可能在后台线程执行，更新 UI 时请切换到主线程。​
续传状态管理​
上传成功完成后 SDK 会自动删除 checkpoint。​
  • cancel:NO 保留续传状态。​
  • cancel:YES 清理续传状态。​
​
准备 checkpoint 路径​
每个传输任务必须使用独立的 checkpoint 路径。以下示例将 checkpoint 保存在 App 的 Application Support 目录中：​
​
static NSString *TOSCheckpointPath(NSString *fileName) {​
NSFileManager *fileManager = [NSFileManager defaultManager];​
NSURL *baseURL = [[fileManager URLsForDirectory:NSApplicationSupportDirectory​
inDomains:NSUserDomainMask] firstObject];​
NSURL *directoryURL = [baseURL URLByAppendingPathComponent:@"TOSCheckpoints"​
isDirectory:YES];​
​
NSError *error = nil;​
BOOL created = [fileManager createDirectoryAtURL:directoryURL​
withIntermediateDirectories:YES​
attributes:nil​
error:&error];​
if (!created) {​
NSLog(@"Create checkpoint directory failed: %@", error);​
return nil;​
}​
return [[directoryURL URLByAppendingPathComponent:fileName] path];​
}​
​
示例代码​
创建上传请求​
创建一个开启 checkpoint 的上传请求。首次上传和恢复上传必须传入相同的 Bucket、Object、源文件、分片大小和 checkpoint 路径。​
​
static TOSUploadFileInputV2 *TOSCreateUploadInput(​
NSString *bucket,​
NSString *objectKey,​
NSString *filePath,​
NSString *checkpointPath,​
TOSCancelHook *cancelHook) {​
​
TOSUploadFileInputV2 *input = [TOSUploadFileInputV2 new];​
input.tosBucket = bucket;​
input.tosKey = objectKey;​
input.tosFilePath = filePath;​
// 分片大小，设置为 0 时使用默认值 20 MiB，有效范围为 5 MiB ～ 5 GiB。​
input.tosPartSize = 20LL * 1024 * 1024; ​
// 当前任务的分片并发数，默认值为 1，取值会归一化到 1 ～ 1000。​
input.tosTaskNum = 3; ​
input.tosEnableCheckpoint = YES;​
// checkpoint 文件或目录路径。建议使用能够跨 App 启动保留的本地目录，并为每个任务分配独立路径。​
input.tosCheckpointFile = checkpointPath;​
// 初始化请求和单个分片请求的最大重试次数，默认值为 3；设置为 0 时表示关闭重试。​
input.tosMaxRetryCount = 3;​
input.tosCancelHook = cancelHook;​
​
input.tosDataTransferListener = ^(TOSDataTransferStatus *status) {​
if (status.tosTotalBytes <= 0) {​
return;​
}​
double progress =​
status.tosConsumedBytes * 100.0 / status.tosTotalBytes;​
dispatch_async(dispatch_get_main_queue(), ^{​
NSLog(@"Upload progress: %.2f%%", progress);​
// 在此更新进度条。​
});​
};​
return input;​
}​
​
开始上传​
​
NSString *bucket = @"YOUR_BUCKET";​
NSString *objectKey = @"example/large-file.bin";​
NSString *sourceFilePath = @"YOUR_LOCAL_FILE_PATH";​
NSString *uploadCheckpoint = TOSCheckpointPath(@"upload-large-file.json");​
​
TOSCancelHook *uploadCancelHook = [TOSCancelHook new];​
TOSUploadFileInputV2 *uploadInput =​
TOSCreateUploadInput(bucket,​
objectKey,​
sourceFilePath,​
uploadCheckpoint,​
uploadCancelHook);​
​
TOSTask *uploadTask = [client uploadFile:uploadInput];​
[uploadTask continueWithBlock:^id(TOSTask *finishedTask) {​
if (finishedTask.error) {​
NSLog(@"Upload file failed: %@", finishedTask.error);​
return nil;​
}​
​
TOSUploadFileOutputV2 *output = finishedTask.result;​
NSLog(@"Upload file succeeded, ETag: %@", output.tosETag);​
return nil;​
}];​
​
暂停并恢复上传​
当用户触发暂停操作时，调用以下接口暂停上传任务：​
​
// 取消当前请求，但保留 checkpoint 和远端已上传分片。​
[uploadCancelHook cancel:NO];​
​
等待原任务完成回调后，重新创建请求和 TOSCancelHook，复用相同 checkpoint 路径：​
​
TOSCancelHook *newUploadCancelHook = [TOSCancelHook new];​
TOSUploadFileInputV2 *resumedUploadInput =​
TOSCreateUploadInput(bucket,​
objectKey,​
sourceFilePath,​
uploadCheckpoint,​
newUploadCancelHook);​
​
TOSTask *resumedUploadTask = [client uploadFile:resumedUploadInput];​
[resumedUploadTask continueWithBlock:^id(TOSTask *finishedTask) {​
if (finishedTask.error) {​
NSLog(@"Resume upload failed: %@", finishedTask.error);​
} else {​
NSLog(@"Resume upload succeeded");​
}​
return nil;​
}];​
​
上传成功后，SDK 会自动删除 checkpoint。​
终止任务​
调用 TOSCancelHook 可立即终止任务并清理续传状态，终止后再次调用对应接口时任务将从头开始。​
通过各自请求中的 TOSCancelHook 终止任务：​
​
// 终止上传​
[uploadCancelHook cancel:YES];​
​
注意​
请勿在任务成功或已经终止后继续复用旧的 TOSCancelHook。​
​
最近更新时间：2026.09.29 16:01:48
这个页面对您有帮助吗？
有用
有用
无用
无用