Harmony SDK を使用して追加アップロードを実行する方法 - Object Storage Service

既存の追加可能オブジェクトにコンテンツを追加できます。このトピックでは、Object Storage Service (OSS) SDK for Harmony 2.0 を使用して追加アップロードを実行する方法について説明します。

注意事項

リージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
コンテンツを追加したいオブジェクトが存在しない場合、追加アップロード操作を呼び出すと追加可能オブジェクトが作成されます。
ファイルが既に存在する場合：
- オブジェクトが追加可能オブジェクトであり、追加操作を開始する指定位置が現在のオブジェクト長と等しい場合、オブジェクトの末尾に追加されます。
- オブジェクトが追加可能オブジェクトであり、追加操作を開始する指定位置が現在のオブジェクト長と等しくない場合、PositionNotEqualToLength エラーが返されます。
- オブジェクトが追加可能オブジェクトでない場合、ObjectNotAppendable エラーが返されます。

権限

デフォルトでは、Alibaba Cloud アカウントは完全な権限を持っています。 Alibaba Cloud アカウント下の RAM ユーザーまたは RAM ロールは、デフォルトでは何の権限も持っていません。 Alibaba Cloud アカウントまたはアカウント管理者は、RAM ポリシーまたはバケットポリシーを通じて操作権限を付与する必要があります。

API

アクション

定義

AppendObject

oss:PutObject

この操作を呼び出して、既存のオブジェクトにデータを追加することでオブジェクトをアップロードできます。

oss:PutObjectTagging

既存のオブジェクトに追加してオブジェクトをアップロードする際に、x-oss-tagging を通じてオブジェクトタグを指定する場合、この権限が必要です。

サンプルコード

次のサンプルコードは、追加アップロードを実行する方法の例です。

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

// OSSClient インスタンスを作成します。
const client = new Client({
  // Security Token Service (STS) から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey Secret を指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが所在するリージョンを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
});

// バケット名を指定します。
const bucket = 'yourBucketName';
// コンテンツを追加するオブジェクトの名前を指定します。
const key = 'yourObjectName';

/**
 * OSS オブジェクトにコンテンツを追加します。
 * appendObject メソッドを使用して、特定のバケット内の特定のオブジェクトにデータを追加します。
 */
const appendObject = async () => {
  try {
    // appendObject メソッドを使用して、特定のバケット内の特定のオブジェクトにデータを追加します。
    // 初めて追加可能オブジェクトを作成するときは position パラメーターを指定せず、その後、追加アップロード操作を実行するときに position パラメーターを指定します。
    const res = await client.appendObject({
      bucket, // バケット名を指定します。
      key,    // オブジェクト名を指定します。
      data: 'hello world' // 追加するデータを指定します。 この例では、単純な文字列が追加されます。
    });

    // 追加アップロードの結果を表示します。
    console.log(JSON.stringify(res));
  } catch (err) {
    // リクエスト中の例外をキャッチします。
    if (err instanceof RequestError) {
      // 既知のタイプのエラーが存在する場合、エラーコード、エラーメッセージ、リクエスト ID、HTTP ステータスコード、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); // EC。
    } else {
      // その他の不明なタイプのエラーを表示します。
      console.log('unknown error: ', err);
    }
  }
};

// appendObject 関数を呼び出して、追加アップロード操作を実行します。
appendObject();

利用シーン

ローカルファイルをオブジェクトに追加する

次のサンプルコードは、ローカルファイルをオブジェクトに追加する方法の例です。

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

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey Secret を指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが所在するリージョンを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
});

// バケット名を指定します。
const bucket = 'yourBucketName';
// コンテンツを追加するオブジェクトの名前を指定します。
const key = 'yourObjectName';

/**
 * ローカルファイルのパスを使用してオブジェクトにコンテンツを追加します。
 * appendObject メソッドを使用して、ローカルファイルの内容を特定のバケット内のオブジェクトに追加します。
 */
const appendObjectByFile = async () => {
  // ローカルファイルを開いて読み取ります。
  const file=await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // ローカルファイルのパスを指定します。

  try {
    // appendObject メソッドを使用して、ローカルファイルの内容を特定のバケット内のオブジェクトに追加します。
    // 初めて追加可能オブジェクトを作成するときは position パラメーターを指定せず、その後、追加アップロード操作を実行するときに position パラメーターを指定します。
    const res = await client.appendObject({
      bucket, // バケット名を指定します。
      key,    // オブジェクト名を指定します。
      data: file, // 追加するローカルファイルを指定します。
    });

    // 追加アップロードの結果を表示します。
    console.log(JSON.stringify(res));
  } catch (err) {
    // リクエスト中の例外をキャッチします。
    if (err instanceof RequestError) {
      // 既知のタイプのエラーが存在する場合、エラーコード、エラーメッセージ、リクエスト ID、HTTP ステータスコード、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); // EC。
    } else {
      // その他の不明なタイプのエラーを表示します。
      console.log('unknown error: ', err);
    }
  } finally {
    // 操作が完了したら、ローカルファイルを閉じます。
    await fs.close(file);
  }
};

// appendObjectByFile 関数を呼び出して、追加アップロード操作を実行します。
appendObjectByFile();

追加操作を開始する位置を指定する

次のサンプルコードは、追加操作を開始する位置を指定する方法の例です。

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

// OSSClient インスタンスを作成します。
const client = new Client({
  // STS から取得した AccessKey ID を指定します。
  accessKeyId: 'yourAccessKeyId',
  // STS から取得した AccessKey Secret を指定します。
  accessKeySecret: 'yourAccessKeySecret',
  // STS から取得したセキュリティトークンを指定します。
  securityToken: 'yourSecurityToken',
  // バケットが所在するリージョンを指定します。 たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: 'oss-cn-hangzhou',
});

// バケット名を指定します。
const bucket = 'yourBucketName';
// コンテンツを追加するオブジェクトの名前を指定します。
const key = 'yourObjectName';

/**
 * OSS オブジェクトにコンテンツを追加し、追加操作を開始する位置を指定します。
 * appendObject メソッドを使用して、特定のバケット内の特定のオブジェクトにデータブロックを追加し、追加操作を開始する位置を指定します。
 */
const appendObjectWithPosition = async () => {
  try {
    // appendObject メソッドを呼び出して、最初の追加アップロードを開始し、初期データブロックを追加します。
    const res = await client.appendObject({
      bucket, // バケット名を指定します。
      key,    // オブジェクト名を指定します。
      data: 'first chunk data', // 最初のデータブロック。
    });

    // 最初の追加アップロードの結果を表示します。
    console.log(JSON.stringify(res));

    /* 次の追加操作を開始する位置を取得します。
    const nextAppendPosition = Number(res.origRes.headers[EHeaderKey.X_OSS_NEXT_APPEND_POSITION]);

    // appendObject メソッドを呼び出して、2 回目の追加アップロードを開始し、2 番目のデータブロックを追加します。
    const res1 = await client.appendObject({
      bucket, // バケット名を指定します。
      key,    // オブジェクト名を指定します。
      data: 'second chunk data', // 2 番目のデータブロック。
      position: nextAppendPosition, // 2 回目の追加を開始する追加位置。
    });

    // 2 回目の追加アップロードの結果を表示します。
    console.log(JSON.stringify(res1));
  } catch (err) {
    // リクエスト中の例外をキャッチします。
    if (err instanceof RequestError) {
      // 既知のタイプのエラーが存在する場合、エラーコード、エラーメッセージ、リクエスト ID、HTTP ステータスコード、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); // EC。
    } else {
      // その他の不明なタイプのエラーを表示します。
      console.log('unknown error: ', err);
    }
  }
};

// appendObjectWithPosition 関数を呼び出して、データブロックを追加する追加アップロード操作を実行します。
appendObjectWithPosition();