初始化 - 对象存储 OSS

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

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

确定Endpoint

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

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

假设您要将自定义域名example.aliyundoc.com绑定到华东1（杭州）地域名为examplebucket的存储空间。您需要到您的域名aliyundoc.com托管商处设定一个新的域名解析，并将https://example.aliyundoc.com解析到https://examplebucket.oss-cn-hangzhou.aliyuncs.com ，类型为CNAME。

设置EndPoint和凭证

移动终端是一个不受信任的环境，把AccessKey ID和AccessKey Secret直接保存在终端用来加签请求，存在极高的风险。推荐使用STS鉴权模式或自签名模式。

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

设置EndPoint和CredentialProvider示例如下：

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

stsServer接口返回的数据格式如下：

{
  // 获取Token的状态。获取成功时，返回值是200。
  "StatusCode": 200,
  // iOS移动应用初始化OSSClient获取的AccessKey ID。
  "AccessKeyId":"STS.iA645eTOXEqP3cg3****",
  // iOS移动应用初始化OSSClient获取AccessKey Secret。
  "AccessKeySecret":"rV3VQrpFQ4BsyHSAvi5NVLpPIVffDJv4LojU****",  
  // iOS移动应用初始化获取的Token。
  "SecurityToken":"CAES7QIIARKAAZPlqaN9ILiQZPS+JDkS/GSZN45RLx4YS/p3OgaUC+oJl3XSlbJ7StKpQ****",
  // Token的失效时间。iOS SDK会自动判断Token是否失效。如果Token失效，iOS SDK将自动获取Token。
  "Expiration":"2015-11-03T09:52:59Z"  
}

设置EndPoint为CNAME

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

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

启用日志

移动端的使用环境比较复杂。部分区域或某个时段会出现无法正常使用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文件夹内。
您可以自行选择将文件上传至服务器，便于进一步追踪问题。您还可以接入阿里云日志服务进行日志文件上传。

设置ClientConfiguration

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

NSString *endpoint = @"https://oss-cn-hangzhou.aliyuncs.com";
NSString *stsServer = @"应用服务器地址，例如https://example.com:8080";
// 推荐使用OSSAuthCredentialProvider，token过期后会自动刷新。
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:stsServer];

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];