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.
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
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];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.
Parameter | Description | Method |
maxRetryCount | The maximum number of retries when a request error occurs. Default value: 3. | configuration.maxRetryCount |
maxConcurrentRequestCount | The maximum number of parallel requests. Default value: 5. | configuration.maxConcurrentRequestCount |
enableBackgroundTransmitService | Specifies whether to enable background tasks. Default value: NO. | configuration.enableBackgroundTransmitService |
backgroundSesseionIdentifier | The custom identifier of the background session. Default value: | configuration.backgroundSesseionIdentifier |
isHttpdnsEnable | Specifies whether to enable HttpDNS.
| configuration.isHttpdnsEnable |
timeoutIntervalForRequest | The request timeout period. Unit: seconds. Default value: 15. | configuration.timeoutIntervalForRequest |
timeoutIntervalForResource | The resource timeout period. Unit: days. Default value: 7. | configuration.timeoutIntervalForResource |
proxyHost | The IP address that is used to access the proxy server. | configuration.proxyHost |
proxyPort | The port that is used to connect to the proxy server. | configuration.proxyPort |
userAgentMark | The User-Agent field in the HTTP headers. | configuration.userAgentMark |
cnameExcludeList | Specifies that CNAME resolution is skipped. | configuration.cnameExcludeList |
crc64Verifiable | Specifies whether to enable CRC-64. Default value: NO. Valid values:
| configuration.crc64Verifiable |
isAllowUACarrySystemInfo | Specifies whether to allow the User-Agent field to carry system information. Default value: NO. Valid values:
| configuration.isAllowUACarrySystemInfo |
isFollowRedirectsEnable | Specifies whether to enable HTTP redirection. Default value: No. Valid values:
| 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]; 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
An OSSTask is returned for all API operations that are called.
OSSTask * task = [client getObject:get];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];