edit-icon download-icon

Initialization

Last Updated: Apr 04, 2018

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 the OSS Android SDK to initiate a request to OSS, you must first initialize an OSSClient instance and complete necessary settings.

Make sure that the life cycle of the OSS client is consistent with that of the application. Create an OSSClient when an application starts, and destroy it when the application ends.

Determine an endpoint

An endpoint is the address of Alibaba Cloud OSS in a region. It currently supports two formats.

Endpoint type Description
OSS region address Address of the region where an OSS bucket is located. Click here to view more
User-defined domain name Domain name defined by the user, with the CNAME directing to the OSS domain name

Click here to view more information about the endpoints.

OSS region address

You can use any of the following two methods to search for an endpoint mapped to the address of the region where an OSS bucket is located:

  • Query the mapping relationship between the endpoint and the region. Click here to view more.
  • Log on to the OSS consoleOSS console, open the Bucket Overview page, and find the suffix of the bucket domain. For example, the suffix oss-cn-hangzhou.aliyuncs.com of the bucket domain bucket-1.oss-cn-hangzhou.aliyuncs.com is the Internet endpoint of the bucket.

CNAME

You can bind your domain to a bucket using the CNAME and access the files in the bucket using the domain.

For example, if you want to bind the new-image.xxxxx.com domain to a bucket named image in Shenzhen: you must contact your domain hosting provider for xxxxx.com to configure a new domain name resolution record used to resolve http://new-image.xxxxx.com to http://image.oss-cn-shenzhen.aliyuncs.com.The record type is CNAME.

Configure the endpoint and credential

A mobile device is an untrusted environment. There is an extremely high risk if you store the AccessKeyId and AccessKeySecret in a mobile device for signing requests. We recommend that you only use plaintext settings for testing purposes. STS authentication mode or self-signed mode is recommended for business applications. For more information, see Resource Access Management and Direct Transfer on a Mobile Device.

If you are using STS authentication mode, we recommend you use OSSAuthCredentialProvider to access the application server because it automatically update expired tokens.

For more information, click here.

An example of how to set EndPoint and CredentialProvider is as follows:

  1. NSString *endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. //Access the authentication server directly (we recommended you use this access method because expired tokens are updated automatically).
  3. id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"An example of an authentication server address is http://abc.com."];
  4. client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];

Note: For more information about authentication modes, see Resource Access Management.

Configure the endpoint with the CNAME

If you have bound the CNAME to the bucket, you can configure the endpoint with the CNAME. For example:

  1. NSString *endpoint = "http://new-image.xxxxx.com";
  2. ...
  3. client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

Note: After Apple implements the support of the ATS standards, all endpoint URLs must be HTTPS URLs and the CNAME does not support credential settings currently, so you cannot set the Endpoint with the CNAME.

For more authentication modes, see Resource Access Management.

Enable logging

The application environment on a mobile device is relatively complicated. The OSS SDK may not work normally in some regions or for a certain period of time. To help developers locate problems, the OSS SDK records some log information on the local device when the logging feature is enabled. To enable logging, initialize OSSClient before use. You can follow these steps.

Note:

  • The log files are stored in the Caches/OSSLogs folder in the sandbox.
  • You can upload the log files to the server to further track the problems.
  • You can also access Alibaba Cloud Log Service to upload log files. See Log ServiceLog ServiceLog Service for more information.
  1. //Log formats
  2. //2017/10/25 11:05:43:863 [Debug]: The 17th attempt: <NSThread: 0x7f8099108580>{number = 3, name = (null)}
  3. //2017/10/25 11:05:43:863 [Debug]: The 15th attempt: <NSThread: 0x7f80976052c0>
  4. //2017/10/25 11:05:43:863 [Debug]: ----------TestDebug------------
  5. [OSSLog enableLog];//Run the method to enable logging

Set network parameters

You can set detailed ClientConfiguration during the initialization process as follows:

  1. NSString *endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
  2. //Access the authentication server directly (we recommended you use this access method because expired tokens are updated automatically).
  3. id<OSSCredentialProvider> credential = [[OSSAuthCredentialProvider alloc] initWithAuthServerUrl:@"An example of an authentication server address is http://abc.com."];
  4. client = [[OSSClient alloc] initWithEndpoint:endPoint credentialProvider:credential];
  5. OSSClientConfiguration * conf = [OSSClientConfiguration new];
  6. conf.maxRetryCount = 3; // The maximum number of retry attempts after a failed network request due to an exception
  7. conf.timeoutIntervalForRequest = 30; // Time-out value of the network requests
  8. conf.timeoutIntervalForResource = 24 * 60 * 60; // The longest time allowed for the resource transmission
  9. client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential clientConfiguration:conf];

OSSTask

For any operation that calls an API, an OSSTask is returned as follows:

  1. OSSTask * task = [client getObject:get];

You can configure a continuation for the task as follows to implement asynchronous callbacks.

  1. [task continueWithBlock: ^(OSSTask *task) {
  2. // do something
  3. ...
  4. return nil;
  5. }];

You can also wait for the task to finish as follows:

  1. [task waitUntilFinished];
Thank you! We've received your feedback.