全部产品
Search
文档中心

对象存储 OSS:iOS初始化

更新时间:Dec 20, 2023

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

说明

OSSClient的生命周期需与应用程序的生命周期保持一致。即您需要在应用启动时创建一个全局的OSSClient,在应用结束时销毁OSSClient。

初始化OSSClient

重要

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

您可以通过以下多种方式新建OSSClient。

使用STS新建OSSClient

以下代码用于使用STS新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];

使用自定义域名新建OSSClient

以下代码用于使用自定义域名新建OSSClient。

// yourEndpoint填写自定义域名。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];

专有云或专有域环境新建OSSClient

以下代码用于在专有云或专有域环境新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// 跳过CNAME解析。
configuration.cnameExcludeList = @[endpoint];
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];

使用自签名模式新建OSSClient

以下代码用于使用自签名模式新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
NSString *endpoint = @"yourEndpoint";
// 通过您的自有服务器进行签名。
id<OSSCredentialProvider> credentialProvider = [[OSSCustomSignerCredentialProvider alloc] initWithImplementedSigner:^NSString * _Nullable(NSString * _Nonnull contentToSign, NSError *__autoreleasing  _Nullable * _Nullable error) {
    // 将content传给服务端进行签名,以服务器签名接口地址为http://localhost:8080/sign为例。
    NSString *urlString = [NSString stringWithFormat:@"http://localhost:8080/sign?content=%@", contentToSign];
    NSURL *url = [NSURL URLWithString:urlString];
    NSURLRequest *request = [NSURLRequest requestWithURL:url];
    OSSTaskCompletionSource *tcs = [OSSTaskCompletionSource taskCompletionSource];
    NSURLSession *session = [NSURLSession sharedSession];
    NSURLSessionTask *sessionTask = [session dataTaskWithRequest:request
                                               completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                      if (error) {
                                                       [tcs setError:error];
                                                       return;
                                                   }
                                                   [tcs setResult:data];
                                               }];
    [sessionTask resume];
    [tcs.task waitUntilFinished];
    if (tcs.task.error) {
        *error = tcs.task.error;
        return nil;
    } else {
        NSData* data = tcs.task.result;
        NSDictionary * object = [NSJSONSerialization JSONObjectWithData:data
                                                                options:kNilOptions
                                                                  error:nil];
        // 获取签名后的signature。
        NSString *signature = object[@"signature"];
        return signature;
    }
}];

OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider];

关于自签名模式的更多信息,请参见自签名模式

配置OSSClient

ClientConfiguration是OSSClient的配置类,您可通过此类来配置代理、连接超时、最大连接数等参数。

参数

描述

方法

maxRetryCount

请求失败后最大的重试次数。默认3次。

configuration.maxRetryCount

maxConcurrentRequestCount

最大并发数。默认为5。

configuration.maxConcurrentRequestCount

enableBackgroundTransmitService

是否开启后台任务,默认不开启。

configuration.enableBackgroundTransmitService

backgroundSesseionIdentifier

自定义后台会话标识符,默认值为com.aliyun.oss.backgroundsession

configuration.backgroundSesseionIdentifier

isHttpdnsEnable

是否开启httpDns。

  • true:2.10.14及以下版本默认开启httpDns。

  • false:2.10.14及以上版本默认关闭httpDns。

configuration.isHttpdnsEnable

timeoutIntervalForRequest

请求超时时间,默认15秒。

configuration.timeoutIntervalForRequest

timeoutIntervalForResource

资源超时时间,默认7天。

configuration.timeoutIntervalForResource

proxyHost

代理服务器主机地址。

configuration.proxyHost

proxyPort

代理服务器端口。

configuration.proxyPort

userAgentMark

用户代理中HTTP的User-Agent头。

configuration.userAgentMark

cnameExcludeList

列表中的元素将跳过CNAME解析。

configuration.cnameExcludeList

crc64Verifiable

是否开启CRC64校验。取值如下:

  • YES:开启CRC64校验。

  • NO(默认值):关闭CRC64校验。

configuration.crc64Verifiable

isAllowUACarrySystemInfo

是否允许User-Agent携带系统信息。取值如下:

  • YES:允许User-Agent携带系统信息。

  • NO(默认值):不允许User-Agent携带系统信息。

configuration.isAllowUACarrySystemInfo

isFollowRedirectsEnable

是否开启HTTP重定向。取值如下:

  • YES:开启HTTP重定向。

  • NO(默认值):关闭HTTP重定向。

configuration.isFollowRedirectsEnable

以下代码用于使用ClientConfiguration配置OSSClient参数。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
NSString *endpoint = @"yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// 请求失败后最大的重试次数。
configuration.maxRetryCount = 3;
// 最大并发数。
configuration.maxConcurrentRequestCount = 3;
// 是否开启后台任务。
configuration.enableBackgroundTransmitService = YES;
// 自定义后台会话标识符。
configuration.backgroundSesseionIdentifier = @"yourBackgroundSesseionIdentifier";
// 是否开启httpDns。
configuration.isHttpdnsEnable = YES;
// 请求超时时间。
configuration.timeoutIntervalForRequest = 15;
// 资源超时时间。
configuration.timeoutIntervalForResource = 24 * 60 * 60;
// 代理服务器主机地址。
configuration.proxyHost = @"yourProxyHost";
// 代理服务器端口。
configuration.proxyPort = @8080;
// 用户代理中HTTP的User-Agent头。
configuration.userAgentMark = @"yourUserAgent";
// 列表中的元素将跳过CNAME解析。
configuration.cnameExcludeList = @[@"yourCname"];
// 是否开启CRC校验。
configuration.crc64Verifiable = YES;
// 是否允许User-Agent携带系统信息。
configuration.isAllowUACarrySystemInfo = YES;
// 是否开启HTTP重定向。
configuration.isFollowRedirectsEnable = NO;

OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];

启用日志

移动端的使用环境比较复杂,部分区域或某个时段会出现无法正常使用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文件夹内。

  • 您可以自行选择将文件上传至服务器,或者选择接入阿里云日志服务上传日志文件。

OSSTask

  1. 所有调用API操作均会返回一个OSSTask。

    OSSTask * task = [client getObject:get];
  2. 设置OSSTask。

    • 为OSSTask设置延续 (continuation) 以实现异步回调。

      [task continueWithBlock: ^(OSSTask *task) {
          // do something
          ...
          return nil;
      }];
    • 等待OSSTask完成以实现同步回调。

      [task waitUntilFinished];