如何通过Harmony SDK上传文件_对象存储(OSS)-阿里云帮助中心

本文介绍如何通过简单上传方法将单个文件快速上传到OSS，此方法操作简便，适合快速将文件上传到云端存储。

注意事项

关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

权限说明

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API	Action	说明

API	Action	说明
PutObject	`oss:PutObject`	上传Object。
	`oss:PutObjectTagging`	上传Object时，如果通过x-oss-tagging指定Object的标签，则需要此操作的权限。
	`kms:GenerateDataKey`	上传Object时，如果Object的元数据包含X-Oss-Server-Side-Encryption: KMS，则需要这两个操作的权限。
	`kms:Decrypt`

示例代码

您可以使用以下代码将简单字符串文件上传到目标存储空间。

重要

上传文件（Object）时，如果存储空间（Bucket）中已存在同名文件且用户对该文件有访问权限，则新添加的文件将覆盖原有文件。

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

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

const bucket = 'yourBucketName'; // 请替换为您想要使用的Bucket名称

const key = 'yourObjectName'; // 请替换为您想要上传的对象（文件）名称

const putObject = async () => {
  try {
    // 调用putObject方法上传数据到指定的Bucket和Key，并传入数据作为参数
    const res = await client.putObject({
      bucket, // Bucket名称
      key, // 对象（文件）名称
      data: 'hello world' // 要上传的数据，这里是一个简单的字符串
    });

    // 打印上传结果
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕获请求过程中的异常信息
    if (err instanceof RequestError) {
      // 如果是已知类型的错误，则打印错误代码、错误消息、请求ID、状态码、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 {
      // 打印其他未知类型的错误
      console.log('unknown error: ', err);
    }
  }
}

// 调用putObject函数执行上传操作
putObject();

常见使用场景

上传本地文件

您可以使用以下代码将本地文件上传到目标存储空间。

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

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

// 指定要操作的Bucket名称，请替换为您实际使用的Bucket名称
const bucket = 'yourBucketName';
// 指定要上传的对象（文件）名称，请替换为您实际要上传的对象名称
const key = 'yourObjectName';

/**
 * 通过文件路径上传对象到OSS。
 * 使用putObject方法将本地文件上传到指定的Bucket和Key。
 */
const putObjectByFile = async () => {
  // 打开本地文件以供读取
  const file = await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // 请替换为实际的文件路径

  try {
    // 调用putObject方法上传文件到指定的Bucket和Key
    const res = await client.putObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
      data: file, // 要上传的文件数据
    });

    // 打印上传结果
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕获请求过程中的异常信息
    if (err instanceof RequestError) {
      // 如果是已知类型的错误，则打印错误代码、错误消息、请求ID、状态码、EC码等信息
      console.log('code: ', err.code); // 错误代码
      console.log('message: ', err.message); // 错误消息
      console.log('requestId: ', err.requestId); // 请求ID
      console.log('status: ', err.status); // HTTP状态码
      console.log('ec: ', err.ec); // 错误码
    } else {
      // 打印其他未知类型的错误
      console.log('unknown error: ', err);
    }
  } finally {
    // 确保在操作完成后关闭文件
    await fs.close(file);
  }
};

// 调用putObjectByFile函数执行文件上传操作
putObjectByFile();

上传文件并指定文件存储类型

您可以使用以下代码将文件上传至目标存储空间并指定文件的存储类型。

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

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

// 指定要操作的Bucket名称，请替换为您实际使用的Bucket名称
const bucket = 'yourBucketName';
// 指定要上传的对象（文件）名称，请替换为您实际要上传的对象名称
const key = 'yourObjectName';

/**
 * 上传对象并指定存储类型。
 * 使用putObject方法上传数据到指定的Bucket和Key，并设置存储类型为ARCHIVE。
 */
const putObjectWithStorageClass = async () => {
  try {
    // 调用putObject方法上传数据，并指定存储类型为ARCHIVE
    const res = await client.putObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
      data: 'hello world', // 要上传的数据，这里是一个简单的字符串
      storageClass: EStorageClass.ARCHIVE, // 指定存储类型为ARCHIVE
    });

    // 打印上传结果
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕获请求过程中的异常信息
    if (err instanceof RequestError) {
      // 如果是已知类型的错误，则打印错误代码、错误消息、请求ID、状态码、EC码等信息
      console.log('code: ', err.code); // 错误代码
      console.log('message: ', err.message); // 错误消息
      console.log('requestId: ', err.requestId); // 请求ID
      console.log('status: ', err.status); // HTTP状态码
      console.log('ec: ', err.ec); // 错误码
    } else {
      // 打印其他未知类型的错误
      console.log('unknown error: ', err);
    }
  }
};

// 调用putObjectWithStorageClass函数执行上传操作
putObjectWithStorageClass();

上传文件并指定文件访问权限

您可以使用以下代码将文件上传至目标存储空间并指定文件的访问权限。

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

// 创建OSS客户端实例
const client = new Client({
  // 请替换为STS临时访问凭证的Access Key ID
  accessKeyId: 'yourAccessKeyId',
  // 请替换为STS临时访问凭证的Access Key Secret
  accessKeySecret: 'yourAccessKeySecret',
  // 请替换为STS临时访问凭证的Security Token
  securityToken: 'yourSecurityToken',
  // 填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou
  region: 'oss-cn-hangzhou',
});

// 指定要操作的Bucket名称，请替换为您实际使用的Bucket名称
const bucket = 'yourBucketName';
// 指定要上传的对象（文件）名称，请替换为您实际要上传的对象名称
const key = 'yourObjectName';

/**
 * 上传对象并设置访问权限。
 * 使用putObject方法上传数据到指定的Bucket和Key，并设置对象的访问权限为PRIVATE。
 */
const putObjectWithObjectAcl = async () => {
  try {
    // 调用putObject方法上传数据，并设置对象的访问权限为PRIVATE
    const res = await client.putObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
      data: 'hello world', // 要上传的数据，这里是一个简单的字符串
      objectAcl: EObjectAcl.PRIVATE, // 设置对象的访问权限为PRIVATE
    });

    // 打印上传结果
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕获请求过程中的异常信息
    if (err instanceof RequestError) {
      // 如果是已知类型的错误，则打印错误代码、错误消息、请求ID、状态码、EC码等信息
      console.log('code: ', err.code); // 错误代码
      console.log('message: ', err.message); // 错误消息
      console.log('requestId: ', err.requestId); // 请求ID
      console.log('status: ', err.status); // HTTP状态码
      console.log('ec: ', err.ec); // 错误码
    } else {
      // 打印其他未知类型的错误
      console.log('unknown error: ', err);
    }
  }
};

// 调用putObjectWithObjectAcl函数执行上传操作
putObjectWithObjectAcl();