OSS Harmony SDK快速入门_对象存储(OSS)-阿里云帮助中心

本文为您提供使用OSS Harmony SDK进行常见存储操作的快速入门。您将学习如何安装SDK、配置访问凭证，以及执行基本操作，包括创建存储空间（Bucket）、上传、下载、列举和删除文件（Object）等。

注意事项

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

安装OSS Harmony SDK

警告

当前OSS Harmony SDK处于公测阶段，因此不建议直接在生产环境中使用。如果您需要在生产环境中部署，请务必进行充分的测试，以确保其稳定性和兼容性。

在安装使用OSS Harmony SDK前，请您参考华为开发者官网下载和安装面向HarmonyOS应用开发者提供的集成开发环境（IDE）- DevEco Studio以及命令行工具包Command Line Tools。
使用包管理工具ohpm执行以下命令获取OSS Harmony SDK。
```
ohpm install @aliyun/oss
```
您可以使用以下命令来验证SDK是否安装成功并查看其版本。
```
ohpm list
```
成功返回示例如下，以下示例表明您已经成功安装SDK。
```
your-project-name@1.0.0 /path/to/your/project
└── @aliyun/oss@1.0.0-beta.1
```
在您的项目中使用以下代码引入OSS Harmony SDK。
```
import Client, { RequestError } from '@aliyun/oss';
```

快速使用

以下示例程序演示了如何创建存储空间（Bucket）、上传、下载、列举和删除文件（Object）等。

警告

以下示例中默认使用STS临时访问凭证，请先确保您已获取可使用的STS临时访问凭证，具体操作步骤请参考以下文档

如果您希望通过OpenAPI的方式简单快速获取到STS临时访问凭证，请参考AssumeRole - 获取扮演角色的临时身份凭证。
如果您希望通过SDK的方式获取STS临时访问凭证，请参考使用STS临时访问凭证访问OSS。

创建存储空间

import Client, { RequestError, EBucketAcl, EStorageClass } 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 putBucket = async () => {
  try {
    // 调用putBucket方法创建存储空间，并传入bucket名称作为参数
    const res = await client.putBucket({
      bucket: 'yourBucketName' // 请替换为你想要创建的Bucket名称
    });

    // 打印创建存储空间的结果
    console.log(JSON.stringify(res));
  } catch (err) {
    // 捕获请求过程中的异常信息
    if (err instanceof RequestError) {
      // 如果是已知类型的错误，则打印详细的错误信息
      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);
    }
  }
};

// 调用putBucket函数执行创建存储空间的操作
putBucket();

上传文件

import Client, { EObjectAcl, EStorageClass, FilePath, 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',
});

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';

/**
 * 下载文件。
 * 文件内容通过res.data返回，数据类型为ArrayBuffer。
 */
const getObject = async () => {
  try {
    // 调用getObject方法从指定的Bucket和Key下载文件
    const res = await client.getObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
    });

    // 获取文件内容，数据类型为ArrayBuffer
    const buf: ArrayBuffer = res.data!;

    // 打印下载结果
    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);
    }
  }
};

// 调用getObject函数执行文件下载操作
getObject();

列举文件

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',
});

/**
 * 列举Bucket中的对象。
 * 使用listObjectsV2方法获取指定Bucket中的对象列表。
 */
const listObjectsV2 = async () => {
  try {
    // 调用listObjectsV2方法列举指定Bucket中的对象
    const res = await client.listObjectsV2({
      bucket: 'yourBucketName', // 请替换为您实际使用的Bucket名称
    });

    // 打印列举结果
    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);
    }
  }
};

// 调用listObjectsV2函数执行对象列举操作
listObjectsV2();

删除文件

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',
});

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

/**
 * 删除指定的对象（文件）。
 * 使用deleteObject方法从指定的Bucket中删除对象。
 */
const deleteObject = async () => {
  try {
    // 调用deleteObject方法删除指定Bucket中的对象
    const res = await client.deleteObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
    });

    // 打印删除结果
    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);
    }
  }
};

// 调用deleteObject函数执行对象删除操作
deleteObject();

常见问题

当使用SDK时遇到报错AccessDenied该如何进行排查？

当您遇到AccessDenied错误时通常是因为没有相应的访问权限。以下是解决此问题的步骤：

确认STS临时访问凭证：请确保您使用了正确的STS临时访问凭证。详情请参见使用STS临时访问凭证访问OSS。
检查Bucket Policy：如果错误信息中提到“Access denied by bucket policy”，则表明是受到Bucket Policy的策略拒绝了。详情请参考Bucket Policy。
更多错误类型的查询，请您参阅EC错误码，例如关于访问控制方面的常见报错，可参见03-ACCESS_CONTROL。