Object Storage Service:マルチパートアップロード

背景情報

MultipartUploadメソッドを使用して、ラージオブジェクトをアップロードできます。 マルチパートアップロードでは、オブジェクトは別々にアップロードされる複数のパートに分割されます。 一部のパーツがアップロードに失敗した場合、OSSはアップロードの進行状況を記録します。 アップロードを再開するときは、アップロードに失敗したパーツのみをアップロードする必要があります。

MultipartUploadメソッドを使用するときにConnectionTimeoutErrorエラーが発生した場合は、エラーを修正する必要があります。 部品サイズの縮小、タイムアウト期間の延長、またはリクエストの再送信を行うことができます。 ConnectionTimeoutErrorエラーをキャプチャし、原因に基づいてエラーを修正することもできます。 詳細については、次をご参照ください：

次の表に、マルチパートアップロードを使用してオブジェクトをアップロードするときに設定できるパラメーターを示します。

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

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

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname',
});


const progress = (p, _checkpoint) => {
  // Record the upload progress of the object. 
  console.log(p); 
  // Record the checkpoint information about the multipart upload task. 
  console.log(_checkpoint); 
};

const headers = {  
  // Specify the storage class of the object. 
  'x-oss-storage-class': 'Standard', 
  // Specify tags for the object. You can specify multiple tags for the object. 
  'x-oss-tagging': 'Tag1=1&Tag2=2', 
  // Specify whether to overwite an existing object with the same name when the multipart upload task is initialized. In this example, this parameter is set to true, which indicates that an existing object with the same name as the object to upload is not overwritten. 
  'x-oss-forbid-overwrite': 'true'
}

// Start the multipart upload task. 
async function multipartUpload() {
  try {
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. Then, specify the full path of the local file. Example: D:\\localpath\\examplefile.txt. Do not include the bucket name in the full path. 
    // By default, if you set this parameter to the name of a local file such as examplefile.txt without specifying the local path, the local file is uploaded from the local path of the project to which the sample program belongs. 
    const result = await client.multipartUpload('exampledir/exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'), {
      progress,
      // headers,
      // Configure the meta parameter to specify metadata for the object. You can call the HeadObject operation to obtain the object metadata. 
      meta: {
        year: 2020,
        people: 'test',
      },
    });
    console.log(result);
    // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
    const head = await client.head('exampledir/exampleobject.txt');
    console.log(head);
  } catch (e) {
    // Handle timeout exceptions. 
    if (e.code === 'ConnectionTimeoutError') {
      console.log('TimeoutError');
      // do ConnectionTimeoutError operation
    }
    console.log(e);
  }
}

multipartUpload();

上記のコードサンプルのmultipartUploadメソッドには、initMultipartUpload、uploadPart、およびcompleteMultipartUpload操作が含まれています。 マルチパートアップロードを段階的に実行する場合は、上記の操作を順番に呼び出します。 詳細については、「」をご参照ください。. initMultipartUpload,. uploadPart、および. completeMultipartUpload.

マルチパートアップロードタスクのキャンセル

client.abortMultipartUploadメソッドを使用して、マルチパートアップロードタスクをキャンセルできます。 マルチパートアップロードタスクをキャンセルした場合、アップロードIDを使用してパーツをアップロードすることはできず、アップロードされたパーツは削除されます。

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

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

async function abortMultipartUpload() {
  // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
  const name = "exampledir/exampleobject.txt";
  // Specify the upload ID. You can obtain the upload ID from the response to the InitiateMultipartUpload operation. 
  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({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

async function listUploads(query = {}) {
  // You can configure the following parameters for query: prefix, marker, delimiter, upload-id-marker, and max-uploads. 
  const result = await client.listUploads(query);

  result.uploads.forEach((upload) => {
    // Specify the upload IDs of the multipart upload tasks. 
    console.log(upload.uploadId);
    // Combine all parts into a complete object and specify the full path of the object. 
    console.log(upload.name);
  });
}

const query = {
  // Specify the maximum number of multipart upload tasks to return for the current list operation. The default value and the maximum value of max-uploads are both 1000. 
  "max-uploads": 1000,
};
listUploads(query);

アップロードしたパーツの一覧表示

client.listPartsメソッドを使用して、指定したアップロードIDを持つマルチパートアップロードタスクを使用してアップロードされたすべてのパーツを一覧表示できます。

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

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: "yourregion",
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: "yourbucketname",
});

async function listParts() {
  const query = {
    // Specify the maximum number of parts to return for the current list operation. The default value and the maximum value of max-parts are both 1000. 
    "max-parts": 1000,
  };
  let result;
  do { 
    result = await client.listParts(
      // Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path. 
      "exampledir/exampleobject.txt",
      // Obtain the upload ID from the response to the InitiateMultipartUpload operation. You must obtain the upload ID before you call the CompleteMultipartUpload operation to complete the multipart upload task.
      "0004B999EF518A1FE585B0C9360D****",
      query
    );
    // Specify the starting position of the next list operation. Only parts with part numbers greater than the value of this parameter are listed. 
    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』をご参照ください。

• OSS SDK for Node.jsがマルチパートアップロードを実行するために使用するmultipartUploadメソッドには、次の3つのAPI操作が含まれます。

  • InitiateMultipartUpload

  • UploadPart

  • CompleteMultipartUpload

• マルチパートアップロードタスクをキャンセルするために呼び出すことができるAPI操作の詳細については、「AbortMultipartUpload」をご参照ください。

• アップロードされたパーツを一覧表示するために呼び出すことができるAPI操作の詳細については、「ListParts」をご参照ください。

• 進行中のマルチパートアップロードタスクを一覧表示するために呼び出すことができるAPI操作の詳細については、「ListMultipartUploads」をご参照ください。 進行中のマルチパートアップロードタスクは、開始されたが完了またはキャンセルされていないタスクです。