如何使用Harmony SDK進行追加上傳 - Object Storage Service

追加上傳是指在已上傳的追加類型檔案（Appendable Object）末尾直接追加內容。本文介紹如何使用OSS Harmony SDK進行追加上傳。

注意事項

關於OSS支援的Region與Endpoint的對應關係，請參見地區和Endpoint。
當檔案不存在時，調用追加上傳方法會建立一個追加類型檔案。
當檔案已存在時：
- 如果檔案為追加類型檔案，且設定的追加位置和檔案當前長度相等，則直接在該檔案末尾追加內容。
- 如果檔案為追加類型檔案，但是設定的追加位置和檔案當前長度不相等，則拋出PositionNotEqualToLength異常。
- 如果檔案為非追加類型檔案，例如通過簡單上傳的檔案類型為Normal的檔案，則拋出ObjectNotAppendable異常。

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

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();