如何使用Harmony SDK进行追加上传_对象存储(OSS)-阿里云帮助中心

追加上传是指在已上传的追加类型文件（Appendable Object）末尾直接追加内容。本文介绍如何使用OSS Harmony SDK进行追加上传。

注意事项

关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
当文件不存在时，调用追加上传方法会创建一个追加类型文件。
当文件已存在时：
- 如果文件为追加类型文件，且设置的追加位置和文件当前长度相等，则直接在该文件末尾追加内容。
- 如果文件为追加类型文件，但是设置的追加位置和文件当前长度不相等，则抛出PositionNotEqualToLength异常。
- 如果文件为非追加类型文件，例如通过简单上传的文件类型为Normal的文件，则抛出ObjectNotAppendable异常。

权限说明

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

API	Action	说明

API

Action

说明

AppendObject

oss:PutObject

以追加写的方式上传文件（Object）。

oss:PutObjectTagging

以追加写的方式上传文件（Object）时，如果通过x-oss-tagging指定Object的标签，则需要此操作的权限。

示例代码

您可以使用以下示例代码进行文件追加上传。

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

/**
 * 追加对象内容到OSS。
 * 使用appendObject方法将数据追加到指定的Bucket和Key的对象中。
 */
const appendObject = async () => {
  try {
    // 调用appendObject方法将数据追加到指定的Bucket和Key的对象中
    // 首次创建可追加上传的 Object 时可省略 position 参数，后续再次对该 Object 执行追加上传时，position 为必传参数
    const res = await client.appendObject({
      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); // 请求ID
      console.log('status: ', err.status); // HTTP状态码
      console.log('ec: ', err.ec); // 错误码
    } else {
      // 打印其他未知类型的错误
      console.log('unknown error: ', err);
    }
  }
};

// 调用appendObject函数执行追加操作
appendObject();

常见使用场景

使用本地文件进行追加上传

您可以通过以下示例代码使用本地文件进行追加上传。

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对象。
 * 使用appendObject方法将本地文件内容追加到指定的Bucket和Key的对象中。
 */
const appendObjectByFile = async () => {
  // 打开本地文件以供读取
  const file = await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // 请替换为实际的文件路径

  try {
    // 调用appendObject方法将文件内容追加到指定的Bucket和Key的对象中
    // 首次创建可追加上传的 Object 时可省略 position 参数，后续再次对该 Object 执行追加上传时，position 为必传参数
    const res = await client.appendObject({
      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);
  }
};

// 调用appendObjectByFile函数执行文件追加操作
appendObjectByFile();

追加上传并指定追加的位置

您可以通过以下示例代码进行追加上传并指定追加的位置。

import Client, { RequestError, EHeaderKey } 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';

/**
 * 追加数据到OSS对象并指定位置。
 * 使用appendObject方法将数据分块追加到指定的Bucket和Key的对象中，并通过position参数指定追加位置。
 */
const appendObjectWithPosition = async () => {
  try {
    // 第一次调用appendObject方法追加初始数据块
    const res = await client.appendObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
      data: 'first chunk data', // 第一个数据块
    });

    // 打印第一次追加结果
    console.log(JSON.stringify(res));

    // 获取下一个追加位置（next append position）
    const nextAppendPosition = Number(res.origRes.headers[EHeaderKey.X_OSS_NEXT_APPEND_POSITION]);

    // 第二次调用appendObject方法追加后续数据块，并指定追加位置
    const res1 = await client.appendObject({
      bucket, // Bucket名称
      key,    // 对象（文件）名称
      data: 'second chunk data', // 第二个数据块
      position: nextAppendPosition, // 指定追加位置
    });

    // 打印第二次追加结果
    console.log(JSON.stringify(res1));
  } 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);
    }
  }
};

// 调用appendObjectWithPosition函数执行分块追加操作
appendObjectWithPosition();