Object Storage Service：Unggah multi-bagian (Node.js SDK)

Informasi latar belakang

Saat mengunggah file besar, Anda dapat menggunakan metode MultipartUpload untuk melakukan unggah multi-bagian. Metode ini membagi objek menjadi beberapa bagian yang diunggah secara terpisah. Jika beberapa bagian gagal diunggah, OSS mencatat progres pengunggahan sehingga pada pengunggahan ulang, Anda hanya perlu mengunggah bagian yang gagal, bukan seluruh file.

Saat menggunakan metode MultipartUpload, Anda harus menangani error ConnectionTimeoutError jika terjadi. Misalnya, Anda dapat menangani timeout dengan memperkecil ukuran shard, memperpanjang periode timeout, mencoba ulang permintaan, atau menangkap error ConnectionTimeoutError. Untuk informasi selengkapnya, lihat Penanganan error jaringan.

Tabel berikut menjelaskan parameter yang terkait dengan unggah multi-bagian.

Contoh unggah multi-bagian lengkap

Kode berikut menunjukkan cara menggunakan metode multipartUpload untuk melakukan unggah multi-bagian.

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

const client = new OSS({
  // Ganti yourregion dengan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur region menjadi oss-cn-hangzhou.
  region: 'yourregion',
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Tentukan nama bucket.
  bucket: 'yourbucketname',
});


const progress = (p, _checkpoint) => {
  // Progres pengunggahan objek.
  console.log(p); 
  // Informasi breakpoint untuk unggah multi-bagian.
  console.log(_checkpoint); 
};

const headers = {  
  // 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 akan ditimpa saat Anda menginisialisasi unggah multi-bagian. Dalam contoh ini, parameter ini diatur ke true untuk mencegah penimpaan objek dengan nama yang sama.
  'x-oss-forbid-overwrite': 'true'
}

// Mulai unggah multi-bagian.
async function multipartUpload() {
  try {
    // Tentukan jalur lengkap objek (misalnya, exampledir/exampleobject.txt) dan jalur lengkap file lokal (misalnya, D:\\localpath\\examplefile.txt). Jalur lengkap objek tidak boleh mengandung nama bucket.
    // Jika Anda tidak menentukan jalur lokal dalam jalur lengkap file lokal (misalnya, examplefile.txt), file akan diunggah dari jalur lokal yang sesuai dengan proyek tempat program contoh berada.
    const result = await client.multipartUpload('exampledir/exampleobject.txt', path.normalize('D:\\localpath\\examplefile.txt'), {
      progress,
      // headers,
      // Tentukan parameter meta untuk menyesuaikan metadata objek. Anda dapat menggunakan operasi head untuk mendapatkan metadata objek.
      meta: {
        year: 2020,
        people: 'test',
      },
    });
    console.log(result);
    // Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap objek tidak boleh mengandung nama bucket.
    const head = await client.head('exampledir/exampleobject.txt');
    console.log(head);
  } catch (e) {
    // Tangkap exception timeout.
    if (e.code === 'ConnectionTimeoutError') {
      console.log('TimeoutError');
      // lakukan operasi ConnectionTimeoutError
    }
    console.log(e);
  }
}

multipartUpload();

Metode multipartUpload yang digunakan dalam contoh di atas mengenkapsulasi tiga operasi API: menginisialisasi unggah multi-bagian, mengunggah bagian, dan menyelesaikan unggah multi-bagian. Jika Anda ingin mengimplementasikan unggah multi-bagian secara bertahap, Anda dapat memanggil metode .initMultipartUpload, .uploadPart, dan .completeMultipartUpload secara berurutan.

Batalkan event unggah multi-bagian

Anda dapat memanggil metode client.abortMultipartUpload untuk membatalkan tugas unggah multi-bagian. Setelah tugas tersebut dibatalkan, Anda tidak dapat lagi menggunakan ID unggah untuk mengunggah bagian, dan bagian yang telah diunggah akan dihapus.

Kode berikut menunjukkan cara membatalkan unggah multi-bagian.

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

const client = new OSS({
  // Ganti yourregion dengan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur region menjadi oss-cn-hangzhou.
  region: "yourregion",
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Tentukan nama bucket.
  bucket: "yourbucketname",
});

async function abortMultipartUpload() {
  // Tentukan jalur lengkap objek, misalnya exampledir/exampleobject.txt. Jalur lengkap objek tidak boleh mengandung nama bucket.
  const name = "exampledir/exampleobject.txt";
  // Tentukan ID unggah. ID unggah diperoleh dari tanggapan pemanggilan InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian.
  const uploadId = "0004B999EF518A1FE585B0C9360D****";
  const result = await client.abortMultipartUpload(name, uploadId);
  console.log(result);
}

abortMultipartUpload();

Daftar event unggah multi-bagian

Anda dapat memanggil metode client.listUploads untuk mencantumkan semua unggah multi-bagian yang sedang berlangsung—yaitu unggahan yang telah diinisialisasi tetapi belum diselesaikan atau dibatalkan.

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

const client = new OSS({
  // Ganti yourregion dengan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur region menjadi oss-cn-hangzhou.
  region: "yourregion",
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Tentukan nama bucket.
  bucket: "yourbucketname",
});

async function listUploads(query = {}) {
  // Anda dapat mengatur parameter seperti prefix, marker, delimiter, upload-id-marker, dan max-uploads dalam query.
  const result = await client.listUploads(query);

  result.uploads.forEach((upload) => {
    // ID unggah untuk unggah multi-bagian.
    console.log(upload.uploadId);
    // Gabungkan semua bagian yang diunggah menjadi satu objek utuh dan tentukan jalur lengkap objek.
    console.log(upload.name);
  });
}

const query = {
  // Tentukan jumlah maksimum event unggah multi-bagian yang akan dikembalikan. Nilai default dan maksimum parameter max-uploads adalah 1000.
  "max-uploads": 1000,
};
listUploads(query);

Daftar bagian yang diunggah

Selama unggah multi-bagian, Anda dapat memanggil metode client.listParts untuk mencantumkan semua bagian yang berhasil diunggah untuk ID unggah tertentu.

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

const client = new OSS({
  // Ganti yourregion dengan wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah China (Hangzhou), atur region menjadi oss-cn-hangzhou.
  region: "yourregion",
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah diatur.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Tentukan nama bucket.
  bucket: "yourbucketname",
});

async function listParts() {
  const query = {
    // Tentukan jumlah maksimum bagian yang akan dikembalikan. Nilai default dan maksimum parameter max-parts adalah 1000.
    "max-parts": 1000,
  };
  let result;
  do { 
    result = await client.listParts(
      // Tentukan jalur lengkap objek (misalnya, exampledir/exampleobject.txt). Jalur lengkap objek tidak boleh mengandung nama bucket.
      "exampledir/exampleobject.txt",
      // ID unggah diperoleh dari tanggapan setelah Anda memanggil InitiateMultipartUpload untuk menginisialisasi unggah multi-bagian dan sebelum Anda memanggil CompleteMultipartUpload untuk menyelesaikan unggah multi-bagian.
      "0004B999EF518A1FE585B0C9360D****",
      query
    );
    // Tentukan posisi awal untuk operasi daftar berikutnya. Hanya bagian dengan nomor bagian yang lebih besar dari nilai ini yang akan dicantumkan.
    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();

Referensi

• Untuk kode contoh lengkap unggah multi-bagian, lihat Contoh GitHub.

• Metode multipartUpload dalam Node.js SDK mengenkapsulasi tiga operasi API berikut:

  • Untuk informasi selengkapnya tentang operasi API untuk menginisialisasi 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 unggah multi-bagian, lihat AbortMultipartUpload.

• Untuk informasi selengkapnya tentang operasi API untuk mencantumkan bagian yang diunggah, lihat ListParts.

• Untuk informasi selengkapnya tentang operasi API untuk mencantumkan semua unggah multi-bagian yang sedang berlangsung (unggahan yang telah diinisialisasi tetapi belum diselesaikan atau dibatalkan), lihat ListMultipartUploads.