Cara melakukan unggah multi-bagian di OSS - Object Storage Service

Object Storage Service (OSS) menyediakan fitur unggah multi-bagian yang membagi file besar atau Object menjadi beberapa bagian. Anda dapat mengunggah bagian-bagian tersebut secara independen, lalu memanggil operasi CompleteMultipartUpload untuk menggabungkannya menjadi satu Object. Proses ini memungkinkan unggahan yang dapat dilanjutkan.

Perhatian

Sebelum melakukan unggah multi-bagian, pastikan Anda memahami fitur tersebut. Untuk informasi selengkapnya, lihat Unggah multi-bagian.
Jika Anda menggunakan alat packaging seperti webpack atau browserify, instal Browser.js software development kit (SDK) dengan menjalankan perintah npm install ali-oss.
Mengakses OSS dari browser melibatkan permintaan lintas asal (cross-origin requests). Jika aturan lintas asal tidak dikonfigurasi, browser akan menolak permintaan tersebut. Untuk mengakses OSS dari browser, Anda harus mengonfigurasi aturan lintas asal di OSS. Untuk informasi selengkapnya, lihat Persiapan.
Browser.js SDK biasanya digunakan di lingkungan browser. Untuk menghindari paparan pasangan AccessKey (ID AccessKey dan Rahasia AccessKey) Akun Alibaba Cloud Anda, gunakan kredensial akses sementara untuk melakukan operasi OSS.
Kredensial akses sementara mencakup pasangan AccessKey sementara (ID AccessKey dan Rahasia AccessKey) serta token keamanan. Untuk informasi selengkapnya tentang cara mendapatkan kredensial akses sementara, lihat Berikan akses (Browser.js SDK).

Kode contoh lengkap untuk unggah multi-bagian

Untuk mengunggah file besar, Anda dapat menggunakan operasi MultipartUpload. Operasi ini membagi file menjadi beberapa blok data, atau bagian, yang dapat diunggah secara terpisah. Jika beberapa bagian gagal diunggah, OSS menyimpan progresnya sehingga Anda hanya perlu mengunggah ulang bagian yang gagal, bukan seluruh file.

Penting

Untuk file berukuran lebih dari 100 MB, gunakan unggah multi-bagian. Unggahan yang dapat dilanjutkan dan mekanisme pengulangan membantu meningkatkan tingkat keberhasilan. Jika Anda menggunakan unggah multi-bagian untuk file berukuran kurang dari 100 MB dengan `partSize` yang tidak sesuai, progres unggahan mungkin tidak ditampilkan secara lengkap. Untuk file berukuran kurang dari 100 MB, gunakan unggah simple.

Kode berikut menunjukkan cara menggunakan unggah multi-bagian untuk mengunggah file bernama exampleobject.txt ke bucket 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" />
    <!--Impor 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({
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region ke oss-cn-hangzhou.
        region: "yourRegion",
        authorizationV4: true,
        // ID AccessKey sementara dan Rahasia AccessKey yang diperoleh dari STS.
        accessKeyId: "yourAccessKeyId",
        accessKeySecret: "yourAccessKeySecret",
        // Token keamanan yang diperoleh dari STS.
        stsToken: "yourSecurityToken",
        // Tentukan nama bucket, misalnya examplebucket.
        bucket: "examplebucket",
      });

      const headers = {
        // Tentukan perilaku cache halaman web saat objek diunduh.
        "Cache-Control": "no-cache",
        // Tentukan nama objek saat diunduh.
        "Content-Disposition": "example.txt",
        // Tentukan waktu kedaluwarsa dalam milidetik.
        Expires: "1000",
        // Tentukan kelas penyimpanan objek.
        "x-oss-storage-class": "Standard",
        // Tentukan tag untuk objek. Anda dapat menentukan beberapa tag.
        "x-oss-tagging": "Tag1=1&Tag2=2",
        // Tentukan apakah objek dengan nama yang sama dilarang ditimpa saat Anda menginisialisasi unggah multi-bagian. Nilai true berarti penimpaan dilarang.
        "x-oss-forbid-overwrite": "true",
      };

      // Tentukan nama objek yang akan diunggah ke examplebucket, misalnya exampleobject.txt.
      const name = "exampleobject.txt";
      // Ambil DOM.
      const submit = document.getElementById("submit");
      const options = {
        // Dapatkan progres unggah multi-bagian, checkpoint, dan nilai kembali.
        progress: (p, cpt, res) => {
          console.log(p);
        },
        // Atur jumlah bagian yang diunggah secara konkuren.
        parallel: 4,
        // Atur ukuran bagian. Nilai default adalah 1 MB. Nilai minimum adalah 100 KB. Nilai maksimum adalah 5 GB. Ukuran bagian terakhir dapat lebih kecil dari 100 KB.
        partSize: 1024 * 1024,
        // headers,
        // Metadata kustom. Anda dapat memperoleh metadata objek dengan memanggil operasi HeadObject.
        meta: { year: 2020, people: "test" },
        mime: "text/plain",
      };

      // Tambahkan pendengar ke tombol.
      submit.addEventListener("click", async () => {
        try {
          const data = document.getElementById("file").files[0];
          // Lakukan unggah multi-bagian.
          const res = await client.multipartUpload(name, data, {
            ...options,
            // Atur callback unggahan.
            // Jika tidak melibatkan server callback, hapus pengaturan callback.
            callback: {
              // Atur alamat server untuk permintaan callback.
              url: "http://examplebucket.aliyuncs.com:23450",
              // Atur nilai Host di header permintaan callback. Ini adalah nilai Host yang dikonfigurasi di server Anda.
              host: "yourHost",
              /* eslint no-template-curly-in-string: [0] */
              // Atur nilai badan permintaan saat callback dipicu.
              body: "bucket=${bucket}&object=${object}&var1=${x:var1}",
              // Atur Content-Type permintaan callback.
              contentType: "application/x-www-form-urlencoded",
              customValue: {
                // Atur parameter kustom untuk permintaan callback.
                var1: "value1",
                var2: "value2",
              },
            },
          });
          console.log(res);
        } catch (err) {
          console.log(err);
        }
      });
    </script>
  </body>
</html>

Jika terjadi ConnectionTimeoutError saat memanggil operasi MultipartUpload, Anda harus menangani timeout tersebut. Misalnya, Anda dapat memperkecil ukuran bagian, memperpanjang periode timeout, mengulangi permintaan, atau menangkap ConnectionTimeoutError. Untuk informasi selengkapnya, lihat Tangani error jaringan.

Batalkan event unggah multi-bagian

Anda dapat memanggil metode client.abortMultipartUpload untuk membatalkan event unggah multi-bagian. Setelah event dibatalkan, uploadId tidak dapat digunakan untuk operasi apa pun, dan data bagian yang telah diunggah akan dihapus.

Kode berikut menunjukkan cara membatalkan event unggah multi-bagian:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <button id="submit">Upload</button>
    <button id="abort">Abort</button>
    <!--Impor 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({
        // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region ke oss-cn-hangzhou.
        region: "yourRegion",
        authorizationV4: true,
        // ID AccessKey sementara dan Rahasia AccessKey yang diperoleh dari STS.
        accessKeyId: "yourAccessKeyId",
        accessKeySecret: "yourAccessKeySecret",
        // Token keamanan yang diperoleh dari STS.
        stsToken: "yourSecurityToken",
        // Tentukan nama bucket, misalnya examplebucket.
        bucket: "examplebucket",
      });
      // Hasilkan file 100 MB untuk unggah multi-bagian.
      const fileContent = Array(1024 * 1024 * 100)
        .fill("a")
        .join("");
      const file = new File([fileContent], "multipart-upload-file");
      // Atur nama objek yang akan diunggah ke examplebucket, misalnya exampleobject.txt.
      const name = "exampleobject.txt";
      // Atur checkpoint.
      let abortCheckpoint;
      // Ambil DOM.
      const submit = document.getElementById("submit");
      const abort = document.getElementById("abort");

      // Tambahkan pendengar ke tombol unggah. Setelah Anda mengklik Upload, unggah multi-bagian dimulai.
      submit.addEventListener("click", async () => {
        try {
          const res = await client.multipartUpload(name, file, {
            progress: (p, cpt, res) => {
              // Tetapkan nilai untuk checkpoint.
              abortCheckpoint = cpt;
              // Dapatkan progres unggahan.
              console.log(p);
            },
          });
        } catch (err) {
          console.log(err);
        }
      });
      // Tambahkan pendengar ke tombol abort.
      abort.addEventListener("click", () => {
        // Batalkan unggah multi-bagian.
        client.abortMultipartUpload(
          abortCheckpoint.name,
          abortCheckpoint.uploadId
        );
      });
    </script>
  </body>
</html>

Daftar bagian yang diunggah

Anda dapat memanggil metode client.listParts untuk mencantumkan semua bagian yang berhasil diunggah untuk uploadId tertentu.

Kode berikut menunjukkan cara mencantumkan bagian yang telah diunggah:

<!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>
    <!--Impor 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({
         // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region ke oss-cn-hangzhou.
         region: 'yourRegion',
         authorizationV4: true,
         // ID AccessKey sementara dan Rahasia AccessKey yang diperoleh dari STS.
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // Token keamanan yang diperoleh dari STS.
        stsToken: 'yourSecurityToken',
        // Tentukan nama bucket, misalnya examplebucket.
        bucket: "examplebucket",
      });
      // Hasilkan file 100 MB untuk unggah multi-bagian.
      const fileContent = Array(1024 * 1024 * 100)
        .fill("a")
        .join("");
      const file = new File([fileContent], "multipart-upload-file");
      // Atur nama objek yang akan diunggah ke examplebucket, misalnya exampleobject.txt.
      const name = "exampleobject.txt";
      // Atur checkpoint.
      let abortCheckpoint;

      // Ambil DOM.
      const submit = document.getElementById("submit");
      const check = document.getElementById("check");

      // Tambahkan pendengar ke tombol.
      submit.addEventListener("click", async () => {
        try {
          const res = await client.multipartUpload(name, file, {
            progress: (p, cpt, res) => {
              // Tetapkan nilai untuk checkpoint.
              abortCheckpoint = cpt;
              // Dapatkan progres unggahan.
              console.log("progress=====", p);
            },
          });
        } catch (err) {
          console.log(err);
        }
      });
      // Tambahkan pendengar ke tombol.
      check.addEventListener("click", async () => {
        // Cantumkan bagian yang telah diunggah.
        const result = await client.listParts(name, abortCheckpoint.uploadId);
        console.log(result);
      });
    </script>
  </body>
</html>

Daftar event unggah multi-bagian

Anda dapat memanggil metode client.listUploads untuk mencantumkan semua event unggah multi-bagian yang sedang berlangsung. Event yang sedang berlangsung adalah event yang telah diinisiasi tetapi belum selesai atau dibatalkan.

Kode berikut menunjukkan cara mencantumkan event unggah multi-bagian:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <button id="check">List multipart upload events</button>
    <!--Impor 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({
         // Tentukan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur Region ke oss-cn-hangzhou.
         region: 'yourRegion',
         authorizationV4: true,
         // ID AccessKey sementara dan Rahasia AccessKey yang diperoleh dari STS.
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // Token keamanan yang diperoleh dari STS.
        stsToken: 'yourSecurityToken',
        // Tentukan nama bucket, misalnya examplebucket.
        bucket: "examplebucket",
      });
      // Ambil DOM.
      const check = document.getElementById("check");

      // Tambahkan pendengar ke tombol.
      check.addEventListener("click", async () => {
        // Dapatkan semua event unggah multi-bagian yang telah diinisiasi tetapi belum selesai atau dibatalkan.
        const result = await client.listUploads({ "max-uploads": 100 });
        console.log("uploads", result.uploads);
      });
    </script>
  </body>
</html>

Referensi

Untuk kode contoh lengkap unggah multi-bagian, lihat Contoh GitHub.
Metode multipartUpload yang dipanggil untuk unggah multi-bagian di Browser.js SDK mengenkapsulasi tiga operasi API berikut:
- Untuk informasi selengkapnya tentang operasi API untuk menginisiasi event unggah multi-bagian, lihat InitiateMultipartUpload.
- Untuk informasi selengkapnya tentang operasi API untuk mengunggah bagian, lihat UploadPart.
- Untuk informasi selengkapnya tentang operasi API untuk menyelesaikan unggah multi-bagian, lihat CompleteMultipartUpload.
Untuk informasi selengkapnya tentang operasi API untuk membatalkan event unggah multi-bagian, lihat AbortMultipartUpload.
Untuk informasi selengkapnya tentang operasi API untuk mencantumkan bagian yang telah diunggah, lihat ListParts.
Untuk informasi selengkapnya tentang operasi API untuk mencantumkan semua event unggah multi-bagian yang sedang berlangsung, lihat ListMultipartUploads.

FAQ

Bagaimana cara mengatasi error "PLease set the etag of expose-headers in Oss."?

Penyebab
Cross-origin resource sharing (CORS) tidak dikonfigurasi dengan benar.
Solusi
Konfigurasikan CORS untuk bucket saat ini. Saat mengonfigurasi aturan CORS, Anda harus mengekspos header umum seperti x-oss-request-id dan ETag. Untuk informasi selengkapnya, lihat Konfigurasi CORS.

Bagaimana cara mengatasi error "The operation is not supported for this resource."?

Penyebab
Anda menetapkan kelas penyimpanan objek saat memanggil operasi CompleteMultipartUpload.
Solusi
Anda tidak dapat menetapkan kelas penyimpanan objek saat memanggil CompleteMultipartUpload. Untuk menentukan kelas penyimpanan objek pada unggah multi-bagian, Anda harus menetapkannya saat memanggil InitiateMultipartUpload.