OSSClient is the iOS client for Object Storage Service (OSS). It provides methods to manage resources such as buckets and objects. Before you use the SDK to send requests to OSS, initialize and configure an OSSClient instance.
The lifecycle of an OSSClient instance must match the lifecycle of your application. Create a global OSSClient instance when the application starts, and destroy the instance when the application ends.
Initialize an OSSClient
A mobile terminal is an untrusted environment. Storing your AccessKeyId and AccessKeySecret directly on the terminal to sign requests creates a high security risk. For better security, use Security Token Service (STS) authentication or self-signed mode.
Create an OSSClient instance in one of the following ways.
Create an OSSClient using STS
The following code shows how to create an OSSClient using STS.
// Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";
id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;Create an OSSClient using a custom domain name
The following code shows how to create an OSSClient using a custom domain name.
// Set yourEndpoint to a custom domain name.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";
id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;Create an OSSClient in an Apsara Stack or private domain environment
The following code shows how to create an OSSClient in an Apsara Stack or private domain environment.
// Set yourEndpoint to the endpoint of the region where the bucket is located.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";
id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// Skip CNAME resolution.
configuration.cnameExcludeList = @[endpoint];
configuration.signVersion = OSSSignVersionV4;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;Configure an OSSClient
ClientConfiguration is the configuration class for OSSClient. Use this class to configure parameters such as the proxy, connection timeout, and maximum number of connections.
Parameter | Description | Method |
maxRetryCount | The maximum number of retries for a failed request. The default value is 3. | configuration.maxRetryCount |
maxConcurrentRequestCount | The maximum number of concurrent requests. The default value is 5. | configuration.maxConcurrentRequestCount |
enableBackgroundTransmitService | Specifies whether to enable background tasks. By default, this feature is disabled. | configuration.enableBackgroundTransmitService |
backgroundSesseionIdentifier | The custom identifier for the background session. The default value is | configuration.backgroundSesseionIdentifier |
isHttpdnsEnable | Specifies whether to enable HttpDNS.
| configuration.isHttpdnsEnable |
timeoutIntervalForRequest | The request timeout interval. The default value is 15 seconds. | configuration.timeoutIntervalForRequest |
timeoutIntervalForResource | The resource timeout interval. The default value is 7 days. | configuration.timeoutIntervalForResource |
proxyHost | The host address of the proxy server. | configuration.proxyHost |
proxyPort | The port of the proxy server. | configuration.proxyPort |
userAgentMark | The User-Agent header in HTTP requests. | configuration.userAgentMark |
cnameExcludeList | The elements in this list will skip canonical name (CNAME) resolution. | configuration.cnameExcludeList |
crc64Verifiable | Specifies whether to enable 64-bit cyclic redundancy check (CRC64) verification. Valid values:
| configuration.crc64Verifiable |
isAllowUACarrySystemInfo | Specifies whether to allow the User-Agent to carry system information. Valid values:
| configuration.isAllowUACarrySystemInfo |
isFollowRedirectsEnable | Specifies whether to enable HTTP redirection. Valid values:
| configuration.isFollowRedirectsEnable |
The following code shows how to use ClientConfiguration to configure OSSClient parameters.
// Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
NSString *endpoint = @"yourEndpoint";
// The temporary AccessKey pair obtained from STS, which consists of an AccessKey ID and an AccessKey secret.
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
// The security token obtained from STS.
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"yourRegion";
id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:accessKeyId secretKeyId:accessKeySecret securityToken:securityToken];
OSSClientConfiguration *configuration = [OSSClientConfiguration new];
// Use Signature V4.
configuration.signVersion = OSSSignVersionV4;
// The maximum number of retries for a failed request.
configuration.maxRetryCount = 3;
// The maximum number of concurrent requests.
configuration.maxConcurrentRequestCount = 3;
// Specifies whether to enable background tasks.
configuration.enableBackgroundTransmitService = YES;
// The custom identifier for the background session.
configuration.backgroundSesseionIdentifier = @"yourBackgroundSesseionIdentifier";
// Specifies whether to enable HttpDNS.
configuration.isHttpdnsEnable = YES;
// The request timeout interval.
configuration.timeoutIntervalForRequest = 15;
// The resource timeout interval.
configuration.timeoutIntervalForResource = 24 * 60 * 60;
// The host address of the proxy server.
configuration.proxyHost = @"yourProxyHost";
// The port of the proxy server.
configuration.proxyPort = @8080;
// The User-Agent header in HTTP requests.
configuration.userAgentMark = @"yourUserAgent";
// The elements in this list will skip CNAME resolution.
configuration.cnameExcludeList = @[@"yourCname"];
// Specifies whether to enable CRC64 verification.
configuration.crc64Verifiable = YES;
// Specifies whether to allow the User-Agent to carry system information.
configuration.isAllowUACarrySystemInfo = YES;
// Specifies whether to enable HTTP redirection.
configuration.isFollowRedirectsEnable = NO;
OSSClient *client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credentialProvider clientConfiguration:configuration];
client.region = region;Enable logging
Mobile terminals operate in complex environments, and the OSS SDK may become unavailable in certain regions or at certain times. To help developers diagnose issues, the OSS SDK can record log information locally when logging is enabled. Before you use OSSClient, initialize it and call the following method to enable logging.
// Log format.
//2017/10/25 11:05:43:863 [Debug]: 17th time: <NSThread: 0x7f8099108580>{number = 3, name = (null)}
//2017/10/25 11:05:43:863 [Debug]: 15th time: <NSThread: 0x7f80976052c0>
//2017/10/25 11:05:43:863 [Debug]: ----------TestDebug------------
// Enable logging.
[OSSLog enableLog]; Log files are stored in the Caches/OSSLogs folder of the sandbox.
You can upload the files to your own server or use Alibaba Cloud Simple Log Service to upload the log files.
OSSTask
All API calls return an OSSTask.
OSSTask * task = [client getObject:get];You can configure the OSSTask.
To implement an asynchronous callback, set a continuation for the OSSTask.
[task continueWithBlock: ^(OSSTask *task) { // do something ... return nil; }];To implement a synchronous callback, wait for the OSSTask to complete.
[task waitUntilFinished];