初始化 - 对象存储 OSS

OSSClient 是OSS 服务的 iOS 客户端，它为调用者提供了一系列的方法，可以用来操作，管理存储空间（Bucket）和文件（Object）等。在使用 SDK 发起 OSS 请求前，您需要初始化一个 OSSClient 实例，并对其进行一些必要设置。

说明

OSSClient 的生命周期和应用程序的生命周期保持一致即可。在应用程序启动时创建一个 OSSClient 实例，在应用程序结束时释放即可。

确定 Endpoint

Endpoint 是阿里云 OSS 服务在各个区域的地址，目前支持两种形式：


Endpoint 类型	解释
OSS 区域地址	使用 OSS Bucket 所在区域地址，各个区域Endpoint参考访问域名和数据中心。
用户自定义域名	用户自定义域名，且 CNAME 指向 OSS 域名。

OSS 区域地址
使用 OSS Bucket 所在区域地址时，您可以通过以下两种方式查询 Endpoint：
- 查询 Endpoint 与区域对应关系详情，可以参考访问域名和数据中心。
- 您可以登录阿里云 OSS 管理控制台，进入 Bucket 概览页，Bucket 域名bucket-1.oss-cn-hangzhou.aliyuncs.com的后缀部分oss-cn-hangzhou.aliyuncs.com，即为该 Bucket 的外网 Endpoint。
用户自定义域名
通过 CNAME 将自定义域名绑定到某个存储空间上，然后通过该域名访问存储空间内的文件。

假设您要将域名 new-image.xxxxx.com 绑定到深圳区域名称为 image 的存储空间。您需要到您的域名xxxxx.com托管商处设定一个新的域名解析，并将http://new-image.xxxxx.com 解析到 http://image.oss-cn-shenzhen.aliyuncs.com ，类型为 CNAME。

设置 EndPoint 和凭证

移动终端是一个不受信任的环境，把AccessKeyId和AccessKeySecret直接保存在终端用来加签请求，存在极高的风险。推荐使用STS鉴权模式或自签名模式，详情请参考访问控制、移动端直传。

说明如果用 STS 鉴权模式，推荐使用 OSSAuthCredentialsProvider 方式直接访问鉴权应用服务器，token 过期后将自动更新。

设置 EndPoint 和 CredentialProvider 示例如下：

NSString *endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 由阿里云颁发的AccessKeyId/AccessKeySecret构造一个CredentialProvider。
// 推荐使用OSSAuthCredentialProvider，token过期后会自动刷新。
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"应用服务器地址，例如http://abc.com:8080"];
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];

设置 EndPoint 为 CNAME

如果您已经在 Bucket 上绑定 CNAME，将该 Endpoint 设置为 CNAME 即可。

NSString *endpoint = "http://new-image.xxxxx.com";
// 推荐使用OSSAuthCredentialProvider，token过期后会自动刷新。
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"应用服务器地址，例如http://abc.com:8080"];
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];

注意苹果要求支持 ATS 标准后，所有 Endpoint URL 都必须为 HTTPS URL，而 CNAME 域名暂不支持证书设置，因此暂时不能用 CNAME 设置 Endpoint。

启用日志

移动端的使用环境比较复杂。部分区域或某个时段会出现无法正常使用 OSS SDK 的情况。为了进一步定位开发者遇到的问题，OSS SDK 在开启日志记录功能后，会将日志信息记录在本地。在使用 OSSClient 前进行初始化，并调用如下方法开启日志记录。

//日志的样式
//2017/10/25 11:05:43:863  [Debug]: 第17次：<NSThread: 0x7f8099108580>{number = 3, name = (null)}
//2017/10/25 11:05:43:863  [Debug]: 第15次：<NSThread: 0x7f80976052c0>
//2017/10/25 11:05:43:863  [Debug]: ----------TestDebug------------
[OSSLog enableLog];//执行该方法，开启日志记录

说明

文件存储在沙盒的 Caches/OSSLogs 文件夹内。
您可以自行选择将文件上传至服务器，便于进一步追踪问题。

您还可以接入阿里云日志服务 LOG 进行日志文件上传。

设置 ClientConfiguration

以下代码用于初始化时设置详细的 ClientConfiguration：

NSString *endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 推荐使用OSSAuthCredentialProvider，token过期后会自动刷新。
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"应用服务器地址，例如http://abc.com:8080"];
                                                                                                        
OSSClientConfiguration * conf = [OSSClientConfiguration new];
conf.maxRetryCount = 3; // 网络请求遇到异常失败后的重试次数
conf.timeoutIntervalForRequest = 30; // 网络请求的超时时间
conf.timeoutIntervalForResource = 24 * 60 * 60; // 允许资源传输的最长时间
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential clientConfiguration:conf];

OSSTask

所有调用 API 的操作都会立即获得一个 OSSTask，如：

OSSTask * task = [client getObject:get];

您可以为这个 Task 设置延续 (continution) 以实现异步回调，如：

[task continueWithBlock: ^(OSSTask *task) {
    // do something
    ...
    return nil;
}];

您还可以等待这个 Task 完成以实现同步等待，如：

[task waitUntilFinished];