Object Storage Service:Multipart upload (Node.js SDK)

背景情報

サイズの大きいファイルをアップロードする必要がある場合は、MultipartUpload メソッドを使用してマルチパートアップロードを実行できます。このメソッドは、オブジェクトを複数のパートに分割して個別にアップロードします。一部のパートのアップロードに失敗した場合、OSS はアップロードの進行状況を記録します。再アップロードする際には、ファイル全体ではなく、失敗したパートのみをアップロードすれば済みます。

MultipartUpload メソッドを使用する場合、ConnectionTimeoutError エラーが発生した際には、それを処理する必要があります。たとえば、シャードサイズを小さくする、タイムアウト期間を長くする、リクエストをリトライする、または ConnectionTimeoutError をキャッチすることでタイムアウトを処理できます。詳細については、ネットワークエラーの処理をご参照ください。

次の表に、マルチパートアップロードに関連するパラメーターを示します。

マルチパートアップロードの完了例

次のコードは、multipartUpload メソッドを使用してマルチパートアップロードを実行する方法を示しています。

const OSS = require('ali-oss');
const path = require("path");

const client = new OSS({
  // バケットが配置されているリージョンを yourregion に置き換えます。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: 'yourregion',
  // 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: 'yourbucketname',
});


const progress = (p, _checkpoint) => {
  // オブジェクトのアップロードの進行状況。
  console.log(p); 
  // マルチパートアップロードのブレークポイント情報。
  console.log(_checkpoint); 
};

const headers = {  
  // オブジェクトのストレージクラスを指定します。
  'x-oss-storage-class': 'Standard', 
  // オブジェクトのタグを指定します。複数のタグを指定できます。
  'x-oss-tagging': 'Tag1=1&Tag2=2', 
  // マルチパートアップロードを初期化する際に、同名のオブジェクトを上書きするかどうかを指定します。この例では、同名のオブジェクトの上書きを防ぐために、このパラメーターは true に設定されています。
  'x-oss-forbid-overwrite': 'true'
}

// マルチパートアップロードを開始します。
async function multipartUpload() {
  try {
    // オブジェクトの完全なパス (例：exampledir/exampleobject.txt) とローカルファイルの完全なパス (例：D:\\localpath\\examplefile.txt) を指定します。オブジェクトの完全なパスにバケット名を含めることはできません。
    // ローカルファイルの完全なパスにローカルパスを指定しない場合 (例：examplefile.txt)、ファイルはサンプルプログラムが配置されているプロジェクトに対応するローカルパスからアップロードされます。
    const result = await client.multipartUpload('exampledir/exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'), {
      progress,
      // headers,
      // meta パラメーターを指定して、オブジェクトのメタデータをカスタマイズします。head 操作を使用してオブジェクトのメタデータを取得できます。
      meta: {
        year: 2020,
        people: 'test',
      },
    });
    console.log(result);
    // オブジェクトの完全なパス (例：exampledir/exampleobject.txt) を指定します。オブジェクトの完全なパスにバケット名を含めることはできません。
    const head = await client.head('exampledir/exampleobject.txt');
    console.log(head);
  } catch (e) {
    // タイムアウト例外をキャッチします。
    if (e.code === 'ConnectionTimeoutError') {
      console.log('TimeoutError');
      // do ConnectionTimeoutError operation
    }
    console.log(e);
  }
}

multipartUpload();

上記の例で使用されている multipartUpload メソッドは、マルチパートアップロードの初期化、パートのアップロード、マルチパートアップロードの完了という 3 つの API 操作をカプセル化しています。マルチパートアップロードを段階的に実装したい場合は、順番に .initMultipartUpload、.uploadPart、.completeMultipartUpload メソッドを呼び出すことができます。

マルチパートアップロードイベントのキャンセル

client.abortMultipartUpload メソッドを呼び出して、マルチパートアップロードタスクをキャンセルできます。マルチパートアップロードタスクがキャンセルされると、そのアップロード ID を使用してパートをアップロードすることはできなくなり、アップロード済みのパートは削除されます。

次のコードは、マルチパートアップロードをキャンセルする方法を示しています。

const OSS = require("ali-oss");

const client = new OSS({
  // バケットが配置されているリージョンを yourregion に置き換えます。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: "yourregion",
  // 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: "yourbucketname",
});

async function abortMultipartUpload() {
  // オブジェクトの完全なパス (例：exampledir/exampleobject.txt) を指定します。オブジェクトの完全なパスにバケット名を含めることはできません。
  const name = "exampledir/exampleobject.txt";
  // アップロード ID を指定します。アップロード ID は、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化した際の応答から取得します。
  const uploadId = "0004B999EF518A1FE585B0C9360D****";
  const result = await client.abortMultipartUpload(name, uploadId);
  console.log(result);
}

abortMultipartUpload();

マルチパートアップロードイベントのリスト表示

client.listUploads メソッドを呼び出して、進行中のすべてのマルチパートアップロードをリスト表示できます。進行中のマルチパートアップロードとは、初期化されたがまだ完了またはキャンセルされていないアップロードのことです。

const OSS = require("ali-oss");

const client = new OSS({
  // バケットが配置されているリージョンを yourregion に置き換えます。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: "yourregion",
  // 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: "yourbucketname",
});

async function listUploads(query = {}) {
  // クエリには、prefix、marker、delimiter、upload-id-marker、max-uploads などのパラメーターを設定できます。
  const result = await client.listUploads(query);

  result.uploads.forEach((upload) => {
    // マルチパートアップロードのアップロード ID。
    console.log(upload.uploadId);
    // アップロードされたすべてのパートを結合して完全なオブジェクトにし、オブジェクトの完全なパスを指定します。
    console.log(upload.name);
  });
}

const query = {
  // 返されるマルチパートアップロードイベントの最大数を指定します。max-uploads パラメーターのデフォルト値および最大値は 1000 です。
  "max-uploads": 1000,
};
listUploads(query);

アップロード済みパートのリスト表示

マルチパートアップロード中に、client.listParts メソッドを呼び出して、指定されたアップロード ID に対して正常にアップロードされたすべてのパートをリスト表示できます。

const OSS = require("ali-oss");

const client = new OSS({
  // バケットが配置されているリージョンを yourregion に置き換えます。たとえば、バケットが中国 (杭州) リージョンにある場合、リージョンを oss-cn-hangzhou に設定します。
  region: "yourregion",
  // 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // バケット名を指定します。
  bucket: "yourbucketname",
});

async function listParts() {
  const query = {
    // 返されるパートの最大数を指定します。max-parts パラメーターのデフォルト値および最大値は 1000 です。
    "max-parts": 1000,
  };
  let result;
  do { 
    result = await client.listParts(
      // オブジェクトの完全なパス (例：exampledir/exampleobject.txt) を指定します。オブジェクトの完全なパスにバケット名を含めることはできません。
      "exampledir/exampleobject.txt",
      // アップロード ID は、InitiateMultipartUpload を呼び出してマルチパートアップロードを初期化し、CompleteMultipartUpload を呼び出してマルチパートアップロードを完了する前の応答から取得します。
      "0004B999EF518A1FE585B0C9360D****",
      query
    );
    // 次のリスト操作の開始位置を指定します。この値より大きいパート番号を持つパートのみがリストされます。
    query["part-number-marker"] = result.nextPartNumberMarker;
    result.parts.forEach((part) => {
      console.log(part.PartNumber);
      console.log(part.LastModified);
      console.log(part.ETag);
      console.log(part.Size);
    });
  } while (result.isTruncated === "true");
}

listParts();

関連ドキュメント

• マルチパートアップロードの完全なサンプルコードについては、GitHub の例をご参照ください。

• Node.js SDK の multipartUpload メソッドは、次の 3 つの API 操作をカプセル化しています：

  • マルチパートアップロードを初期化する API 操作の詳細については、InitiateMultipartUpload をご参照ください。

  • パートをアップロードする API 操作の詳細については、UploadPart をご参照ください。

  • マルチパートアップロードを完了する API 操作の詳細については、CompleteMultipartUpload をご参照ください。

• マルチパートアップロードをキャンセルする API 操作の詳細については、AbortMultipartUpload をご参照ください。

• アップロードされたパートをリスト表示する API 操作の詳細については、ListParts をご参照ください。

• 進行中のすべてのマルチパートアップロード (初期化されたがまだ完了またはキャンセルされていないアップロード) をリスト表示する API 操作の詳細については、ListMultipartUploads をご参照ください。