OSSClient是OSS服务的iOS客户端,它为调用者提供了一系列的方法,可以用来操作存储空间(Bucket)和文件(Object)等。在使用SDK发起OSS请求前,您需要初始化一个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将自定义域名绑定到某个存储空间上,然后通过该域名访问存储空间内的文件。

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

设置EndPoint和凭证

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

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

设置EndPoint和CredentialProvider示例如下:

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

设置EndPoint为CNAME

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

NSString *endpoint = "https://example.aliyundoc.com";
// 推荐使用OSSAuthCredentialProvider,token过期后会自动刷新。
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"应用服务器地址,例如https://example.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:@"应用服务器地址,例如https://example.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];