对象存储
对象存储
对象存储
文档指南
请输入
产品动态
产品公告
产品计费
快速入门
用户指南
存储桶管理
基础设置
容错与容灾
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 v2.1.8 或更高版本。
- 已准备可用的 Endpoint、Region 和 Bucket。
- 确保上传源文件路径、下载目标目录及 checkpoint 目录均可正常访问。
- 示例代码使用 Objective-C，可放入工程的 .m 文件中。
注意事项
注意事项 | 说明 |
注意事项 | 说明 |
版本与接口兼容性 | 当前断点续传接口不支持 SSE 相关参数。 |
任务管理 |
|
运行环境 |
|
续传状态管理 | 拷贝成功完成后 SDK 会自动删除 checkpoint。
|
普通拷贝
如下代码展示如何在同一个桶内拷贝对象。
// 从STS服务获取的临时访问密钥和安全令牌（AccessKey、SecretKey、SecurityToken）
TOSCredential *credential = [[TOSCredential alloc] initWithAccessKey:@"accesskey" secretKey:@"secretkey" securityToken:@"securityToken"];
TOSEndpoint *tosEndpoint = [[TOSEndpoint alloc] initWithURLString:@"endpoint" withRegion:@"region"];
TOSClientConfiguration *config = [[TOSClientConfiguration alloc] initWithEndpoint:tosEndpoint credential:credential];
TOSClient *client = [[TOSClient alloc] initWithConfiguration:config];
TOSCopyObjectInput *input = [[TOSCopyObjectInput alloc] init];
input.tosBucket = @"bucket-name";
input.tosSrcBucket = @"src-bucket-name";
input.tosKey = @"object-name";
input.tosSrcKey = @"src-object-name";
input.tosMeta = @{@"new-meta-key" : @"new-meta-value"};
input.tosMetadataDirective = TOSMetadataDirectiveReplace;
TOSTask *task = [client copyObject:input];
[task continueWithBlock:^id(TOSTask *task) {
if (!task.error) {
NSLog(@"Copy object success.");
} else {
NSLog(@"Copy object failed, error: %@" ,task.error);
}
return nil;
}];
分片拷贝
拷贝大对象时，可通过 UploadPartCopy 实现分片复制，操作步骤如下：
- 调用 CreateMultipartUpload 初始化分片复制任务。
- 调用 UploadPartCopy 执行分片复制。
- 调用 CompleteMultipartUpload 合并分片。
TOSCredential *credential = [[TOSCredential alloc] initWithAccessKey:@"accesskey" secretKey:@"secretkey"];
TOSEndpoint *tosEndpoint = [[TOSEndpoint alloc] initWithURLString:@"endpoint" withRegion:@"region"];
TOSClientConfiguration *config = [[TOSClientConfiguration alloc] initWithEndpoint:tosEndpoint credential:credential];
TOSClient *client = [[TOSClient alloc] initWithConfiguration:config];
// 1. CreateMultipartUpload
TOSCreateMultipartUploadInput *create = [TOSCreateMultipartUploadInput new];
create.tosBucket = @"bucket-name";
create.tosKey = @"object-name";
task = [client createMultipartUpload:create];
[task waitUntilFinished];
TOSCreateMultipartUploadOutput *createOutput = task.result;
// 2. UploadPartCopy
TOSUploadPartCopyInput *part1 = [TOSUploadPartCopyInput new];
part1.tosBucket = @"bucket-name";
part1.tosKey = @"object-name";
part1.tosSrcBucket = @"src-bucket-name";
part1.tosSrcKey = @"src-object-name";
part1.tosCopySourceRangeStart = @0;
part1.tosPartNumber = 1;
task = [client uploadPartCopy:part1];
[task waitUntilFinished];
TOSUploadPartCopyOutput *uploadOutput = task.result;
uploadOutput.tosETag = [uploadOutput.tosETag stringByReplacingOccurrencesOfString:@"\"" withString:@""];
// 3. CompleteMultipartUpload
TOSCompleteMultipartUploadInput *complete = [TOSCompleteMultipartUploadInput new];
complete.tosBucket = createOutput.bucket;
complete.tosKey = createOutput.key;
complete.tosUploadId = createOutput.uploadId;
NSMutableArray *array = [NSMutableArray array];
TOSUploadedPart *uploadedPart1 = [TOSUploadedPart new];
uploadedPart1.tosPartNumber = uploadOutput.tosPartNumber;
uploadedPart1.tosETag = uploadOutput.tosETag;
[array addObject:uploadedPart1];
complete.parts = array;
task = [client completeMultipartUpload:complete];
[task waitUntilFinished];
TOSCompleteMultipartUploadOutput *comleteOutput = task.result;
断点续传拷贝
断点续传拷贝在 TOS 服务端完成，无需先把源对象下载到本地。源对象和目标对象可以位于不同的桶中。
准备 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];
}
创建复制请求
static TOSResumableCopyObjectInput *TOSCreateCopyInput(
NSString *sourceBucket,
NSString *sourceObjectKey,
NSString *destinationBucket,
NSString *destinationObjectKey,
NSString *checkpointPath,
TOSCancelHook *cancelHook) {
TOSResumableCopyObjectInput *input =
[TOSResumableCopyObjectInput new];
input.tosSrcBucket = sourceBucket;
input.tosSrcKey = sourceObjectKey;
input.tosBucket = destinationBucket;
input.tosKey = destinationObjectKey;
// 分片大小。设置为 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.tosCopyEventListener = ^(TOSCopyEvent *event) {
if (event.tosType == TOSCopyEventUploadPartCopySucceed) {
NSLog(@"Copy part succeeded: %d",
event.tosCopyPartInfo.tosPartNumber);
} else if (event.tosType == TOSCopyEventUploadPartCopyFailed) {
NSLog(@"Copy part failed: %@", event.tosErr);
}
};
return input;
}
开始复制
NSString *sourceBucket = @"YOUR_SOURCE_BUCKET";
NSString *sourceObjectKey = @"example/source-large-file.bin";
NSString *destinationBucket = @"YOUR_DESTINATION_BUCKET";
NSString *destinationObjectKey = @"example/copied-large-file.bin";
NSString *copyCheckpoint = TOSCheckpointPath(@"copy-large-file.json");
TOSCancelHook *copyCancelHook = [TOSCancelHook new];
TOSResumableCopyObjectInput *copyInput =
TOSCreateCopyInput(sourceBucket,
sourceObjectKey,
destinationBucket,
destinationObjectKey,
copyCheckpoint,
copyCancelHook);
TOSTask *copyTask = [client resumableCopyObject:copyInput];
[copyTask continueWithBlock:^id(TOSTask *finishedTask) {
if (finishedTask.error) {
NSLog(@"Copy object failed: %@", finishedTask.error);
return nil;
}
TOSResumableCopyObjectOutput *output = finishedTask.result;
NSLog(@"Copy object succeeded, ETag: %@", output.tosETag);
return nil;
}];
暂停并恢复复制
当用户触发暂停操作时，调用以下接口暂停拷贝任务：
// 暂停复制，保留 checkpoint 和远端分片任务。
[copyCancelHook cancel:NO];
等待原任务完成回调后，复用相同源对象、目标对象、分片大小和 checkpoint 路径：
TOSCancelHook *newCopyCancelHook = [TOSCancelHook new];
TOSResumableCopyObjectInput *resumedCopyInput =
TOSCreateCopyInput(sourceBucket,
sourceObjectKey,
destinationBucket,
destinationObjectKey,
copyCheckpoint,
newCopyCancelHook);
TOSTask *resumedCopyTask = [client resumableCopyObject:resumedCopyInput];
[resumedCopyTask continueWithBlock:^id(TOSTask *finishedTask) {
if (finishedTask.error) {
NSLog(@"Resume copy failed: %@", finishedTask.error);
} else {
NSLog(@"Resume copy succeeded");
}
return nil;
}];
终止任务
调用 TOSCancelHook 可立即终止任务并清理续传状态，终止后再次调用对应接口时任务将从头开始。
通过各自请求中的 TOSCancelHook 终止任务：
// 终止复制
[copyCancelHook cancel:YES];
注意
请勿在任务成功或已经终止后继续复用旧的 TOSCancelHook。
最近更新时间：2026.09.29 16:01:16
这个页面对您有帮助吗？
有用
有用
无用
无用