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

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

使用方法

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

権限

デフォルトでは、Alibaba Cloud アカウントはすべての権限を持っています。 RAM ユーザーまたは Alibaba Cloud アカウント下の 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 シークレットを指定します。
  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 メソッドを使用して、特定のバケットの特定のオブジェクトにデータを追加します。
    // append可能なオブジェクトを初めて作成するときは、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 シークレットを指定します。
  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 メソッドを使用して、ローカルファイルのコンテンツを特定のバケットのオブジェクトに追加します。
    // append可能なオブジェクトを初めて作成するときは、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 シークレットを指定します。
  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();