SDK以动态库的形式呈现。请将KS3iOSSDK.framework添加到项目工程中。如果开发工具是Xcode6,请在project->target->General中的‘Embedded Binaries‘中添加KS3iOSSDK.framework
支持iOS6及以上版本
由于在App端明文存储AccessKey、SecretKey是极不安全的,因此推荐的使用场景如下图所示:
对应的初始化代码如下:
[[KS3Client initialize] connectWithAccessKey:strAccessKey withSecretKey:strSecretKey];
在KS3中,用户操作的基本数据单元是Object。单个Object允许存储0~48.8TB的数据。 Object 包含key和data。其中,key是Object的名字;data是Object 的数据。key为UTF-8编码,且编码后的长度不得超过1024个字符。
即Object的名字,key为UTF-8编码,且编码后的长度不得超过1024个字符。Key中可以带有斜杠,当Key中带有斜杠的时候,将会自动在控制台里组织成目录结构。
其他术语请参考概念与术语
为方便开发者使用,SDK在REST API接口返回值基础上进行了封装,具体更多封装类详情请见
SDK-REST API:
列出客户所有的 Bucket 信息
方法名:
- (NSArray *)listBuckets:(KS3ListBucketsRequest *)request
参数说明:
返回结果:
代码示例:
KS3ListBucketsRequest *request = [[KS3ListBucketsRequest alloc] init];
[request setBucket:@"bucket"];
NSArray *arrBuckets = [[KS3Client initialize] listBuckets:request];
创建一个新的Bucket
方法名:
- (KS3CreateBucketResponse *)createBucket:(KS3CreateBucketRequest *)request
参数说明:
返回结果:
代码示例:
KS3CreateBucketRequest *request = [[KS3CreateBucketRequest alloc] initWithName:@"bucket"];
KS3CreateBucketResponse *response = [[KS3Client initialize] createBucket:request];
删除指定Bucket
方法名:
- (KS3DeleteBucketResponse *)deleteBucket:(KS3DeleteBucketRequest *)bucketName;
参数说明:
返回结果:
代码示例:
KS3DeleteBucketRequest *request = [[KS3DeleteBucketRequest alloc] initWithName:@"bucket"];
KS3DeleteBucketResponse *response = [[KS3Client initialize] deleteBucket:request];
获取Bucket的ACL
方法名:
- (KS3GetACLResponse *)getBucketACL:(KS3GetACLRequest *)getACLRequest
参数说明:
返回结果:
代码示例:
KS3GetACLRequest *getACLRequest = [[KS3GetACLRequest alloc] initWithName:@"blues111"];
KS3GetACLResponse *response = [[KS3Client initialize] getBucketACL:getACLRequest];
KS3BucketACLResult *result = response.listBucketsResult;
if (response.httpStatusCode == 200) {
NSLog(@"Get bucket acl success!");
NSLog(@"Bucket owner ID: %@",result.owner.ID);
NSLog(@"Bucket owner displayName: %@",result.owner.displayName);
for (KS3Grant *grant in result.accessControlList) {
NSLog(@"%@",grant.grantee.ID);
NSLog(@"%@",grant.grantee.displayName);
NSLog(@"%@",grant.grantee.URI);
NSLog(@"%@",grant.permission);
}
}
else {
NSLog(@"Get bucket acl error: %@", response.error.description);
}
设置Bucket的ACL,以AccessControlList
方法名:
- (KS3SetGrantACLResponse *)setGrantACL:(KS3SetGrantACLRequest *)setGrantACLRequest;
参数说明:
返回结果:
代码示例:
KS3GrantAccessControlList *acl = [[KS3GrantAccessControlList alloc] init];
//设置权限为公共读
[acl setGrantControlAccess:KingSoftYun_Grant_Permission_Read];
//设置被授权人的id和name
acl.identifier = @"523678123";
acl.displayName = @"blues111";
KS3SetGrantACLRequest *request = [[KS3SetGrantACLRequest alloc] initWithName:@"" accessACL:acl];
KS3SetGrantACLResponse *response = [[KS3Client initialize] setGrantACL:request];
if (response.httpStatusCode == 200) {
NSLog(@"Set grant acl success!");
} else {
NSLog(@"Set grant acl error: %@", response.error.description);
}
查询是否已经存在指定Bucket
方法名:
- (KS3HeadBucketResponse *)headBucket:(KS3HeadBucketRequest *)headBucketRequest
参数说明:
返回结果:
代码示例:
KS3HeadBucketRequest *request = [[KS3HeadBucketRequest alloc] initWithName:@"blues111"];
KS3HeadBucketResponse *response = [[KS3Client initialize] headBucket:request];
if (response.httpStatusCode == 200) {
NSLog(@"Head bucket success!");
}
else {
NSLog(@"Head bucket error: %@", response.error.description);
}
下载该Object数据
方法名:
- (KS3DownLoad *)downloadObjectWithBucketName:(NSString *)strBucketName key:(NSString *)strObject downloadBeginBlock:(KS3DownloadBeginBlock)downloadBeginBlock downloadFileCompleteion:(KS3DownloadFileCompleteionBlock)downloadFileCompleteion downloadProgressChangeBlock:(KS3DownloadProgressChangeBlock)downloadProgressChangeBlock failedBlock:(KS3DownloadFailedBlock)failedBlock;
参数说明:
返回结果:
代码示例:
[[KS3Client initialize] downloadObjectWithBucketName:@"photo_hor.jpeg" key:@"alert1" downloadBeginBlock:^(KS3DownLoad *aDownload, NSURLResponse *responseHeaders) {
} downloadFileCompleteion:^(KS3DownLoad *aDownload, NSString *filePath) {
} downloadProgressChangeBlock:^(KS3DownLoad *aDownload, double newProgress) {
} failedBlock:^(KS3DownLoad *aDownload, NSError *error) {
}];
查询是否已经存在指定Object
方法名:
- (KS3HeadObjectResponse *)headObject:(KS3HeadObjectRequest *)headObjectRequest
参数说明:
返回结果:
代码示例:
KS3HeadObjectRequest *headObjRequest = [[KS3HeadObjectRequest alloc] initWithName:strBucketName withKeyName:strObjectName];
KS3HeadObjectResponse *response = [[KS3Client initialize] headObject:headObjRequest];
if (response.httpStatusCode == 200) {
NSLog(@"Head object success!");
}
else {
NSLog(@"Head object error: %@", response.error.description);
}
删除指定Object
方法名:
- (KS3DeleteObjectResponse *)deleteObject:(KS3DeleteObjectRequest *)deleteObjectRequest;
参数说明:
返回结果:
代码示例:
KS3DeleteObjectRequest *deleteObjRequest = [[KS3DeleteObjectRequest alloc] initWithName:strBucketName withKeyName:strObjectName];
KS3DeleteObjectResponse *response = [[KS3Client initialize] deleteObject:deleteObjRequest];
if (response.httpStatusCode == 200) {
NSLog(@"Delete object success!");
}
else {
NSLog(@"Delete object error: %@", response.error.description);
}
获得Object的acl
方法名:
- (KS3GetObjectACLResponse *)getObjectACL:(KS3GetObjectACLRequest *)getObjectACLRequest;
参数说明:
返回结果:
代码示例:
KS3GetObjectACLRequest *getObjectACLRequest = [[KS3GetObjectACLRequest alloc] initWithName:strBucketName withKeyName:strObjectName];
KS3GetObjectACLResponse *response = [[KS3Client initialize] getObjectACL:getObjectACLRequest];
KS3BucketACLResult *result = response.listBucketsResult;
if (response.httpStatusCode == 200) {
NSLog(@"Object owner ID: %@",result.owner.ID);
NSLog(@"Object owner displayName: %@",result.owner.displayName);
for (KS3Grant *grant in result.accessControlList) {
NSLog(@"%@",grant.grantee.ID);
NSLog(@"%@",grant.grantee.displayName);
NSLog(@"%@",grant.grantee.URI);
NSLog(@"%@",grant.permission);
}
}
else {
NSLog(@"Get object acl error: %@", response.error.description);
}
上传object的acl,以CannedAccessControlList形式
方法名:
- (KS3SetObjectACLResponse *)setObjectACL:(KS3SetObjectACLRequest *)setObjectACLRequest;
参数说明:
返回结果:
代码示例:
KS3AccessControlList *acl = [[KS3AccessControlList alloc] init];
//设置object的ACL为私有
[acl setContronAccess:KingSoftYun_Permission_Private];
KS3SetObjectACLRequest *setObjectACLRequest = [[KS3SetObjectACLRequest alloc] initWithName:strBucketName withKeyName:strObjectName acl:acl];
KS3SetObjectACLResponse *response = [[KS3Client initialize] setObjectACL:setObjectACLRequest];
if (response.httpStatusCode == 200) {
NSLog(@"Set object acl success!");
}
else {
NSLog(@"Set object acl error: %@", response.error.description);
}
上传object的acl,以AccessControlList形式
方法名:
- (KS3SetObjectGrantACLResponse *)setObjectGrantACL:(KS3SetObjectGrantACLRequest *)setObjectGrantACLRequest;
参数说明:
返回结果:
代码示例:
KS3GrantAccessControlList *acl = [[KS3GrantAccessControlList alloc] init];
//设置权限为公共读
[acl setGrantControlAccess:KingSoftYun_Grant_Permission_Read];
//设置被授权人的id和name
acl.identifier = @"436749834";
acl.displayName = @"blues111";
KS3SetObjectGrantACLRequest *request = [[KS3SetObjectGrantACLRequest alloc] initWithName:@"blues111" withKeyName:@"500.txt" grantAcl:acl];
KS3SetObjectGrantACLResponse *response = [[KS3Client initialize] setObjectGrantACL:request];
if (response.httpStatusCode == 200) {
NSLog(@"Set object grant acl success!");
}
else {
NSLog(@"Set object grant acl error: %@", response.error.description);
}
列举Bucket内的Object
方法名:
- (KS3ListObjectsResponse *)listObjects:(KS3ListObjectsRequest *)listObjectsRequest;
参数说明:
<IsTruncated>true</IsTruncated>
。类型:字符串默认:10000;delimiter:delimiter是用来对Object名字进行分组的一个字符。包含指定的前缀到第一次出现的delimiter字符的所有Object名字作为一组结果CommonPrefix。类型:字符串默认值:无返回结果:
代码示例:
KS3ListObjectsRequest *listObjectRequest = [[KS3ListObjectsRequest alloc] initWithName:@"blues111"];
KS3ListObjectsResponse *response = [[KS3Client initialize] listObjects:listObjectRequest];
KS3ListObjectsResult *_result = response.listBucketsResult;
NSMutableArray *_arrObjects = response.listBucketsResult.objectSummaries;
for (KS3ObjectSummary *objectSummary in _arrObjects) {
NSLog(@"%@",objectSummary.Key);
NSLog(@"%@",objectSummary.owner.ID);
}
NSLog(@"%@",_result.bucketName);
NSLog(@"%ld",_result.objectSummaries.count);
NSLog(@"%ld",_result.commonPrefixes.count);
NSLog(@"KS3ListObjectsResponse %d",response.httpStatusCode);
上传Object数据
方法名:
- (KS3PutObjectResponse *)putObject:(KS3PutObjectRequest *)putObjectRequest;
参数说明:
返回结果:
代码示例:
1.普通上传
/* 一定要实现委托方法 (这种情况如果实现委托,返回的reponse一般返回为nil,具体获取返回对象需要到委托方法里面获取,如果不实现委托,reponse不会为nil*/
KS3PutObjectRequest *putObjRequest = [[KS3PutObjectRequest alloc] initWithName:@"testcreatebucket-wf111" withAcl:nil grantAcl:nil];
//设置object权限为公开读
KS3AccessControlList *acl = [[KS3AccessControlList alloc] init];
[acl setContronAccess:KingSoftYun_Permission_Public_Read];
[putObjRequest setAcl:acl];
putObjRequest.delegate = self;
NSString *fileName = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"jpg"];
putObjRequest.data = [NSData dataWithContentsOfFile:fileName options:NSDataReadingMappedIfSafe error:nil];
putObjRequest.filename = [fileName lastPathComponent];
[[KS3Client initialize] putObject:putObjRequest];
2.有些情况下,如果希望KS3上传文件完成后通知服务端,需要注册回调参数。使用方法:
/* 一定要实现委托方法 (这种情况如果实现委托,返回的reponse一般返回为nil,具体获取返回对象需要到委托方法里面获取,如果不实现委托,reponse不会为nil*/
KS3PutObjectRequest *putObjRequest = [[KS3PutObjectRequest alloc] initWithName:@"testcreatebucket-wf111" withAcl:nil grantAcl:nil];
//设置object权限为公开读
KS3AccessControlList *acl = [[KS3AccessControlList alloc] init];
[acl setContronAccess:KingSoftYun_Permission_Public_Read];
[putObjRequest setAcl:acl];
putObjRequest.delegate = self;
NSString *fileName = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"jpg"];
putObjRequest.data = [NSData dataWithContentsOfFile:fileName options:NSDataReadingMappedIfSafe error:nil];
putObjRequest.filename = [fileName lastPathComponent];
//设置回调函数
putObjRequest.callbackUrl = @"http://123.59.36.81/index.php/api/photos/callback";
//设置回调参数,回调参数支持自定义参数、常量和魔法变量。如下所示:kss-location和kss-name为自定义参数,key和etag为魔法变量。
//支持的魔法变量详见上传回调处理说明文档([https://docs.ksyun.com/documents/956](https://docs.ksyun.com/documents/956))
putObjRequest.callbackBody = @"location=${kss-location}&name=${kss-name}&uid=8888&objectKey=${key}&etag=${etag}";
//设置自定义参数,必须以"kss-"开始
putObjRequest.callbackParams = @{@"kss-location": @"china_location", @"kss-name": @"lulu_name"};
[[KS3Client initialize] putObject:putObjRequest];
调用这个接口会初始化一个分块上传,KS3 Server会返回一个upload id, upload id 用来标识属于当前object的具体的块,并且用来标识完成分块上传或者取消分块上传
方法名:
- (KS3MultipartUpload *)initiateMultipartUploadWithKey:(NSString *)theKey withBucket:(NSString *)theBucket
参数说明:
返回结果:
代码示例:
KS3InitiateMultipartUploadRequest *request = [[KS3InitiateMultipartUploadRequest alloc] initWithKey:strObjectName inBucket:strBucketName acl:nil grantAcl:nil];
KS3MultipartUpload *upload = [[KS3Client initialize] initiateMultipartUploadWithRequest:request];
初始化分块上传后,上传分块接口。Part number 是标识每个分块的数字,介于0-10000之间。除了最后一块,每个块必须大于等于5MB,最后一块没有这个限制。
方法名:
- (KS3UploadPartResponse *)uploadPart:(KS3UploadPartRequest *)uploadPartRequest;
参数说明:
返回结果:
代码示例:
KS3UploadPartRequest *req = [[KS3UploadPartRequest alloc] initWithMultipartUpload:upload partNumber:partNumber data:data generateMD5:NO];
req.delegate = self;
KS3UploadPartResponse *response = [[KS3Client initialize] uploadPart:req];
罗列出已经上传的块
方法名:
- (KS3ListPartsResponse *)listParts:(KS3ListPartsRequest *)listPartsRequest;
参数说明:
返回结果:
代码示例:
KS3ListPartsRequest *req2 = [[KS3ListPartsRequest alloc] initWithMultipartUpload:_muilt];
KS3ListPartsResponse *response2 = [[KS3Client initialize] listParts:req2];
取消分块上传。
方法名:
- (KS3AbortMultipartUploadResponse *)abortMultipartUpload:(KS3AbortMultipartUploadRequest *)abortMultipartRequest
参数说明:
返回结果:
代码示例:
KS3AbortMultipartUploadRequest *request = [[KS3AbortMultipartUploadRequest alloc] initWithMultipartUpload:_muilt];
KS3AbortMultipartUploadResponse *response = [[KS3Client initialize] abortMultipartUpload:request];
if (response.httpStatusCode == 204) {
NSLog(@"Abort multipart upload success!");
}
else {
NSLog(@"error: %@", response.error.description);
}
组装之前上传的块,然后完成分块上传。通过你提供的xml文件,进行分块组装。在xml文件中,块号必须使用升序排列。必须提供每个块的ETag值。
方法名:
- (KS3CompleteMultipartUploadResponse *)completeMultipartUpload:(KS3CompleteMultipartUploadRequest *)completeMultipartUploadRequest;
参数说明:
返回结果:
代码示例:
KS3ListPartsResponse *response2 = [[KS3Client initialize] listParts:req2];
KS3CompleteMultipartUploadRequest *req = [[KS3CompleteMultipartUploadRequest alloc] initWithMultipartUpload:_muilt];
for (KS3Part *part in response2.listResult.parts) {
[req addPartWithPartNumber:part.partNumber withETag:part.etag];
}
[[KS3Client initialize] completeMultipartUpload:req];
分块上传代码示例
NSFileHandle *fileHandle = [NSFileHandle fileHandleForReadingAtPath:[[NSBundle mainBundle] pathForResource:@"bugDownload" ofType:@"txt"]];
long long fileLength = [[fileHandle availableData] length];
long long partLength = 5*1024.0*1024.0;
_partInter = (ceilf((float)fileLength / (float)partLength));
[fileHandle seekToFileOffset:0];
KS3InitiateMultipartUploadRequest *_muilt = [[KS3Client initialize] initiateMultipartUploadWithKey:@"500.txt" withBucket:@"blues111" inBucket:strBucketName acl:nil grantAcl:nil];
for (NSInteger i = 0; i < _partInter; i ++) {
NSData *data = nil;
if (i == _partInter - 1) {
data = [fileHandle readDataToEndOfFile];
}
else {
data = [fileHandle readDataOfLength:partLength];
[fileHandle seekToFileOffset:partLength*(i+1)];
}
KS3UploadPartRequest *req = [[KS3UploadPartRequest alloc] initWithMultipartUpload:_muilt];
req.delegate = self;
req.data = data;
req.partNumber = (int32_t)i+1;
req.contentLength = data.length;
[[KS3Client initialize] uploadPart:req];
}
// **** 分块上传的回调,每块上传结束后都会被调用
- (void)request:(KS3ServiceRequest *)request didCompleteWithResponse:(KS3ServiceResponse *)response {
_upLoadCount++;
if (_partInter == _upLoadCount) {
KS3ListPartsRequest *req2 = [[KS3ListPartsRequest alloc] initWithMultipartUpload:_muilt];
KS3ListPartsResponse *response2 = [[KS3Client initialize] listParts:req2];
KS3CompleteMultipartUploadRequest *req = [[KS3CompleteMultipartUploadRequest alloc] initWithMultipartUpload:_muilt];
NSLog(@" - - - - - %@",response2.listResult.parts);
for (KS3Part *part in response2.listResult.parts) {
[req addPartWithPartNumber:part.partNumber withETag:part.etag];
}
[[KS3Client initialize] completeMultipartUpload:req];
}
}
- (void)request:(KS3ServiceRequest *)request didFailWithError:(NSError *)error {
NSLog(@"error: %@", error.description);
}
分块上传接口可以实现断点续传等功能,但是由于使用比较复杂,SDK提供了一个封装后的接口——Ks3UploadManager。
使用本接口首先需要初始化一个KS3UploadManager实例。
self.uploadManager = [KS3UploadManager sharedInstanceWithClient:[KS3Client initialize] authHandler:nil];
KS3UploadManager接受唯一参数是authHandler
,此handler用于处理鉴权串签名,每次请求都会用本次请求的信息调用authHandler
,handler方法内,请求鉴权服务器拿到签名串返回即可。
authHandler如果为nil
,则需要在客户端设置AK、SK(这种方式不推荐)。设置方法为:[[KS3Client initialize] setCredentials:[[KS3Credentials alloc] initWithAccessKey:"YOUR_KS3_ACCESS_KEY" withSecretKey:"YOUR_KS3_SECRET_KEY"]];
。
实例创建好后,可以调用上传方法:
// 读取文件信息
NSString *strFilePath = [[NSBundle mainBundle] pathForResource:@"7.6M" ofType:@"mov"];
NSData *data = [NSData dataWithContentsOfFile:strFilePath];
KS3AccessControlList *acl = [[KS3AccessControlList alloc] init];
[acl setContronAccess:KingSoftYun_Permission_Public_Read];
// 创建一次开始分块的请求
KS3UploadRequest *uploadRequest = [[KS3UploadRequest alloc] initWithKey:@"uploadmanager/sample.mov" inBucket:kUploadBucketName acl:acl grantAcl:nil];
[uploadRequest setCompleteRequest];
[uploadRequest setStrKS3Token:[KS3Util getAuthorization:uploadRequest]];
// 开始上传
[self.uploadManager putData:data
request:uploadRequest
blockSize:1 * kMB
progress:^(NSString *key, double percent) {
NSLog(@"objectKey: %@, progress %lf", key, percent);
} cancelSignal:^BOOL(NSString *key) {
return false; // 修改这里进行取消
} complete:^(KS3Upload *upload, KS3Response *response) {
NSLog(@"uploadId: %@, response %@", upload.uploadId, response);
} error:^(KS3Upload *upload, NSError *error) {
NSLog(@"uploadId: %@, error: %@", upload.uploadId, error);
}];
目前此接口只支持使用NSData作为参数进行上传。
完整示例,请见 KS3-iOS-SDK-Demo
文档内容是否对您有帮助?
评价建议不能为空
非常感谢您的反馈,我们会继续努力做到更好!