OSS Harmony SDK Quick Start - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to use Object Storage Service (OSS) SDK for Harmony to perform common operations. You can learn how to install OSS SDK for Harmony, configure access credentials, and perform basic operations, such as creating buckets and uploading, downloading, listing, and deleting objects.

Usage notes

For more information about the regions and endpoints, see Regions and endpoints.

Install OSS SDK for Harmony

Warning

OSS SDK for Harmony is in public preview. We recommend that you do not use it directly in a production environment. To deploy it in a production environment, conduct sufficient tests to ensure its stability and compatibility.

Before you install and use OSS SDK for Harmony, download and install DevEco Studio and Command Line Tools by referring to the Huawei developer website.
Run the following command in OpenHarmony Package Manager Command-line Interface (OHPM CLI) to install OSS SDK for Harmony:
```
ohpm install @aliyun/oss
```
Run the following command to check whether OSS SDK for Harmony is installed and view its version:
```
ohpm list
```
The following response indicates that OSS SDK for Harmony is installed:
```
your-project-name@1.0.0 /path/to/your/project
└── @aliyun/oss@1.0.0-beta.1 
```
Run the following command to import OSS SDK for Harmony:
```
import Client, { RequestError } from '@aliyun/oss';
```

Quick start

The following demo describes how to create a bucket and upload, download, list, and delete objects.

Warning

In the following example, temporary access credentials obtained from Security Token Service (STS) are used by default. Make sure that you have obtained the temporary access credentials. You can obtain the temporary access credentials using one of the following methods:

You can obtain temporary access credentials by calling the AssumeRole operation. For more information, see AssumeRole.
You can also obtain temporary access credentials using the SDK. For more information, see Access OSS using an STS token.

Create a bucket

import Client, { RequestError, EBucketAcl, EStorageClass } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

const putBucket = async () => {
  try {
    // Use the putBucket method to create a bucket and pass the name of the bucket as a parameter.
    const res = await client.putBucket({
      bucket: 'yourBucketName' // Specify the name of the bucket.
    });

    // Display the result of the bucket creation operation.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display detailed error information.
      console.log('code: ', err.code);
      console.log('message: ', err.message);
      console.log('requestId: ', err.requestId);
      console.log('status: ', err.status);
      console.log('ec: ', err.ec);
    } else {
      // Display unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the putBucket function to create a bucket.
putBucket();

Upload an object

import Client, { EObjectAcl, EStorageClass, FilePath, RequestError } from '@aliyun/oss';
import { fileIo as fs } from '@kit.CoreFileKit';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName'; // Specify the name of the bucket.

const key='yourObjectName '; // Specify the name of the object.

const putObject = async () => {
  try {
    // Use the putObject method to upload data to object in the specified bucket and pass parameters.
    const res = await client.putObject({
      bucket, // Specify the name of the bucket.
      key, // Specify the name of the object.
      data: 'hello world' // The data that you want to upload. In this example, a simple string is uploaded.
    });

    // Display the result of the object upload operation.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code);
      console.log('message: ', err.message);
      console.log('requestId: ', err.requestId);
      console.log('status: ', err.status);
      console.log('ec: ', err.ec);
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
}

// Call the putObject function to perform the object upload operation.
putObject();

Download an object

import Client, { RequestError } from '@aliyun/oss';
import { fileIo as fs } from '@kit.CoreFileKit';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object that you want to download.
const key = 'yourObjectName';

/**
 * Download the object. 
 * The object content is returned using res.data. The data type is ArrayBuffer. 
 */
const getObject = async () => {
  try {
    // Use the getObject method to download the object from the bucket.
    const res = await client.getObject({
      bucket, // Specify the name of the bucket.
      key, // Specify the name of the object.
    });

    // Query the content of the object. The data type is ArrayBuffer.
    const buf: ArrayBuffer = res.data!;

    // Display the result of the object download operation.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the getObject function to download the object.
getObject();

List files

import Client, { RequestError } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

/**
 * List objects in the bucket. 
 * Use the listObjectsV2 method to list objects in the bucket. 
 */
const listObjectsV2 = async () => {
  try {
    // Use the listObjectsV2 method to list objects in the bucket.
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // Specify the name of the bucket.
    });

    // Display the listed objects.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the listObjectsV2 function to list objects.
listObjectsV2();

Delete an object

import Client, { RequestError } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object that you want to delete.
const key = 'yourObjectName';

/**
 * Delete the object. 
 * Use the deleteObject method to delete the object from the bucket. 
 */
const deleteObject = async () => {
  try {
    // Use the deleteObject method to delete the object from the bucket.
    const res = await client.deleteObject({
      bucket, // Specify the name of the bucket.
      key, // Specify the name of the object.
    });

    // Display the result of the object deletion operation.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the deleteObject function to delete the object.
deleteObject();

FAQ

What do I do if the AccessDenied error code is returned when I use OSS SDK for Harmony?

You do not have the required permissions. Perform the following steps to resolve the issue:

Check the temporary access credentials obtained from STS: Make sure that the temporary access credentials are valid. For more information, see Access OSS using an STS token.
Check bucket policies: If the "Access denied by bucket policy" error message is displayed, bucket policies that deny access to resources in the bucket exist. For more information, see Bucket policies.
Check error types in Error codes: See 03-ACCESS_CONTROL to troubleshoot common RAM errors.