Object Storage Service (OSS) は、大きなファイル (オブジェクト) を複数のパートに分割するマルチパートアップロード機能を提供します。これらのパートは個別にアップロードできます。すべてのパートがアップロードされた後、CompleteMultipartUpload 操作を呼び出して、それらを単一のオブジェクトに結合できます。このプロセスにより、アップロードの再開が可能になります。
注意事項
マルチパートアップロードを実行する前に、この機能を理解していることを確認してください。詳細については、「マルチパートアップロード」をご参照ください。
webpack や browserify などのパッケージングツールを使用する場合は、npm install ali-oss コマンドを実行して Browser.js SDK をインストールします。
ブラウザから OSS にアクセスするには、クロスオリジンリクエストが伴います。クロスオリジンルールを設定しない場合、ブラウザはこれらのリクエストを拒否します。ブラウザから OSS にアクセスするには、OSS でクロスオリジンルールを設定する必要があります。詳細については、「事前準備」をご参照ください。
Browser.js SDK は通常、ブラウザ環境で使用されます。Alibaba Cloud アカウントの AccessKey ペア (AccessKey ID と AccessKey Secret) の漏洩を避けるため、一時的なアクセス認証情報を使用して OSS 操作を実行してください。
一時的なアクセス認証情報には、一時的な AccessKey ペア (AccessKey ID と AccessKey Secret) とセキュリティトークンが含まれます。一時的なアクセス認証情報を取得する方法の詳細については、「アクセスの許可 (Browser.js SDK)」をご参照ください。
マルチパートアップロードの完全なサンプルコード
大きなファイルをアップロードするには、MultipartUpload 操作を使用できます。この操作は、ファイルを複数のデータブロック (パート) に分割し、個別にアップロードできます。一部のパートのアップロードに失敗した場合、OSS は進捗を保存します。ファイル全体ではなく、失敗したパートのみを再アップロードする必要があります。
100 MB を超えるファイルには、マルチパートアップロードを使用してください。再開可能なアップロードとリトライにより、成功率が向上します。100 MB 未満のファイルに不適切な `partSize` でマルチパートアップロードを使用すると、アップロードの進捗が完全に表示されない場合があります。100 MB 未満のファイルには、シンプルアップロードを使用してください。
次のコードは、マルチパートアップロードを使用して exampleobject.txt という名前のファイルを examplebucket バケットにアップロードする方法を示しています。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<input id="file" type="file" />
<!--SDK ファイルをインポートします。-->
<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({
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
region: "yourRegion",
authorizationV4: true,
// STS から取得した一時的な AccessKey ID と AccessKey Secret。
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// STS から取得したセキュリティトークン。
stsToken: "yourSecurityToken",
// バケット名を指定します (例: examplebucket)。
bucket: "examplebucket",
});
const headers = {
// オブジェクトがダウンロードされる際の Web ページのキャッシュ動作を指定します。
"Cache-Control": "no-cache",
// オブジェクトがダウンロードされる際のオブジェクト名を指定します。
"Content-Disposition": "example.txt",
// 有効期限をミリ秒単位で指定します。
Expires: "1000",
// オブジェクトのストレージクラスを指定します。
"x-oss-storage-class": "Standard",
// オブジェクトのタグを指定します。複数のタグを指定できます。
"x-oss-tagging": "Tag1=1&Tag2=2",
// マルチパートアップロードを初期化する際に、同名のオブジェクトを上書きするかどうかを指定します。true の値は上書きが禁止されていることを示します。
"x-oss-forbid-overwrite": "true",
};
// examplebucket にアップロードするオブジェクトの名前を指定します (例: exampleobject.txt)。
const name = "exampleobject.txt";
// DOM を取得します。
const submit = document.getElementById("submit");
const options = {
// マルチパートアップロードの進捗、チェックポイント、および戻り値を取得します。
progress: (p, cpt, res) => {
console.log(p);
},
// 同時にアップロードするパートの数を設定します。
parallel: 4,
// パートサイズを設定します。デフォルト値は 1 MB です。最小値は 100 KB です。最大値は 5 GB です。最後のパートのサイズは 100 KB 未満でもかまいません。
partSize: 1024 * 1024,
// headers,
// カスタムメタデータ。HeadObject 操作を呼び出すことで、オブジェクトのメタデータを取得できます。
meta: { year: 2020, people: "test" },
mime: "text/plain",
};
// ボタンにリスナーを追加します。
submit.addEventListener("click", async () => {
try {
const data = document.getElementById("file").files[0];
// マルチパートアップロードを実行します。
const res = await client.multipartUpload(name, data, {
...options,
// アップロードコールバックを設定します。
// コールバックサーバーが関与しない場合は、コールバック設定を削除します。
callback: {
// コールバックリクエストのサーバーアドレスを設定します。
url: "http://examplebucket.aliyuncs.com:23450",
// コールバックリクエストのヘッダーの Host 値を設定します。これは、ご利用のサーバーで設定された Host 値です。
host: "yourHost",
/* eslint no-template-curly-in-string: [0] */
// コールバックが開始されたときのリクエストボディの値を設定します。
body: "bucket=${bucket}&object=${object}&var1=${x:var1}",
// コールバックリクエストの Content-Type を設定します。
contentType: "application/x-www-form-urlencoded",
customValue: {
// コールバックリクエストのカスタムパラメーターを設定します。
var1: "value1",
var2: "value2",
},
},
});
console.log(res);
} catch (err) {
console.log(err);
}
});
</script>
</body>
</html>
MultipartUpload 操作を呼び出すときに ConnectionTimeoutError が発生した場合は、タイムアウトを処理する必要があります。たとえば、パートサイズを小さくする、タイムアウト期間を長くする、リクエストをリトライする、または ConnectionTimeoutError をキャッチすることができます。詳細については、「ネットワークエラーの処理」をご参照ください。
マルチパートアップロードイベントのキャンセル
client.abortMultipartUpload メソッドを呼び出して、マルチパートアップロードイベントをキャンセルできます。イベントがキャンセルされると、その uploadId をどの操作にも使用できなくなり、アップロードされたパートデータは削除されます。
次のコードは、マルチパートアップロードイベントをキャンセルする方法を示しています。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="abort">Abort</button>
<!--SDK ファイルをインポートします。-->
<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({
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
region: "yourRegion",
authorizationV4: true,
// STS から取得した一時的な AccessKey ID と AccessKey Secret。
accessKeyId: "yourAccessKeyId",
accessKeySecret: "yourAccessKeySecret",
// STS から取得したセキュリティトークン。
stsToken: "yourSecurityToken",
// バケット名を指定します (例: examplebucket)。
bucket: "examplebucket",
});
// マルチパートアップロード用に 100 MB のファイルを生成します。
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// examplebucket にアップロードするオブジェクトの名前を設定します (例: exampleobject.txt)。
const name = "exampleobject.txt";
// チェックポイントを設定します。
let abortCheckpoint;
// DOM を取得します。
const submit = document.getElementById("submit");
const abort = document.getElementById("abort");
// アップロードボタンにリスナーを追加します。[Upload] をクリックすると、マルチパートアップロードが開始されます。
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
// チェックポイントに値を割り当てます。
abortCheckpoint = cpt;
// アップロードの進捗を取得します。
console.log(p);
},
});
} catch (err) {
console.log(err);
}
});
// 中止ボタンにリスナーを追加します。
abort.addEventListener("click", () => {
// マルチパートアップロードを中止します。
client.abortMultipartUpload(
abortCheckpoint.name,
abortCheckpoint.uploadId
);
});
</script>
</body>
</html>
アップロード済みパートのリスト
client.listParts メソッドを呼び出して、指定された uploadId に対して正常にアップロードされたすべてのパートをリスト表示できます。
次のコードは、アップロードされたパートをリスト表示する方法を示しています。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="submit">Upload</button>
<button id="check">List uploaded parts</button>
<!--SDK ファイルをインポートします。-->
<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({
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
region: 'yourRegion',
authorizationV4: true,
// STS から取得した一時的な AccessKey ID と AccessKey Secret。
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// STS から取得したセキュリティトークン。
stsToken: 'yourSecurityToken',
// バケット名を指定します (例: examplebucket)。
bucket: "examplebucket",
});
// マルチパートアップロード用に 100 MB のファイルを生成します。
const fileContent = Array(1024 * 1024 * 100)
.fill("a")
.join("");
const file = new File([fileContent], "multipart-upload-file");
// examplebucket にアップロードするオブジェクトの名前を設定します (例: exampleobject.txt)。
const name = "exampleobject.txt";
// チェックポイントを設定します。
let abortCheckpoint;
// DOM を取得します。
const submit = document.getElementById("submit");
const check = document.getElementById("check");
// ボタンにリスナーを追加します。
submit.addEventListener("click", async () => {
try {
const res = await client.multipartUpload(name, file, {
progress: (p, cpt, res) => {
// チェックポイントに値を割り当てます。
abortCheckpoint = cpt;
// アップロードの進捗を取得します。
console.log("progress=====", p);
},
});
} catch (err) {
console.log(err);
}
});
// ボタンにリスナーを追加します。
check.addEventListener("click", async () => {
// アップロードされたパートをリスト表示します。
const result = await client.listParts(name, abortCheckpoint.uploadId);
console.log(result);
});
</script>
</body>
</html>
マルチパートアップロードイベントのリスト
client.listUploads メソッドを呼び出して、進行中のすべてのマルチパートアップロードイベントをリスト表示できます。進行中のイベントとは、開始されたがまだ完了またはキャンセルされていないイベントです。
次のコードは、マルチパートアップロードイベントをリスト表示する方法を示しています。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<title>Document</title>
</head>
<body>
<button id="check">List multipart upload events</button>
<!--SDK ファイルをインポートします。-->
<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({
// バケットが配置されているリージョンを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを oss-cn-hangzhou に設定します。
region: 'yourRegion',
authorizationV4: true,
// STS から取得した一時的な AccessKey ID と AccessKey Secret。
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// STS から取得したセキュリティトークン。
stsToken: 'yourSecurityToken',
// バケット名を指定します (例: examplebucket)。
bucket: "examplebucket",
});
// DOM を取得します。
const check = document.getElementById("check");
// ボタンにリスナーを追加します。
check.addEventListener("click", async () => {
// 開始されたが完了またはキャンセルされていないすべてのマルチパートアップロードイベントを取得します。
const result = await client.listUploads({ "max-uploads": 100 });
console.log("uploads", result.uploads);
});
</script>
</body>
</html>関連ドキュメント
マルチパートアップロードの完全なサンプルコードについては、「GitHub の例」をご参照ください。
Browser.js SDK でマルチパートアップロードのために呼び出される
multipartUploadメソッドは、次の 3 つの API 操作をカプセル化しています。マルチパートアップロードイベントを初期化する API 操作の詳細については、「InitiateMultipartUpload」をご参照ください。
パートをアップロードする API 操作の詳細については、「UploadPart」をご参照ください。
マルチパートアップロードを完了する API 操作の詳細については、「CompleteMultipartUpload」をご参照ください。
マルチパートアップロードイベントをキャンセルする API 操作の詳細については、「AbortMultipartUpload」をご参照ください。
アップロードされたパートをリスト表示する API 操作の詳細については、「ListParts」をご参照ください。
進行中のすべてのマルチパートアップロードイベントをリスト表示する API 操作の詳細については、「ListMultipartUploads」をご参照ください。
よくある質問
「PLease set the etag of expose-headers in Oss.」エラーを解決するにはどうすればよいですか？
原因
クロスオリジンリソース共有 (CORS) が正しく設定されていません。
解決策
現在のバケットに対して CORS を設定します。CORS ルールを設定する際には、x-oss-request-id や ETag などの共通ヘッダーを公開する必要があります。詳細については、「CORS の設定」をご参照ください。
「The operation is not supported for this resource.」エラーを解決するにはどうすればよいですか？
原因
CompleteMultipartUpload 操作を呼び出すときにオブジェクトストレージクラスを設定しました。
解決策
CompleteMultipartUpload を呼び出すときにオブジェクトストレージクラスを設定することはできません。マルチパートアップロードのオブジェクトストレージクラスを指定するには、InitiateMultipartUpload を呼び出すときに設定する必要があります。