Object Storage Service (OSS) は、マルチパートアップロード機能を提供します。 マルチパートアップロードを使用すると、大きなオブジェクトを複数のパートに分割してアップロードできます。 パーツがアップロードされたら、CompleteMultipartUpload操作を呼び出して、パーツを完全なオブジェクトに結合できます。 これにより、再開可能な方法でオブジェクトをアップロードできます。
使用上の注意
オブジェクトをパーツでアップロードする前に、マルチパートアップロード機能を理解してください。 詳しくは、「マルチパートアップロード」をご参照ください。
WebpackやBrowserifyなどのバンドルツールを使用する場合は、npm install ali-OSSコマンドを実行して、oss SDK for Browser.jsをインストールします。
ブラウザからOSSバケットへのクロスリージョンアクセス要求を開始し、バケットにクロスオリジンリソース共有 (CORS) ルールが設定されていない場合、ブラウザは要求を拒否します。 ブラウザからバケットへのクロスオリジンリクエストを許可するには、バケットのCORSルールを設定する必要があります。 詳細は、「前提条件 (Prerequisites)」をご参照ください。
ほとんどの場合、ブラウザではOSS SDK for Browser.jsが使用されます。 AccessKeyペアが公開されないようにするには、Security Token Service (STS) から取得した一時的なアクセス資格情報を使用してOSSにアクセスすることを推奨します。
一時的なアクセス資格情報には、セキュリティトークンと、AccessKey IDとAccessKeyシークレットで構成される一時的なAccessKeyペアが含まれます。 一時的なアクセス資格情報を取得する方法の詳細については、「一時的なアクセス権限付与にSTSを使用する」をご参照ください。
完全なサンプルコード
大きなオブジェクトをアップロードするには、マルチパートアップロードを使用してオブジェクトをパーツ単位でアップロードします。 マルチパートアップロードでは、オブジェクトは複数のパートに分割され、別々にアップロードされます。 一部のパーツのアップロードに失敗した場合は、オブジェクト全体を再度アップロードするのではなく、アップロードの進行状況に基づいて失敗したパーツのみを再アップロードできます。
サイズが100 MBを超えるオブジェクトをアップロードするには、マルチパートアップロードを使用してアップロードの成功率を上げることを推奨します。 マルチパートアップロードを使用してサイズが100 MB未満のオブジェクトをアップロードし、partSizeパラメーターの値が不適切な場合、アップロードの進行状況が完全に表示されないことがあります。 サイズが100 MB未満のオブジェクトをアップロードするには、簡易アップロードを使用することを推奨します。
次のサンプルコードは、マルチパートアップロードを使用してローカルファイルexampleobject.txtをexamplebucketにアップロードする方法の例を示しています。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<input id="file" type="file" />
<!-- Import the SDK file -->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
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",
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// Specify the security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the name of the bucket. Example: examplebucket.
bucket: "examplebucket",
});
const headers = {
// Specify the caching behavior of the web page when the object is downloaded.
"Cache-Control": "no-cache",
// Specify the name of the object when the object is downloaded.
"Content-Disposition": "example.txt",
// Specify the content encoding format of the object when the object is downloaded.
"Content-Encoding": "utf-8",
// Specify the validity period of the request. Unit: milliseconds.
Expires: "1000",
// Specify the storage class of the object.
"x-oss-storage-class": "Standard",
// Specify one or more tags for the object.
"x-oss-tagging": "Tag1=1&Tag2=2",
// Specify whether to overwrite an existing object with the same name when the multipart upload task is initialized. In this example, the x-oss-forbid-overwrite parameter is set to true. This value specifies that an existing object cannot be overwritten by the object that has the same name.
"x-oss-forbid-overwrite": "true",
};
// Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt.
const name = "exampleobject.txt";
// Obtain DOM.
const submit = document.getElementById("submit");
const options = {
// Query the progress, checkpoint, and return value of the multipart upload task.
progress: (p, cpt, res) => {
console.log(p);
},
// Specify the number of parts that can be uploaded in parallel.
parallel: 4,
// Specify the part size. Default value: 1 MB. Minimum value: 100 KB.
partSize: 1024 * 1024,
// headers,
// Specify the user metadata of the object. You can call the HeadObject operation to query the object metadata.
meta: { year: 2020, people: "test" },
mime: "text/plain",
};
// Configure an event listener.
submit.addEventListener("click", async () => {
try {
const data = document.getElementById("file").files[0];
// Start the multipart upload task.
const res = await client.multipartUpload(name, data, {
...options,
// Configure an upload callback.
// If no callback server is required, delete the callback configurations.
callback: {
// Specify the address of the server that receives the callback request.
url: "http://examplebucket.aliyuncs.com:23450",
// Specify the Host header in the callback request.
host: "yourHost",
/* eslint no-template-curly-in-string: [0] */
// Specify the body content of the callback request.
body: "bucket=${bucket}&object=${object}&var1=${x:var1}",
// Specify Content-Type in the callback request.
contentType: "application/x-www-form-urlencoded",
customValue: {
// Specify custom parameters for the callback request.
var1: "value1",
var2: "value2",
},
},
});
console.log(res);
} catch (err) {
console.log(err);
}
});
</script>
</body>
</html>
API操作を呼び出してマルチパートアップロードを実行するときにConnectionTimeoutErrorエラーが発生した場合は、エラーを処理する必要があります。 エラーを修正するには、部品サイズを縮小したり、タイムアウト期間を延長したり、リクエストを再送信したりできます。 ConnectionTimeoutErrorエラーをキャプチャして、エラーの特定の原因を分析することもできます。 詳細については、「ネットワーク接続タイムアウト処理」をご参照ください。
マルチパートアップロードタスクのキャンセル
client.abortMultipartUploadメソッドを使用して、マルチパートアップロードタスクをキャンセルできます。 マルチパートアップロードタスクをキャンセルした場合、アップロードIDを使用してパーツをアップロードすることはできません。 アップロードされたパーツは削除されます。
次のコードは、マルチパートアップロードタスクをキャンセルする方法の例を示しています。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="abort">Cancel Upload</button>
<!-- Import the SDK file -->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
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",
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// Specify the security token obtained from STS.
stsToken: "yourSecurityToken",
// Specify the name of the bucket. Example: examplebucket.
bucket: "examplebucket",
});
// Create a local file that you want to upload to the bucket by using multipart upload. The size of the file is 100 MB.
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt.
const name = "exampleobject.txt";
// Specify the checkpoint at which the multipart upload task is canceled.
let abortCheckpoint;
// Query DOM.
const submit = document.getElementById("submit");
const abort = document.getElementById("abort");
// Create a button that is used to start the multipart upload task.
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
// Assign a value to the checkpoint.
abortCheckpoint = cpt;
// Query the progress of the multipart upload task.
console.log(p);
},
});
} catch (err) {
console.log(err);
}
});
// Create a button that is used to cancel the multipart upload task.
abort.addEventListener("click", () => {
// Cancel the multipart upload task.
client.abortMultipartUpload(
abortCheckpoint.name,
abortCheckpoint.uploadId
);
});
</script>
</body>
</html>
アップロードしたパーツの一覧表示
client.listPartsメソッドを使用して、指定したアップロードIDを使用してアップロードされたすべてのパーツを一覧表示できます。
次のコードは、アップロードされたパーツを一覧表示する方法の例です。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="check">List Uploaded Parts</button>
<!-- Import the SDK file -->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
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',
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Specify the security token obtained from STS.
stsToken: 'yourSecurityToken',
// Specify the name of the bucket. Example: examplebucket.
bucket: "examplebucket",
});
// Create a local file that you want to upload to the bucket by using multipart upload. The size of the file is 100 MB.
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// Specify the name of the object that is uploaded to the examplebucket bucket. Example: exampleobject.txt.
const name = "exampleobject.txt";
// Specify the checkpoint at which the multipart upload task is canceled.
let abortCheckpoint;
// Query DOM.
const submit = document.getElementById("submit");
const check = document.getElementById("check");
// Configure an event listener.
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
// Assign a value to the checkpoint.
abortCheckpoint = cpt;
// Query the progress of the multipart upload task.
console.log("progress=====", p);
},
});
} catch (err) {
console.log(err);
}
});
// Configure an event listener.
check.addEventListener("click", async () => {
// List the uploaded parts.
const result = await client.listParts(name, abortCheckpoint.uploadId);
console.log(result);
});
</script>
</body>
</html>
マルチパートアップロードタスクの一覧表示
client.listUploadsメソッドを使用すると、開始されたが完了またはキャンセルされていないタスクを含む、進行中のすべてのマルチパートアップロードタスクを一覧表示できます。
次のサンプルコードは、マルチパートアップロードタスクを一覧表示する方法の例を示しています。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="check">List Multipart Upload Tasks</button>
<!-- Import the SDK file -->
<script
type="text/javascript"
src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
></script>
<script type="text/javascript">
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',
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Specify the security token obtained from STS.
stsToken: 'yourSecurityToken',
// Specify the name of the bucket. Example: examplebucket.
bucket: "examplebucket",
});
// Obtain DOM.
const check = document.getElementById("check");
// Configure an event listener.
check.addEventListener("click", async () => {
// Query multipart upload tasks that have been initiated but are not completed or canceled.
const result = await client.listUploads({ "max-uploads": 100 });
console.log("uploads", result.uploads);
});
</script>
</body>
</html>関連ドキュメント
マルチパートアップロードの実行に使用する完全なサンプルコードについては、『GitHub』をご参照ください。
マルチパートアップロードを実行するために呼び出すことができるAPI操作の詳細については、次のトピックを参照して。
マルチパートアップロードタスクをキャンセルするために呼び出すことができるAPI操作の詳細については、「AbortMultipartUpload」をご参照ください。
アップロードされたパーツを一覧表示するために呼び出すことができるAPI操作の詳細については、「ListParts」をご参照ください。
実行中のすべてのマルチパートアップロードタスクを一覧表示するために呼び出すことができるAPI操作の詳細については、「ListMultipartUploads」をご参照ください。 進行中のマルチパートアップロードタスクには、開始されたが完了またはキャンセルされていないタスクが含まれます。
よくある質問
PLeaseがOssのexposure-headersのetagを設定した場合はどうすればよいですか。 エラーメッセージが返されますか?
原因
クロスオリジンリソース共有 (CORS) ルールが正しく設定されていません。
解決策
現在のバケットにCORSルールを設定する必要があります。 CORSルールを設定するときに、x-oss-request-idやETagなどの共通ヘッダーを指定します。 詳細については、「CORS」をご参照ください。
私は何をしますか?この操作はこのリソースではサポートされていません。 エラーメッセージが返されますか?
原因
CompleteMultipartUpload操作を呼び出すときに、オブジェクトのストレージクラスを指定しました。
解決策
CompleteMultipartUpload操作を呼び出すときに、オブジェクトのストレージクラスを指定しないでください。 マルチパートアップロード中にオブジェクトのストレージクラスを指定する場合は、InitiateMultipartUpload操作を呼び出します。