对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
ObjectSet
文件管理
监控与告警
权限配置
IAM 策略管理
典型配置场景
IAM 子用户授权
使用工具及 SDK 的授权说明
接入点
单区域接入点（SRAP）
内容感知与处理（SenseFlow）
TOS Agent
数据处理
分层命名空间（HNS）
TOS Vectors
API 参考
向量桶
SDK 参考
Python-Vectors
向量桶
向量索引
Java-Vectors
向量桶
向量索引
Node.js-Vectors
向量桶
向量索引
工具指南
tosutil
常用命令
辅助命令
TOS Browser
FSX
TOS PyTorch Connector
tosfsspec
API 参考
签名机制
存储桶
桶基础操作
自定义域名
数据处理
媒体处理
视频转码
音频转码
ObjectSet
生命周期
对象
基础操作
分片上传
SDK 参考
Java
存储桶接口
管理桶配置
ObjectSet
对象接口
下载对象
数据处理
视频处理
日志配置
分层命名空间
Python
数据处理
存储桶接口
对象接口
上传对象
C++
存储桶接口
对象接口
Go
对象接口
存储桶接口
管理桶配置
ObjectSet
数据处理
日志配置
Node.js
存储桶接口
对象接口
上传对象
数据处理
Browser.js
上传对象
.NET
对象接口
PHP
对象接口
异常处理
Android
对象接口
iOS
对象接口
Harmony
存储桶接口
对象接口
上传对象
Rust
存储桶接口
桶基础操作
桶清单
自定义域名
对象接口
基础操作
错误码
01-SERVICE_ERROR
02-AUTH
03-ACCESS_CONTROL
04-QOS
05-REQUEST
06-BUCKET
07-LIFECYCLE
08-ACL
09-CORS
10-POLICY
11-MIRROR
12-REPLICATION
13-WEBSITE
14-NOTIFICATION
15-ENCRYPT
16-CUSTOMDOMAIN
17-OBJECT
18-TAG
19-MULTIPART
20-STORAGE_CLASS
21-CALLBACK
22-DATA_PROCESS
23-BATCH
24-STORAGE_LENS
25-INVENTORY
26-DIRECTORY_BUCKET
32-WORM
常见问题
最佳实践
AIGC-豆包大模型最佳实践
校验数据一致性
- 文档首页
对象存储SDK 参考iOS对象接口下载对象断点续传（iOS SDK）
复制全文
下载 pdf断点续传（iOS SDK）
文档反馈
问问助手断点续传适用于大文件传输或网络不稳定的场景。TOS iOS SDK 将对象拆分为多个分片并保存至 checkpoint。任务暂停或异常中断后，再次发起相同请求即可从已完成的分片继续传输，无需重新传输整个文件。
前提条件
- 已安装并初始化 TOS iOS SDK v2.1.8 或更高版本。
- 已准备可用的 Endpoint、Region 和 Bucket。
- 确保上传源文件路径、下载目标目录及 checkpoint 目录均可正常访问。
- 示例代码使用 Objective-C，可放入工程的 .m 文件中。
注意事项
注意事项 | 说明 |
注意事项 | 说明 |
版本与接口兼容性 |
|
任务管理 |
|
运行环境 |
|
续传状态管理 | 下载成功完成后 SDK 会自动删除 checkpoint。
|
准备 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];
}
示例代码
下载数据会先写入临时文件。所有分片下载并校验成功后，SDK 才会原子替换目标文件，因此暂停或传输失败不会破坏已有目标文件。
创建下载请求
static TOSDownloadFileInput *TOSCreateDownloadInput(
NSString *bucket,
NSString *objectKey,
NSString *filePath,
NSString *checkpointPath,
TOSCancelHook *cancelHook) {
TOSDownloadFileInput *input = [TOSDownloadFileInput new];
input.tosBucket = bucket;
input.tosKey = objectKey;
input.tosFilePath = filePath;
// 临时文件必须与目标文件位于同一文件系统，建议使用同一目录。
input.tosTempFilePath = [filePath stringByAppendingString:@".temp"];
// 分片大小。设置为 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;= ^(TOSDataTransferStatus *status) {
if (status.tosTotalBytes <= 0) {
return;
}
double progress =
status.tosConsumedBytes * 100.0 / status.tosTotalBytes;
dispatch_async(dispatch_get_main_queue(), ^{
NSLog(@"Download progress: %.2f%%", progress);
// 在此更新进度条。
});
};
return input;
}
开始下载
NSString *bucket = @"YOUR_BUCKET";
NSString *objectKey = @"example/large-file.bin";
NSString *downloadFilePath = @"YOUR_DOWNLOAD_FILE_PATH";
NSString *downloadCheckpoint = TOSCheckpointPath(@"download-large-file.json");
TOSCancelHook *downloadCancelHook = [TOSCancelHook new];
TOSDownloadFileInput *downloadInput =
TOSCreateDownloadInput(bucket,
objectKey,
downloadFilePath,
downloadCheckpoint,
downloadCancelHook);
TOSTask *downloadTask = [client downloadFile:downloadInput];
[downloadTask continueWithBlock:^id(TOSTask *finishedTask) {
if (finishedTask.error) {
NSLog(@"Download file failed: %@", finishedTask.error);
return nil;
}
NSLog(@"Download file succeeded: %@", downloadFilePath);
return nil;
}];
暂停并恢复下载
当用户触发暂停操作时，调用以下接口暂停下载任务：
// 暂停下载并保留 checkpoint 和临时文件。
[downloadCancelHook cancel:NO];
等待原任务完成回调后，使用相同参数重新创建请求：
TOSCancelHook *newDownloadCancelHook = [TOSCancelHook new];
TOSDownloadFileInput *resumedDownloadInput =
TOSCreateDownloadInput(bucket,
objectKey,
downloadFilePath,
downloadCheckpoint,
newDownloadCancelHook);
TOSTask *resumedDownloadTask = [client downloadFile:resumedDownloadInput];
[resumedDownloadTask continueWithBlock:^id(TOSTask *finishedTask) {
if (finishedTask.error) {
NSLog(@"Resume download failed: %@", finishedTask.error);
} else {
NSLog(@"Resume download succeeded: %@", downloadFilePath);
}
return nil;
}];
终止任务
调用 TOSCancelHook 可立即终止任务并清理续传状态，终止后再次调用对应接口时任务将从头开始。
通过各自请求中的 TOSCancelHook 终止任务：
// 终止下载
[downloadCancelHook cancel:YES];
注意
请勿在任务成功或已经终止后继续复用旧的 TOSCancelHook。
最近更新时间：2026.09.29 16:01:36
这个页面对您有帮助吗？
有用
有用
无用
无用