The OSSClient is the iOS client of OSS. It provides the caller with a series of methods to operate and manage buckets and objects. Before you use OSS SDK for iOS to initiate a request to OSS, you need to first initialize an OSSClient instance and complete necessary settings.

Note

Ensure that the lifecycle of the OSSClient is consistent with that of the application. When an application is started, create an OSSClient instance. When the application is ended, release the instance.

Determine an endpoint

An endpoint is the URL of Alibaba Cloud OSS in a region. The following table describes the supported formats of OSS endpoints.

Endpoint type Description
OSS endpoint The URL of the region where the bucket is located. For more information about the endpoints of each region, see Regions and endpoints.
Custom domain name The domain name provided by the user. You can configure a CNAME record to map the a custom domain name to an OSS domain name.
  • OSS endpoints

    When you use the endpoint of a bucket, you can query the endpoint in either of the following ways:

    • For more information about how to query the relationship between the endpoint and region, see Regions and endpoints.
    • You can log on to the OSS console. In the left-side navigation pane, locate the Buckets section, enter bucket-1 in the search box, and click the search icon. Click the bucket name to go to the Overview tab. In the Domain Names section, the suffix of bucket-1.oss-cn-hangzhou.aliyuncs.com is oss-cn-hangzhou.aliyuncs.com, which is the endpoint for Internet access.
  • Custom domain name

    Use CNAME to bind a custom domain name to a bucket. Use the custom domain name to access objects in the bucket.

    For example, if you bind the new-image.xxxxx.com domain name to the bucket named image in China (Shenzhen): Contact your DNS provider of xxxxx.com to configure a new CNAME record. This record is used to resolve http://new-image.xxxxx.com to http://image.oss-cn-shenzhen.aliyuncs.com. The record type is CNAME.

Configure an endpoint and credential

A mobile device is an untrusted environment. It is highly risky to store AccessKeyId and AccessKeySecret in a mobile device to sign requests. We recommend that you use STS Authentication Mode or Self-signed Mode. For more information, see Authorized access and Set up direct data transfer for mobile apps.

Note If the STS authentication mode is used, we recommend that you use OSSAuthCredentialsProvider to directly access STS. The token is automatically updated after it expires.

The following code provides an example on how to configure the Endpoint and CredentialProvider fields:

NSString *endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// Use the AccessKey ID and AccessKey secret that are issued by Alibaba Cloud to create a credential provider.
// We recommend that you use OSSAuthCredentialProvider. The token is automatically updated after it expires.
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"Application server address such as http://abc.com:8080"];
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];
			

Set the Endpoint field to CNAME

If you bind CNAME to a bucket, you can set the Endpoint field to CNAME.

NSString *endpoint = "http://new-image.xxxxx.com";
// We recommend that you use OSSAuthCredentialProvider. The token is automatically updated after it expires.
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"Application server address such as http://abc.com:8080"];
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];
			
Notice After Apple implemented the ATS standard, all Endpoint URLs must be HTTPS URLs. However, domain names set by CNAME do not support certificate settings. Therefore, you cannot use CNAME to set the Endpoint field.

Enable logging

Mobile devices are used in various environments. OSS SDKs cannot provide normal services in some regions or in a period of time. To further locate problems developers encounter, OSS SDKs record the log information locally after logging is enabled. Before you use the OSSClient, initialize the OSSClient instance and call the following method to enable logging:
// The log entry style.
//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------------
[OSSLog enableLog];// Perform this method to enable logging.
				
Note
  • Logs are stored in the Caches/OSSLogs folder of the sandbox.
  • You can upload logs to the server to further track problems.

You can also access Alibaba Cloud Log Service to upload logs.

Configure ClientConfiguration

The following code provides an example on how to configure ClientConfiguration in detail during the initialization process:

NSString *endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// We recommend that you use OSSAuthCredentialProvider. The token is automatically updated after it expires.
id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"Application server address such as http://abc.com:8080"];
                                                                                                        
OSSClientConfiguration * conf = [OSSClientConfiguration new];
conf.maxRetryCount = 3; // The number of retry attempts after the network request fails due to exceptions.
conf.timeoutIntervalForRequest = 30; // The timeout period of a network request.
conf.timeoutIntervalForResource = 24 * 60 * 60; // The maximum timeout period for resource transmission.
client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential clientConfiguration:conf];
			

OSSTask

An OSSTask is immediately returned for all OSS operations that are called. Example:

OSSTask * task = [client getObject:get];

To implement an asynchronous callback, you can configure a continuation for the task. Example:

[task continueWithBlock: ^(OSSTask *task) {
    // do something
    ...
    return nil;
}];
You can also wait until the task is complete (synchronous wait). Example:
[task waitUntilFinished];