OSSClient is the iOS client of Object Storage Service (OSS). OSSClient provides callers with a series of methods to manage buckets and objects. Before you use OSS SDK for iOS to initiate a request to OSS, you must initialize and configure an OSSClient instance.

Note Make sure that the lifecycle of the OSSClient instance is the same as the lifecycle of the application for which the instance is created. You must create an OSSClient instance when you start an application and release the instance when the application is stopped.

Initialize an OSSClient instance

Important A mobile device is used in various untrusted environments. It is highly risky to store AccessKeyId and AccessKeySecret in a mobile device to sign requests. We recommend that you access OSS in self-signed mode or by using the credentials that are obtained from Security Token Service (STS).

You can use one of the following methods to create an OSSClient instance:

Create an OSSClient instance by using STS

The following code provides an example on how to create an OSSClient instance by using STS:

// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
NSString *endpoint = @"yourEndpoint";
// Specify the temporary AccessKey pair obtained from STS. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// Specify the security token obtained from STS. 
NSString *securityToken = @"yourSecurityToken";

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

Create an OSSClient instance by using a custom domain name

The following code provides an example on how to create an OSSClient instance by using a custom domain name.

// Specify a custom domain name. 
NSString *endpoint = @"yourEndpoint";
// Specify the temporary AccessKey pair obtained from STS. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// Specify the security token obtained from STS. 
NSString *securityToken = @"yourSecurityToken";

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

Create an OSSClient instance in Apsara Stack or a private region

The following code provides an example on how to create an OSSClient instance in Apsara Stack or a private region:

// Specify the endpoint of the region in which the bucket is located. 
NSString *endpoint = @"yourEndpoint";
// Specify the temporary AccessKey pair obtained from STS. 
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// Specify the security token obtained from STS. 
NSString *securityToken = @"yourSecurityToken";

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

Create an OSSClient instance in self-signed mode

The following code provides an example on how to create an OSSClient instance in self-signed mode:

// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
NSString *endpoint = @"yourEndpoint";
// Sign the string on your own server. 
id<OSSCredentialProvider> credentialProvider = [[OSSCustomSignerCredentialProvider alloc] initWithImplementedSigner:^NSString * _Nullable(NSString * _Nonnull contentToSign, NSError *__autoreleasing  _Nullable * _Nullable error) {
    // Send content to the server for signing. content is the string that is concatenated based on the request parameters. In this example, http://localhost:8080/sign is used as the URL to sign the string. 
    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];
        // Obtain the signature. signature is the signed string. 
        NSString *signature = object[@"signature"];
        return signature;
    }
}];

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

For more information about the self-signed mode, see Self-signed mode.

Configure an OSSClient instance

ClientConfiguration is a configuration class of OSSClient. You can use ClientConfiguration to configure parameters such as proxy servers, connection timeouts, and the maximum number of connections.

ParameterDescriptionMethod
maxRetryCountThe maximum number of retries when a request error occurs. Default value: 3. configuration.maxRetryCount
maxConcurrentRequestCountThe maximum number of parallel requests. Default value: 5. configuration.maxConcurrentRequestCount
enableBackgroundTransmitServiceSpecifies whether to enable background tasks. Default value: NO. configuration.enableBackgroundTransmitService
backgroundSesseionIdentifierThe custom identifier of the background session. Default value: com.aliyun.oss.backgroundsession. configuration.backgroundSesseionIdentifier
isHttpdnsEnableSpecifies whether to enable HttpDNS.
  • true: enables HttpDNS. For OSSClient whose version is earlier than 2.10.14, true is the default value.
  • false: disables HttpDNS. For OSSClient 2.10.14 and later, false is the default value.
configuration.isHttpdnsEnable
timeoutIntervalForRequestThe request timeout period. Unit: seconds. Default value: 15. configuration.timeoutIntervalForRequest
timeoutIntervalForResourceThe resource timeout period. Unit: days. Default value: 7. configuration.timeoutIntervalForResource
proxyHostThe IP address that is used to access the proxy server. configuration.proxyHost
proxyPortThe port that is used to connect to the proxy server. configuration.proxyPort
userAgentMarkThe User-Agent field in the HTTP headers. configuration.userAgentMark
cnameExcludeListSpecifies that CNAME resolution is skipped. configuration.cnameExcludeList
crc64VerifiableSpecifies whether to enable CRC-64. Default value: NO. Valid values:
  • YES: enables CRC-64.
  • NO: disables CRC-64.
configuration.crc64Verifiable
isAllowUACarrySystemInfoSpecifies whether to allow the User-Agent field to carry system information. Default value: NO. Valid values:
  • YES: allows the User-Agent field to carry system information.
  • NO: does not allow the User-Agent field to carry system information.
configuration.isAllowUACarrySystemInfo
isFollowRedirectsEnableSpecifies whether to enable HTTP redirection. Default value: No. Valid values:
  • YES: enables HTTP redirection.
  • NO: disables HTTP redirection.
configuration.isFollowRedirectsEnable

The following code provides an example on how to configure parameters for an OSSClient instance by using ClientConfiguration:

// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
NSString *endpoint = @"yourEndpoint";
// Specify the temporary AccessKey pair obtained from STS. 
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// Specify the security token obtained from STS. 
NSString *securityToken = @"yourSecurityToken";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// Specify the maximum number of retries when a request error occurs. 
configuration.maxRetryCount = 3;
// Specify the maximum number of parallel requests. 
configuration.maxConcurrentRequestCount = 3;
// Specify whether to enable background tasks. 
configuration.enableBackgroundTransmitService = YES;
// Specify a custom identifier for the background session. 
configuration.backgroundSesseionIdentifier = @"yourBackgroundSesseionIdentifier";
// Specify whether to enable httpDns. 
configuration.isHttpdnsEnable = YES;
// Specify a request timeout period. 
configuration.timeoutIntervalForRequest = 15;
// Specify a resource timeout period. 
configuration.timeoutIntervalForResource = 24 * 60 * 60;
// Specify the IP address that is used to access the proxy server. 
configuration.proxyHost = @"yourProxyHost";
// Specify the port of the proxy server. 
configuration.proxyPort = @8080;
// Specify the User-Agent field in the HTTP headers. 
configuration.userAgentMark = @"yourUserAgent";
// Specify that CNAME resolution is skipped. 
configuration.cnameExcludeList = @[@"yourCname"];
// Specify whether to enable CRC-64. 
configuration.crc64Verifiable = YES;
// Specify whether to allow the User-Agent field to carry system information. 
configuration.isAllowUACarrySystemInfo = YES;
// Specify whether to enable HTTP redirection. 
configuration.isFollowRedirectsEnable = NO;

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

Enable logging

Mobile devices are used in various environments. OSS SDK for iOS is unavailable in specific regions or during specific periods of time. To identify possible issues, you can enable logging to allow OSS SDK for iOS to record logs in the local client. Before you use OSSClient, initialize the OSSClient instance and call the following method to enable logging:
// Specify the log format. 
//2017/10/25 11:05:43:863  [Debug]: the 17th: <NSThread: 0x7f8099108580>{number = 3, name = (null)}
//2017/10/25 11:05:43:863  [Debug]: the 15th: <NSThread: 0x7f80976052c0>
//2017/10/25 11:05:43:863  [Debug]: ----------TestDebug------------
// Enable logging. 
[OSSLog enableLog];                
Note
  • Logs are stored in the Caches/OSSLogs directory of the sandbox.
  • You can upload the logs to the server or Alibaba Cloud Log Service.

OSSTask

  1. An OSSTask is returned for all API operations that are called.
    OSSTask * task = [client getObject:get];
  2. Specify OSSTask.
    • Configure continuation for the OSSTask to implement asynchronous callbacks:
      [task continueWithBlock: ^(OSSTask *task) {
          // do something
          ...
          return nil;
      }];
    • Wait until the OSSTask is complete to implement synchronous callbacks:
      [task waitUntilFinished];