如何通過Harmony SDK上傳檔案 - Object Storage Service

本文介紹如何通過簡單上傳方法將單個檔案快速上傳到OSS，此方法操作簡便，適合快速將檔案上傳到雲端儲存。

注意事項

關於OSS支援的Region與Endpoint的對應關係，請參見地區和Endpoint。

許可權說明

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

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