Unduh File dengan Transfer Resumable melalui SDK JavaScript PDS - Drive and Photo Service

PDSClient menyediakan dua metode untuk mengunduh satu file: downloadFile dan createDownloadTask. Topik ini menjelaskan cara menggunakan kedua metode tersebut untuk mengunduh file dari Photo and Drive Service (PDS).

Catatan

Mengunduh file pada klien web:

Karena batasan API browser, kesalahan mungkin dilaporkan jika cache browser tidak mencukupi dan sulit untuk mengidentifikasi penyebab spesifiknya. Oleh karena itu, disarankan untuk tidak menggunakan metode downloadFile atau createDownloadTask untuk mengunduh file pada klien web.

Disarankan untuk menggunakan metode berikut dalam mengunduh file pada klien web:

Mengunduh satu file
Gunakan metode listFiles atau getFile untuk mendapatkan nilai parameter download_url dalam objek IFileItem. Buka URL unduhan di browser untuk mengunduh file. Metode ini cocok untuk pengunduhan satu file, bukan beberapa file atau file dalam direktori.
Mengunduh beberapa file atau file dalam direktori
Telusuri secara rekursif semua file dalam daftar file atau direktori untuk mendapatkan nilai parameter download_url untuk setiap file. Unduh file di frontend dan hasilkan paket ZIP. Metode ini cocok untuk pengunduhan beberapa file atau file dalam direktori. Namun, metode ini membutuhkan banyak memori dan tidak cocok untuk pengunduhan file besar atau direktori.

Metode downloadFile

Cara mudah untuk mengunduh file.

Kata kunci await dapat digunakan untuk menunggu hingga pengunduhan selesai.
Jika nilai parameter state adalah stopped, cancelled, atau error, maka PDSError dilemparkan.

const cp = await client.downloadFile(pdsFile, downloadTo, options)

Contoh

// from
const pdsFile= {
  drive_id: '1',
  file_id: 'xxxxxxxx',
}

// to  (Catatan: Jika Anda mengunduh file di browser, Anda tidak perlu menentukan parameter ini. Dalam hal ini, gunakan string kosong.)
const downloadTo = '/Users/test/a.txt'

const options = {
  onProgress(state, progress){
    console.log(state, progress)
  }
}

// Unduh file.
await client.downloadFile(pdsFile, downloadTo, options);

console.log('Pengunduhan selesai.');

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi
pdsFile	Partial<IDownCheckpoint>	Ya	File yang akan diunduh, atau informasi titik kontrol unduhan.
downloadTo	string	Ya	Path tempat file akan diunduh. Jika Anda mengunduh file di browser, Anda tidak perlu menentukan parameter ini. Dalam hal ini, gunakan string kosong.
options	IDownloadOptions		Konfigurasi unduhan, termasuk metode callback.

Parameter IDownCheckpoint

Parameter	Tipe	Diperlukan	Deskripsi
path_type	string	Ya	Mode penyimpanan data domain. Tetapkan nilainya menjadi `StandardMode`.
loc_id	string		ID drive atau share tempat file yang akan diunduh disimpan. Kami menyarankan Anda mengganti parameter ini dengan parameter `drive_id` atau `share_id`.
loc_type	string		Tipe lokasi file yang akan diunduh. Parameter ini digunakan bersama dengan parameter `loc_id`. Nilai valid: `drive` dan `share`.
file_key	string		Pengenal unik file yang akan diunduh. Anda harus menentukan salah satu dari parameter file_key dan file_id.
drive_id	string		ID drive. Anda hanya dapat menentukan salah satu dari parameter `drive_id` dan `share_id`.
share_id	string		ID share. Anda hanya dapat menentukan salah satu dari parameter `drive_id` dan `share_id`.
file_id	string		ID file yang akan diunduh. Anda harus menentukan salah satu dari parameter file_key dan file_id.
file	IFile	Ya	File yang akan diunduh.
id	string		ID tugas unduhan.
download_id	string		ID unduhan. Ini adalah ID yang dihasilkan jika file sementara lokal dibuat.
download_url	string		URL unduhan.
content_md5	string		Nilai hash MD5 dari file.
crc64ecma	string		Nilai CRC-64 dari file.
content_type	string		Tipe konten dari file.
part_info_list	Array<IDownPartInfo>		Daftar bagian yang diunduh.
state	string		Status tugas unduhan. Nilai valid: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`.
message	string		Pesan kesalahan.
progress	number		Kemajuan tugas unduhan. Nilai valid: 0 hingga 100.
loaded	number		Jumlah byte yang telah diunduh. Unit: `bytes`.
start_time	number		Waktu ketika tugas unduhan dimulai. Unit: `milliseconds`.
end_time	number		Waktu ketika tugas unduhan berakhir. Unit: `milliseconds`.
used_avg_speed	number		Kecepatan rata-rata pengunduhan file. Unit: `bytes/s`.
used_time_len	number		Periode waktu yang telah dihabiskan untuk tugas unduhan. Unit: `milliseconds`.

Anda hanya dapat menentukan salah satu dari parameter berikut: loc_id together with loc_type, share_id, and drive_id.
Anda harus menentukan salah satu dari parameter file_key dan file_id.

Parameter IDownloadOptions (extends IDownConfig)

Parameter	Tipe	Diperlukan	Deskripsi
onReady	(task: UploadTask) => void		Metode callback untuk tugas unduhan setelah tugas dibuat.
onProgress	(state: string, progress:number) => void		Metode callback yang digunakan untuk mendengarkan kemajuan tugas. Anda dapat menggunakan metode ini untuk mendengarkan kemajuan pengunduhan dan kemajuan perhitungan nilai CRC-64. Nilai valid dari `state`: `running` dan `checking`. Nilai running menentukan bahwa tugas unduhan sedang berlangsung. Nilai checking menentukan bahwa nilai CRC-64 sedang dihitung. Nilai valid dari `progress`: 0 hingga 100.
onStateChange	(cp: IDownCheckpoint, state: string, error?: PDSError) => void		Metode callback yang digunakan untuk mendengarkan perubahan status tugas. Nilai valid dari `state`: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`.
onPartComplete	(cp:IDownCheckpoint, part: IPartInfo) => void		Metode callback yang digunakan untuk mendengarkan penyelesaian pengunduhan bagian.
... Parameter IDownConfig lainnya			Parameter lainnya.

Parameter IDownPartInfo

Parameter	Tipe	Diperlukan	Deskripsi
part_number	number	Ya	Nomor urut bagian. Nomor dimulai dari 1.
part_size	number	Ya	Ukuran bagian.

Parameter IDownConfig

Parameter	Tipe	Diperlukan	Deskripsi
verbose	boolean		Menentukan apakah akan menampilkan log debug.
checking_crc	boolean		Menentukan apakah akan melakukan verifikasi cyclic redundancy check (CRC). Nilai default: `true`.
chunk_con_auto	boolean		Menentukan apakah akan menyesuaikan jumlah bagian konkuren yang sedang diunduh secara otomatis.
init_chunk_con	number		Jumlah bagian konkuren kustom untuk diunduh. Parameter ini hanya berlaku jika Anda menetapkan parameter `chunk_con_auto` ke `false`.
max_chunk_size	number		Ukuran bagian.

Parameter respons

Parameter	Tipe	Diperlukan	Deskripsi
cp	IDownCheckpoint	Ya	Informasi titik kontrol tugas unduhan. Dalam hal ini, tugas unduhan mungkin berada dalam status `success, error, stopped, or cancelled`.

Metode createDownloadTask

Membuat tugas unduhan.

const task = client.createDownloadTask(checkpoint, configs)

Contoh

const cp = {
  // to 
  file: {
    name: "a.txt",
    path: "/Users/zu/a.txt", // Catatan: Jika Anda mengunduh file di browser, Anda tidak perlu menentukan parameter ini. 
    size: 100,
  },
  
  // from
  path_type: 'StandardMode',
  // loc_type: 'drive',  
  // loc_id: '1',        // Parameter ini dapat diganti dengan parameter drive_id.
  // file_key: 'xxxxxxxx'  // Parameter ini dapat diganti dengan parameter file_id.
  
  drive_id: '1',
  file_id: 'xxxxxxxx'
};

const task = client.createDownloadTask(cp);

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IDownCheckpoint	Ya	Parameter yang digunakan untuk membuat tugas unduhan.
configs	IDownConfig		Konfigurasi unduhan.

Parameter respons

Sebuah instance DownloadTask dikembalikan.

Parameter	Tipe	Diperlukan	Deskripsi
task	DownloadTask	Ya	Tugas unduhan.

Kelas DownloadTask

Membuat tugas unduhan untuk mengunduh file.

Metode yang didukung

.wait()

Setelah memanggil metode ini, tugas unduhan masuk ke status menunggu. Nilai parameter state berubah menjadi waiting.

.start()

Anda dapat memanggil metode ini untuk memulai tugas unduhan. Setelah memanggil metode ini, bagian konkuren mulai diunduh.

task.start();

.stop()

Anda dapat memanggil metode ini untuk menghentikan tugas unduhan. Setelah memanggil metode ini, nilai parameter state berubah menjadi stopped. Dalam hal ini, instance klien menyimpan informasi titik kontrol untuk pengunduhan lanjutan berikutnya.

task.stop();

.cancel()

Anda dapat memanggil metode ini untuk membatalkan tugas unduhan. Setelah memanggil metode ini, nilai parameter state berubah menjadi cancelled.

task.cancel()

.getCheckpoint()

Anda dapat memanggil metode ini untuk menanyakan informasi titik kontrol tugas unduhan. Selain memanggil metode ini, Anda dapat menanyakan informasi titik kontrol menggunakan callback event.

var cp = task.getCheckpoint()

.on(eventname, callback)

Anda dapat memanggil metode ini untuk mengonfigurasi pendengar.

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

Parameter Permintaan

Parameter	Tipe	Diperlukan	Deskripsi
eventname	string	Ya	Nama event. Nilai valid: `progress, statechange, and partialcomplete`.
callback	Function	Ya	Metode callback.

Event yang didukung

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

Metode callback untuk event progress

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

Parameter permintaan

Parameter

Tipe

Diperlukan

Deskripsi

state

string

Status tugas unduhan.

Nilai valid dari state: running dan checking. Nilai running menentukan bahwa tugas unduhan sedang berlangsung. Nilai checking menentukan bahwa nilai CRC-64 sedang dihitung.

progress

number

Kemajuan tugas unduhan. Nilai valid: 0 hingga 100.

Metode callback untuk event statechange

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

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IDownCheckpoint	Ya	Informasi titik kontrol tugas unduhan.
state	string	Ya	Status tugas unduhan. Nilai valid: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`.
error	PDSError		Kesalahan unduhan. Nilai mungkin dikembalikan jika statusnya adalah `error`, `stopped`, atau `cancelled`.

Metode callback untuk event partialcomplete

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

Parameter	Tipe	Diperlukan	Deskripsi
checkpoint	IDownCheckpoint	Ya	Informasi titik kontrol tugas unduhan.
partInfo	IDownPartInfo	Ya	Informasi tentang bagian yang telah diunduh.

Status

Tabel berikut menjelaskan kemungkinan status tugas unduhan.

Status	Deskripsi
waiting	Tugas unduhan sedang menunggu untuk dimulai. Secara default, tugas unduhan masuk ke status ini setelah dibuat. Anda dapat memanggil metode `wait()` untuk memicu status ini.
start	Tugas unduhan dimulai. Anda dapat memanggil metode `start()` untuk memicu status ini.
created	Tugas unduhan dibuat. Status ini dipicu setelah file sementara lokal dibuat.
running	Tugas unduhan sedang berlangsung.
stopped	Tugas unduhan dihentikan.
complete	Tugas unduhan selesai tetapi file belum diverifikasi.
checking	Verifikasi `CRC-64` sedang dilakukan pada file.
success	Tugas unduhan berhasil.
error	Tugas unduhan gagal. Status ini dipicu jika pemanggilan operasi API gagal, koneksi jaringan gagal, atau operasi I/O lokal gagal selama proses unduhan.
cancelled	Tugas unduhan dibatalkan. Anda dapat memanggil metode `.cancel()` untuk memicu status ini.

Parameter yang mungkin digunakan

Parameter	Tipe	Deskripsi
speed	number	Kecepatan unduhan. Unit: `byte/s`. Parameter ini hanya valid jika status tugas adalah running.
progress	number	Kemajuan tugas unduhan. Nilai valid: 0 hingga 100.
loaded	number	Ukuran bagian yang telah diunduh. Unit: `bytes`.
file	IFile	Informasi tentang file.
left_time	number	Periode waktu perkiraan yang diperlukan untuk bagian yang tersisa. Unit: `seconds`.
start_time	number	Waktu ketika tugas unduhan dimulai. Unit: `milliseconds`.
end_time	number	Waktu ketika tugas unduhan berakhir. Unit: `milliseconds`.
used_avg_speed	number	Kecepatan unduhan rata-rata. Unit: `byte/s`.
used_time_len	number	Durasi unduhan. Unit: `milliseconds`.