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.
Initialize an OSSClient instance
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.
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: com.aliyun.oss.backgroundsession . | 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
// 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];
- Configure continuation for the OSSTask to implement asynchronous callbacks: