All Products
Document Center

Quick start

Last Updated: May 04, 2018

The basic file upload and download processes are demonstrated as follows. For more information, see the following directories of this project:

ios demo: Click to view details

mac demo: Click to view details

swift demo: Click to view details

Test cases (see API usage): Click to view details

You can also run git clone project and configure the necessary parameters as follows:

Then run the demo as follows:



Reference that must be imported

  1. #import <AliyunOSSiOS/OSSService.h>

Step 1. Initialize the OSSClient

The initialization process mainly includes the following steps: endpoint settings, authentication mode settings, and client parameter settings. Three authentication modes are available: plain text setting mode, self-signed mode, and STS authentication mode.

To use the STS authentication, see Resource Access Management to learn more about the RAM. Assuming that you have activated the RAM service and learned the RAM service and how to obtain sub-account AccessKeyId, SecretKeyId, and RoleArn.

Complete the parameter information of AccessKeyId, SecretKeyId, and RoleArn in the script files. You can enable a local HTTP service with Python. Access local services using the client codes to obtain the StsToken.AccessKeyId, StsToken.SecretKeyId, and StsToken.SecurityToken.

For more information, see STS instructions in the sample. Click to view details.

  1. NSString *endpoint = "";
  2. // We recommend that you initialize OSSClient using STS on the mobile device. For more information, see STS instructions in the sample (
  3. id<OSSCredentialProvider> credential = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:@"AccessKeyId" secretKeyId:@"AccessKeySecret" securityToken:@"SecurityToken"];
  4. client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

Initialization of upload and download requests using the OSSClient is thread-safe. You can run multiple tasks concurrently.

Step 2. Upload a file

Assuming that you already have a bucket in the OSS console. An OSSTask is returned for each operation related to SDK. You can configure a continuation action for the task or call the waitUntilFinished block to wait until the task asynchronization completes.

  1. OSSPutObjectRequest * put = [OSSPutObjectRequest new];
  2. put.bucketName = @"<bucketName>";
  3. put.objectKey = @"<objectKey>";
  4. put.uploadingData = <NSData *>; // Upload NSData directly
  5. put.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
  6. NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
  7. };
  8. OSSTask * putTask = [client putObject:put];
  9. [putTask continueWithBlock:^id(OSSTask *task) {
  10. if (!task.error) {
  11. NSLog(@"upload object success!");
  12. } else {
  13. NSLog(@"upload object failed, error: %@" , task.error);
  14. }
  15. return nil;
  16. }];
  17. // Wait until the task is complete
  18. // [putTask waitUntilFinished];

Step 3. Download a specified file

Download a specified object as NSData:

  1. OSSGetObjectRequest * request = [OSSGetObjectRequest new];
  2. request.bucketName = @"<bucketName>";
  3. request.objectKey = @"<objectKey>";
  4. request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
  5. NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
  6. };
  7. OSSTask * getTask = [client getObject:request];
  8. [getTask continueWithBlock:^id(OSSTask *task) {
  9. if (!task.error) {
  10. NSLog(@"download object success!");
  11. OSSGetObjectResult * getResult = task.result;
  12. NSLog(@"download result: %@", getResult.downloadedData);
  13. } else {
  14. NSLog(@"download object failed, error: %@" ,task.error);
  15. }
  16. return nil;
  17. }];
  18. // Use a blocking call to wait until the task is complete
  19. // [task waitUntilFinished];


The MAC demo of is the same to the iOS demo but the importing method.

  1. import <AliyunOSSOSX/AliyunOSSiOS.h>