阿里云 OSS SDK for iOS
中文 README
介绍
本文档主要描述了如何安装和使用 OSS iOS SDK。本文档假设您已经激活了阿里云 OSS 服务并创建了 AccessKeyID 和 AccessKeySecret。在文档中,ID 指的是 AccessKeyID,而 KEY 指示的是 AccessKeySecret。如果您尚未激活或不知道 OSS 服务,请访问 OSS 产品页面 以获取更多帮助。
环境要求
- iOS 8.0 或更高版本。
- 您必须使用已经激活OSS服务的阿里云账户注册。
安装
直接引入框架
需要引入OLS iOS SDK框架。
您可以使用 AliyunOSSSDK.xcworkspace,选择名为 AliyunOSSSDK OSX 的方案,在 MacOS 中直接生成框架。
# Clone the project
$ git clone [email protected]:aliyun/aliyun-oss-ios-sdk.git
# Enter the directory
$ cd aliyun-oss-ios-sdk
# Run the packaging script
$ sh ./buildiOSFramework.sh
# Enter the generated packaging directory where the AliyunOSSiOS.framework will be generated
$ cd Products && ls
在 Xcode 中,将 OSS iOS SDK 框架拖动到目标上,并在弹出的框中选择 如果有需要则复制项目。
Pod依赖
如果您的项目使用Pod管理依赖,请将以下依赖项添加到Podfile中。在这种情况下,您不需要导入OSS iOS SDK框架。
pod 'AliyunOSSiOS'
CocoaPods 是一款出色的依赖管理器。推荐官方参考文档:CocoaPods 安装和使用教程。
您可以直接引入OSS iOS SDK框架或Pod依赖,两种方法都可行。
将头文件引入项目
#import <AliyunOSSiOS/AliyunOSSiOS.h>
注意: 在引入 OSS iOS SDK 框架后,请在项目的 构建设置 中的 其他链接器标志 添加 -ObjC
。如果您的项目已配置了 -force_load
选项,请添加 -force_load <框架路径>/AliyunOSSiOS
。
仅支持 IPv6 网络兼容性
OSS 移动 SDK 已经引入了 HTTPDNS 用于域名解析,以解决无线网络中的域名解析劫持问题,并直接使用 IP 地址请求服务器。在仅支持 IPv6 的网络中,可能会出现兼容性问题。应用已正式发布应用审查要求,要求应用支持仅支持 IPv6 网络兼容。为此,SDK 从 V2.5.0 版本开始提供兼容性。在新版本中,除了 -ObjC
设置之外,还应引入两个系统库
libresolv.tbd
SystemConfiguration.framework
CoreTelephony.framework
苹果的 ATS 策略
在 2016 年的 WWDC 上,苹果宣布从 2017 年 1 月 1 日起,苹果 App Store 中的所有应用必须启用 App Transport Security(ATS)。也就是说,默认情况下,不允许新提交的应用使用 NSAllowsArbitraryLoads
来绕过 ATS 限制。我们最好确保应用的所有网络请求都是 HTTPS 加密的。否则,应用可能无法通过审查。
此 SDK 在 V2.6.0 及以上版本中提供支持。具体来说,SDK 不会发出任何非 HTTPS 请求。同时,SDK 支持带有 https://
前缀的 端点。您只需设置正确的 HTTPS 端点,以确保所有网络请求都符合要求。
注意
- 使用带有
https://
前缀的URL设置端点。 - 确保在实现签名和获取STSToken回调时应用程序不会发送非HTTPS请求。
OSSTask描述
对于所有调用API的操作,您将立即获得一个OSSTask。
OSSTask * task = [client getObject:get];
您可以为任务配置一个延续以实现异步回调。例如,
[task continueWithBlock: ^(OSSTask *task) {
// do something
...
return nil;
}];
您也可以等待到任务完成(同步等待)。例如,
[task waitUntilFinished];
...
快速开始
以下展示了基本的对象上传和下载过程。有关详细信息,您可以参考以下项目的以下目录。
测试: 点击查看详情;
或
示例: 点击查看详情。
步骤 1. 初始化 OSSClient
我们建议在移动设备上使用STS身份验证模式初始化OSSClient。有关身份验证的详细信息,请参阅以下链接中提供的完整官方文档的访问控制部分。
注意:如果您的应用程序的存储桶仅在数据中心,我们建议保持OSSClient的实例与您的应用程序的生命周期一致。下面的代码示例展示了使用方法:
@interface AppDelegate ()
@property (nonatomic, strong) OSSClient *client;
@end
/**
* the url to fetch sts info,for detail please refer to https://help.aliyun.com/document_detail/31920.html
*/
#define OSS_STS_URL @"oss_sts_url"
/**
* the endpoint for OSS used in app, for detail please refer to https://help.aliyun.com/document_detail/31837.html
*/
#define OSS_ENDPOINT @"your bucket's endpoint"
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
// initialize OSSClient
[self setupOSSClient];
return YES;
}
- (void)setupOSSClient {
// initialize credential provider,which auto fetch and update sts info from sts url.
OSSAuthCredentialProvider *credentialProvider = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:OSS_STS_URL];
// set config for oss client networking
OSSClientConfiguration *cfg = [[OSSClientConfiguration alloc] init];
_client = [[OSSClient alloc] initWithEndpoint:OSS_ENDPOINT credentialProvider:credentialProvider clientConfiguration:cfg];
}
步骤-2. 上传文件
假设您在OSS控制台中有一个桶。每次SDK操作后,都会返回一个OSSTask。您可以配置任务的延续以实现异步回调。您还可以使用waitUntilFinished来阻塞其他请求并等待任务完成。
OSSPutObjectRequest * put = [OSSPutObjectRequest new];
put.bucketName = @"<bucketName>";
put.objectKey = @"<objectKey>";
put.uploadingData = <NSData *>; // Directly upload NSData
put.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
};
OSSTask * putTask = [client putObject:put];
[putTask continueWithBlock:^id(OSSTask *task) {
if (!task.error) {
NSLog(@"upload object success!");
} else {
NSLog(@"upload object failed, error: %@" , task.error);
}
return nil;
}];
// Wait until the task is finished
// [putTask waitUntilFinished];
步骤-3. 下载指定的对象
以下代码以NSData的形式下载指定的对象。
OSSGetObjectRequest * request = [OSSGetObjectRequest new];
request.bucketName = @"<bucketName>";
request.objectKey = @"<objectKey>";
request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
};
OSSTask * getTask = [client getObject:request];
[getTask continueWithBlock:^id(OSSTask *task) {
if (!task.error) {
NSLog(@"download object success!");
OSSGetObjectResult * getResult = task.result;
NSLog(@"download result: %@", getResult.downloadedData);
} else {
NSLog(@"download object failed, error: %@" ,task.error);
}
return nil;
}];
// Use a blocking call to wait until the task is finished
// [task waitUntilFinished];
完整文档
SDK提供了高级的上传、下载、断点续传上传/下载、对象管理以及桶管理功能。详细信息请参阅完整的官方文档:[点击查看详情](https://help.aliyun.com/document_detail/32055.html)。
API文档
常见问题解答
1. 如何支持 armv7s?
Arm 兼容向下兼容,Armv7 库也适用于需要支持 armv7s 的应用程序。如果您还需要优化 armv7s,可以按照以下设置。
许可证
- Apache License 2.0.
联系我们
- 阿里云OSS官方网站.
- 阿里云OSS官方论坛.
- 阿里云OSS官方文档中心.
- 阿里云官方技术支持:[提交工单](https://workorder.console.aliyun.com/#/ticket/createIndex)。