Unggah File melalui SDK PDS dengan Dukungan Multipart & Resume - Drive and Photo Service

PDSClient menyediakan dua metode untuk mengunggah file: uploadFile dan createUploadTask. Topik ini menjelaskan kedua metode tersebut.

Metode uploadFile

Mengunggah file dengan cara yang mudah.

Kata kunci await dapat digunakan untuk menunggu hingga file selesai diunggah.
Jika nilai dari state adalah stopped, cancelled, atau error, maka PDSError akan dilemparkan.

// client menunjukkan instance PDSClient.
const cp = await client.uploadFile(from, uploadTo, options)

Contoh

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let uploadTo = {drive_id: '1', parent_file_id: 'root'};
    await client.uploadFile(file, uploadTo);
    console.log("Diunggah");
  }
</script>

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi
file	IFile \| string	Ya	File yang akan diunggah. Jika Anda ingin mengunggah file di browser web, tentukan file HTML yang ingin Anda unggah. Jika Anda ingin mengunggah file di lingkungan Node.js, atur nilainya ke jalur file lokal atau informasi jalur lokal.
uploadTo	IUpCheckpoint	Ya	Informasi tentang direktori Drive and Photo Service (PDS) tempat file akan diunggah. Anda juga dapat mengatur nilainya ke informasi checkpoint terakhir.
options	IUploadOptions		Konfigurasi pengunggahan, termasuk metode callback.

Bidang IFile

Bidang	Tipe	Diperlukan	Deskripsi
path	string	Ya	Jalur.
name	string	Ya	Nama file.
size	number	Ya	Ukuran file.
type	string		`tipe konten` file.

Bidang IUpCheckpoint

Bidang	Tipe	Diperlukan	Deskripsi
file	IFile	Ya	File yang akan diunggah. Jika Anda ingin mengunggah file di browser web, tentukan file HTML yang ingin Anda unggah. Jika Anda ingin mengunggah file di lingkungan Node.js, atur nilainya ke informasi jalur lokal.
path_type	string	Ya	`tipe jalur` domain. Atur nilainya ke `StandardMode`.
loc_id	string		ID lokasi tempat file akan diunggah. Bisa berupa `drive_id` atau `share_id`.
loc_type	string		Tipe lokasi tempat file akan diunggah. Nilai valid: `drive` dan `share`.
parent_file_key	string		ID direktori tempat file akan diunggah. Kami sarankan Anda mengganti parameter ini dengan parameter `parent_file_id`.
drive_id	string		ID drive direktori tempat file akan diunggah. Anda harus menentukan salah satu parameter `drive_id` dan `share_id`.
share_id	string		ID share direktori tempat file akan diunggah. Anda harus menentukan salah satu parameter `drive_id` dan `share_id`.
parent_file_id	string		ID direktori induk tempat file akan diunggah.
new_name	string		Nama baru yang akan digunakan untuk file yang diunggah. Parameter ini mungkin dipengaruhi oleh parameter `check_name_mode`.
id	string		ID tugas unggah.
file_key	string		ID file yang akan diunggah. Kami sarankan Anda mengganti parameter ini dengan parameter file_id.
update_id	string		ID unggah. ID ini dibuat setelah PDS membuat file sementara.
part_info_list	Array<IUpPartInfo>		Daftar bagian yang akan diunggah.
state	string		Status tugas unggah. Nilai valid: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, dan cancelled`.
message	string		Pesan kesalahan.
progress	number		Progres unggah. Nilai valid: 0 hingga 100.
loaded	number		Jumlah byte yang telah diunggah. Unit: `bytes`.
chunk_size	number		Ukuran sebuah bagian. Unit: `bytes`.
start_time	number		Waktu mulai tugas unggah. Unit: `millisecond`.
end_time	number		Waktu akhir tugas unggah. Unit: `millisecond`.
used_avg_speed	number		Kecepatan rata-rata saat file diunggah. Unit: `bytes/s`.
used_time_len	number		Jangka waktu yang telah berlalu sejak dimulainya tugas unggah. Unit: `millisecond`.

Anda harus menentukan loc_id + loc_type atau share_id || drive_id.
Anda harus menentukan parent_file_key atau parent_file_id.

Bidang IUploadOptions (memperluas IUpConfig)

Bidang	Tipe	Diperlukan	Deskripsi
onReady	(task: UploadTask) => void		Metode callback untuk `tugas unggah` setelah tugas dibuat.
onProgress	(state: string, progress:number) => void		Metode callback yang digunakan untuk mendengarkan progres. Anda dapat menggunakan metode ini untuk mendengarkan progres perhitungan nilai hash SHA-1, progres unggah, atau progres perhitungan nilai CRC-64. Nilai valid dari `state`: `computing_hash`, `running`, dan `checking`. Nilai computing_hash menunjukkan bahwa nilai hash SHA-1 sedang dihitung. Nilai running menunjukkan bahwa tugas unggah sedang berlangsung. Nilai checking menunjukkan bahwa nilai CRC-64 sedang dihitung. Nilai valid dari `progress`: 0 hingga 100.
onStateChange	(cp: IUpCheckpoint, state: string, error?: PDSError) => void		Metode callback yang digunakan untuk mendengarkan perubahan status tugas. Nilai valid dari state: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, dan cancelled`
onPartComplete	(cp:IUpCheckpoint, part: IPartInfo) => void		Metode callback yang digunakan untuk mendengarkan penyelesaian unggah bagian.
... Bidang IUpConfig lainnya

Bidang IUpPartInfo

Bidang	Tipe	Diperlukan	Deskripsi
part_number	number	Ya	Nomor urutan bagian. Nomor dimulai dari 1.
part_size	number	Ya	Ukuran bagian.
etag	string		`ETag` yang dihasilkan setelah bagian diunggah.

Bidang IUpConfig

Bidang	Tipe	Diperlukan	Deskripsi
parallel_upload	boolean		Menentukan apakah akan mengunggah bagian secara bersamaan. Nilai default: `false`.
check_name_mode	string		Kebijakan yang digunakan ketika file baru memiliki nama yang sama dengan file yang sudah ada. Nilai valid: `overwrite`: menimpa file yang sudah ada dengan file yang memiliki nama yang sama dengan file yang sudah ada. `auto_rename`: menambahkan angka acak di akhir nama file. `refuse`: tidak membuat file yang memiliki nama yang sama dengan file yang sudah ada. `ignore`: membuat file yang memiliki nama yang sama dengan file yang sudah ada.
checking_crc	boolean		Menentukan apakah akan melakukan verifikasi CRC. Nilai default: `true`.
chunk_con_auto	boolean		Menentukan apakah akan menyesuaikan jumlah bagian yang diunggah secara bersamaan.
init_chunk_con	number		Jumlah kustom bagian yang diunggah secara bersamaan. Bidang ini hanya berlaku jika `chunk_con_auto` disetel ke `false`.
max_chunk_size	number		Ukuran bagian.
ignore_rapid	boolean		Menentukan apakah akan memaksa menonaktifkan transfer file instan. Nilai default: `false`. Bidang ini dapat digunakan untuk pengujian.

Parameter respons

Parameter	Tipe	Diperlukan	Deskripsi
cp	IUpCheckpoint	Ya	Informasi checkpoint dari tugas unggah. Status valid termasuk `success`, `rapid_success`, `error`, `stopped`, dan `cancelled`.

Metode createUploadTask

Membuat tugas unggah.

const task = client.createUploadTask(checkpoint, configs)

Contoh

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let cp = {
      
      // from
      file,
      
      // to
      path_type: "StandardMode",
      // loc_id: "1", // Anda bisa mengganti parameter ini dengan parameter drive_id.
      // loc_type: "drive",
      // parent_file_key: "root", // Anda bisa mengganti parameter ini dengan parameter parent_file_id.
      
      drive_id: "1", 
      parent_file_id: "root"
    };
  
    // Buat tugas unggah.
    const task = client.createUploadTask(cp);
    
    // Dengarkan progres unggah.
    task.on('progress', (state, progress)=>{
       console.log(state, progress);
    });
  
    // Mulai tugas unggah.
    task.start();
   
    // ...
  }
</script>

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IUpCheckpoint	Ya	Atribut unggah.
configs	IUpConfig		Konfigurasi unggah.

Parameter respons

Parameter	Tipe	Diperlukan	Deskripsi
task	UploadTask	Ya	Instance UploadTask.

Kelas UploadTask

Membuat tugas untuk mengunggah file.

Metode yang didukung

.wait()

Setelah Anda memanggil metode ini, status tugas berubah menjadi menunggu.

.start()

Anda dapat memanggil metode ini untuk memulai tugas unggah. Setelah tugas dimulai, sistem mulai menghitung nilai hash SHA-1. Jika file diunggah secara instan, pesan dikembalikan yang menunjukkan transfer file instan berhasil. Jika file tidak dapat diunggah secara instan, sistem mulai mengunggah file dalam bagian-bagian. Parameter config.parallel_upload menentukan apakah akan mengunggah bagian secara bersamaan.

task.start();

.stop()

Anda dapat memanggil metode ini untuk menangguhkan tugas unggah. state tugas akan berubah menjadi stopped, dan instance klien akan menyimpan informasi checkpoint untuk digunakan dalam unggah berkelanjutan berikutnya.

task.stop();

.cancel()

Anda dapat memanggil metode ini untuk membatalkan tugas unggah. Status tugas berubah menjadi dibatalkan.

task.cancel()

.getCheckpoint()

Anda dapat memanggil metode ini untuk menanyakan informasi checkpoint dari tugas unggah. Sebagai alternatif, Anda dapat menanyakan informasi checkpoint tugas menggunakan callback event.

IUpCheckpoint cp = task.getCheckpoint()

.on(eventname, callback)

Anda dapat memanggil metode ini untuk mengonfigurasi pendengar.

// Contoh: event progres
task.on('progress', (state, progress)=>{
   console.log(state, progress)
})

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
eventname	ICheckpoint	Ya	Nama event. Nilai valid: `progress`, `statechange`, dan `partialcomplete`.
callback	Function	Ya	Fungsi callback.

Event yang didukung

Metode callback untuk event progres

Anda dapat mendengarkan event jenis berikut: progress, statechange, dan partialcomplete.

task.on('progress', (state, progress)=>{
   //
})

Parameter

Parameter

Tipe

Diperlukan

Deskripsi

state

string

Status tugas.

Nilai valid: computing_hash, running, dan checking. Nilai computing_hash menunjukkan bahwa nilai hash SHA-1 sedang dihitung. Nilai running menunjukkan bahwa tugas unggah sedang berlangsung. Nilai checking menunjukkan bahwa nilai CRC-64 sedang dihitung.

progress

number

Progres unggah. Nilai valid: 0 hingga 100.

Metode callback untuk event statechange

task.on('statechange', (checkpoint, state, error)=>{
   //
})

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IUpCheckpoint	Ya	Informasi checkpoint dari tugas unggah.
state	string	Ya	Status tugas unggah. Nilai valid: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, dan cancelled`.
error	PDSError		Kesalahan unggah. Nilai dikembalikan jika status tugas adalah `error`, `stopped`, atau `cancelled`.

Metode callback untuk event partialcomplete

task.on('partialcomplete', (checkpoint, partInfo)=>{
   //
})

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IUpCheckpoint	Ya	Informasi checkpoint dari tugas unggah.
partInfo	IUpPartInfo	Ya	Informasi tentang bagian yang diunggah.

Status

Tugas unggah dapat berada dalam salah satu status berikut.

Status	Deskripsi
waiting	Tugas unggah sedang menunggu untuk dimulai. Secara default, tugas unggah berada dalam status ini setelah dibuat. Anda dapat memanggil metode `wait()` untuk memicu status ini.
start	Tugas unggah dimulai. Anda dapat memanggil metode `start()` untuk memicu status ini.
created	Tugas unggah dibuat. Status ini dipicu setelah PDS membuat file sementara. Dalam hal ini, `upload ID` dihasilkan.
computing_hash	Nilai hash `SHA-1` sedang dihitung, yang digunakan untuk transfer file instan. Jika file diunggah secara instan, status tugas berubah menjadi `rapid_success`.
running	Tugas unggah sedang berjalan.
stopped	Tugas unggah ditangguhkan.
complete	Tugas unggah selesai tetapi file belum diverifikasi.
checking	Pemeriksaan `CRC-64` sedang dilakukan pada file.
success	Tugas unggah berhasil.
rapid_success	File diunggah secara instan.
error	Tugas unggah gagal. Status ini dipicu jika pemanggilan operasi API gagal, koneksi jaringan gagal, atau operasi I/O lokal gagal selama proses unggah.
cancelled	Tugas unggah dibatalkan. Anda dapat memanggil metode `.cancel()` untuk memicu status ini.

Parameter yang mungkin digunakan

// Contoh:
console.log(task.speed)

Parameter	Tipe	Deskripsi
speed	number	Kecepatan unggah. Unit: `byte/s`. Parameter ini hanya valid jika status tugas adalah running.
progress	number	Progres unggah. Nilai valid: 0 hingga 100.
loaded	number	Ukuran bagian yang telah diunggah. Unit: `bytes`.
file	IFile	Informasi tentang file.
left_time	number	Perkiraan waktu yang diperlukan untuk mengunggah bagian yang tersisa. Unit: `seconds`.
start_time	number	Waktu mulai tugas unggah. Unit: `millisecond`.
end_time	number	Waktu akhir tugas unggah. Unit: `millisecond`.
used_avg_speed	number	Kecepatan unggah rata-rata. Unit: `byte/s`.
used_time_len	number	Durasi unggah. Unit: `millisecond`.