How to use OSS SDK for Harmony 2.0 to upload objects - Object Storage Service

This topic describes how to quickly upload a local file to Object Storage Service (OSS) using simple upload. This method is straightforward and suitable for scenarios where you need to quickly upload a local file.

Considerations

For more information about the mapping between regions and endpoints supported by OSS, see OSS regions and endpoints.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket Policy.

API	Action	Definition
PutObject	`oss:PutObject`	Uploads an object.
	`oss:PutObjectTagging`	When uploading an object, if you specify object tags through x-oss-tagging, this permission is required.
	`kms:GenerateDataKey`	When uploading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, these two permissions are required.
	`kms:Decrypt`

Sample code

The following sample code demonstrates how to upload a simple string to a bucket:

Important

If you upload an object with the same name as an accessible existing object, the existing object will be overwritten by the uploaded object.

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

// Create an OSS client 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' // Specify the data that you want to upload. In this example, a simple string is uploaded
    });

    // Display the result of the simple upload request
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture the exceptions during the request
    if (err instanceof RequestError) {
      // For a known error, display the error codes, error message, requests ID, and HTTP status code
      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();

Scenarios

Upload a local file

The following sample code demonstrates how to upload a local file to a bucket:

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
const key = 'yourObjectName';

/**
 * Upload a local file to OSS by using the file path.
 * Use the putObject method to upload a local file to the bucket.
 */
const putObjectByFile = async () => {
  // Open and read the local file
  const file = await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // Specify the path of the local file

  try {
    // Use the putObject method to upload the local file to the bucket
    const res = await client.putObject({
      bucket, // Specify the name of the bucket
      key,    // Specify the name of the object
      data: file, // Specify the local file that you want to upload
    });

    // Display the result of the object upload operation
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture request exceptions
    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);
    }
  } finally {
    // Close the local file after the operation is complete
    await fs.close(file);
  }
};

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

Upload a file and specify the storage class

The following sample code demonstrates how to upload a local file to a specific bucket and specify the storage class of the uploaded object:

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

// Create an OSS client 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
const key = 'yourObjectName';

/**
 * Upload a local file and specify the storage class of the uploaded object.
 * Use the putObject method to upload the local file to the bucket and set the storage class of the uploaded object to ARCHIVE.
 */
const putObjectWithStorageClass = async () => {
  try {
    // Use the putObject method to upload the local file to the bucket and set the storage class of the uploaded object to ARCHIVE
    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
      storageClass: EStorageClass.ARCHIVE, // Set the storage class to ARCHIVE
    });

    // 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); // 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 putObjectWithStorageClass function to perform the object upload operation
putObjectWithStorageClass();

Upload a file and specify the ACL

The following sample code demonstrates how to upload a local file to a bucket and specify the ACL of the uploaded object:

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

// Create an OSS client 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
const key = 'yourObjectName';

/**
 * Upload a local file and specify the ACL of the uploaded object.
 * Use the putObject method to upload the local file to the bucket and set the ACL of the uploaded object to PRIVATE.
 */
const putObjectWithObjectAcl = async () => {
  try {
    // Use the putObject method to upload the local file to the bucket and set the ACL of the uploaded object to PRIVATE
    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
      objectAcl: EObjectAcl.PRIVATE, // Set the ACL of the object to PRIVATE
    });

    // Display the upload result
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture request exceptions
    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 putObjectWithObjectAcl function to perform the object upload operation
putObjectWithObjectAcl();