Unggah file - Drive and Photo Service

Topik ini menjelaskan praktik terbaik untuk mengunggah file ke Drive and Photo Service (PDS). Anda dapat merujuk pada topik ini untuk mengunggah file ke PDS.

Istilah

folder: file bertipe direktori. Folder tidak berisi data fisik. Anda dapat memanggil operasi CreateFile dari PDS untuk membuat folder.
file: file bertipe non-direktori. File berisi data fisik. Untuk membuat file, Anda harus mengunggah file lokal ke PDS. Topik ini menjelaskan cara mengunggah file ke PDS.

Pengunggahan file

Proses

Untuk mengunggah file ke PDS, ikuti tiga langkah berikut:

Panggil operasi CreateFile untuk membuat dan menginisialisasi file. PDS mengembalikan metadata file dan URL yang digunakan untuk mengunggah file melalui HTTP.
Unggah file menggunakan URL yang dikembalikan pada langkah sebelumnya.
Panggil operasi CompleteFile untuk menyelesaikan proses pengunggahan file.

Prosedur

Contoh berikut menunjukkan cara mengunggah file lokal ke PDS.

1. Buat file

Panggil operasi CreateFile untuk membuat dan menginisialisasi file.

Pengaturan parameter inti:

drive_id = "testDriveId": ID drive tempat file diunggah.
parent_file_id = "root": direktori tempat file diunggah. Nilai root menunjukkan bahwa file diunggah ke direktori root.
name = "testName.jpg": nama file yang akan diunggah.
type = "file": tipe file yang akan diunggah. Nilai valid: file dan folder.
size = 13.381.200: ukuran sebenarnya dari file lokal. Satuan: byte.
part_info_list = [{"part_number":1},{"part_number":2},{"part_number":3}]: bagian-bagian file yang akan diunggah. Tentukan jumlah bagian berdasarkan ukuran file dan ukuran setiap bagian yang ditentukan oleh klien. Anda dapat menentukan beberapa bagian untuk meningkatkan tingkat keberhasilan unggah dan melakukan unggah yang dapat dilanjutkan. Dalam contoh ini, ukuran file sekitar 13 MB dan ukuran setiap bagian yang ditentukan oleh klien adalah 5 MB. Oleh karena itu, tiga bagian diunggah.

Contoh badan permintaan:

{
    "drive_id":"testDriveId",
    "name":"testName.jpg",
    "parent_file_id":"root",
    "part_info_list":[
        {
            "part_number":1
        },
        {
            "part_number":2
        },
        {
            "part_number":3
        }
    ],
    "size":13381200,
    "type":"file"
}

Contoh badan respons:

{
    "parent_file_id":"root",
    "part_info_list":[
        {
            "part_number":1,
            "upload_url":"https://xxxx1"
        },
        {
            "part_number":2,
            "upload_url":"https://xxxx2"
        },
        {
            "part_number":3,
            "upload_url":"https://xxxx3"
        }
    ],
    "upload_id":"testUploadId",
    "rapid_upload":false,
    "type":"file",
    "file_id":"testFileId",
    "revision_id":"testRevisionId",
    "domain_id":"testDomainId",
    "drive_id":"testDriveId",
    "file_name":"testName.jpg"
}

Parameter respons inti:

file_id: ID unik yang diberikan ke file oleh PDS. ID setiap file bersifat unik dalam satu drive.
upload_id: ID yang diberikan ke proses pengunggahan file oleh PDS. ID proses pengunggahan file digunakan dalam langkah-langkah selanjutnya seperti langkah untuk menyelesaikan proses pengunggahan file.
part_info_list: URL unggah yang diberikan ke bagian-bagian oleh PDS. Jumlah URL sama dengan jumlah bagian yang akan diunggah. PDS memberikan setiap bagian sebuah URL unggah.

2. Unggah file

Lakukan iterasi dan unggah bagian-bagian file berdasarkan URL yang dikembalikan di Langkah 1. Dalam contoh ini, metode HTTP PUT digunakan.

Contoh kode Java:

// Iterasi semua bagian file yang akan diunggah.
for (PartInfo uploadPartInfo : partInfoList) {
   // Hitung nomor seri bagian dalam file lokal.
   int number = uploadPartInfo.getPartNumber();
   long pos = (number - 1) * partSize;
   long size = Math.min(length - pos, partSize);
   byte[] partContent = new byte[(int) size];

   // Baca data bagian dari file lokal ke memori.
   RandomAccessFile randomAccessFile = new RandomAccessFile(localFile, "r");
   randomAccessFile.seek(pos);
   randomAccessFile.readFully(partContent, 0, (int) size);
   randomAccessFile.close();

   // Unggah bagian.
   RequestBody body = RequestBody.create(null, partContent);
   Request request = new Request.Builder()
   .url(uploadPartInfo.getUploadUrl())
   .header("Content-Length", String.valueOf(size))
   .put(body)
   .build();

   OkHttpClient okHttpClient = new OkHttpClient.Builder().build();
   Response response = okHttpClient.newCall(request).execute();

   // Tentukan apakah bagian telah diunggah.
   if (!response.isSuccessful()) {
   System.out.println(response.body().string() + "\n");
   Assert.fail("upload part failed, partNumber:" + number);
   return "";
   }
   System.out.println("upload part success, partNumber:" + number);
}

3. Selesaikan proses pengunggahan file

Panggil operasi CompleteFile untuk menyelesaikan proses pengunggahan file setelah semua bagian file diunggah.

Pengaturan parameter inti:

drive_id = "testDriveId": ID drive tempat file diunggah.
file_id = "testFileId": ID file. Atur parameter ini ke nilai parameter file_id yang dikembalikan di Langkah 1.
upload_id = "testUploadId": ID proses pengunggahan file. Atur parameter ini ke nilai parameter upload_id yang dikembalikan di Langkah 1.

Contoh badan permintaan:

{
    "drive_id":"testDriveId",
    "file_id":"testFileId",
    "upload_id":"testUploadId"
}

Jika kode status HTTP 200 dikembalikan, file berhasil diunggah.

Contoh badan respons:

{
    "domain_id":"testDomainId",
    "drive_id":"testDriveId",
    "file_id":"testFileId",
    "parent_file_id":"root",
    "type":"file",
    "file_extension":"jpg",
    "name":"testName.jpg",
    "size":13381200,
    "status":"available",
    "content_hash":"xxxxx",
    "created_at":"2023-01-16T11:55:12.166Z",
    "updated_at":"2023-01-16T11:55:13.368Z"
}

Unggah yang dapat dilanjutkan

Skenario

Saat mengunggah file, Anda dapat sementara menghentikan pengunggahan file. Misalnya, jika Anda ingin mengunggah file hanya menggunakan Wi-Fi, Anda dapat sementara menghentikan pengunggahan file jika Wi-Fi tidak tersedia dan melanjutkan pengunggahan file ketika Wi-Fi tersedia.

Implementasi

Saat mengunggah file, Anda dapat membagi file menjadi beberapa bagian.

Misalnya, jika Anda ingin mengunggah file sebesar 50 MB dan ukuran setiap bagian yang ditentukan oleh klien adalah 5 MB, klien membagi file menjadi 10 bagian.

Klien telah mengunggah enam bagian pertama ke PDS, dan Anda menghentikan pengunggahan file saat bagian ketujuh sedang diunggah. Dalam hal ini, klien perlu menyimpan informasi antara proses pengunggahan file, seperti informasi file dan kemajuan pengunggahan. Klien dapat menyimpan informasi antara ke database.

Ketika Anda melanjutkan pengunggahan file, data parsial bagian ketujuh yang diunggah ke PDS dibuang. Klien melanjutkan pengunggahan file dari bagian ketujuh yang belum sepenuhnya diunggah. Ketika klien melanjutkan pengunggahan file, URL unggah bagian yang tersisa mungkin menjadi tidak valid dan kode kesalahan 403 dapat dikembalikan. Dalam hal ini, Anda dapat memanggil operasi ListUploadedParts untuk mendapatkan URL unggah bagian yang tersisa.

Jika proses pengunggahan file dihentikan lebih dari 10 hari, Anda tidak dapat melakukan unggah yang dapat dilanjutkan. Dalam hal ini, Anda harus memanggil operasi CreateFile untuk membuat file lain dan mengunggah file lokal lagi.

Pemindahan file instan

Ikhtisar

PDS menyediakan kemampuan deduplikasi file di tingkat domain. Saat Anda mengunggah file yang sudah ada di domain PDS, Anda tidak perlu melakukan proses pengunggahan file lengkap. Dalam hal ini, Anda hanya perlu menghitung nilai hash Secure Hash Algorithm 1 (SHA-1) dari file, dan file dapat diunggah ke PDS dalam hitungan detik.

Skenario

Jika Pengguna A telah mengunggah film ke drive PDS, Pengguna B dapat mengunggah film tersebut ke drive lain di PDS di domain yang sama menggunakan fitur pemindahan file instan. Pengguna B tidak perlu melakukan proses lengkap untuk mengunggah film. Ini meningkatkan efisiensi unggah dan menghemat lalu lintas unggah.

File yang diunggah oleh Pengguna B ke PDS menggunakan fitur pemindahan file instan independen dari file di drive Pengguna A. Ini memastikan keamanan data.

Gunakan fitur pemindahan file instan

Sebelum menggunakan fitur pemindahan file instan untuk mengunggah file, Anda harus menghitung nilai hash SHA-1 dari file. Saat Anda memanggil operasi CreateFile, Anda harus menyetel parameter content_hash ke nilai hash SHA-1 yang dihitung dari file.

Pengaturan parameter inti:

content_hash_name = "sha1": algoritma perhitungan untuk pemindahan file instan. Hanya SHA-1 yang didukung.
content_hash = "xxxx": nilai hash SHA-1 yang dihitung dari file.
size = 13.381.200: ukuran file.

Pengaturan parameter lainnya sama dengan yang dijelaskan di bagian "Pengunggahan file" dari topik ini.

Contoh badan permintaan:

{
    "drive_id":"testDriveId",
    "name":"testName.jpg",
    "parent_file_id":"root",
    "content_hash":"xxxxx",
    "content_hash_name":"sha1",
    "part_info_list":[
        {
            "part_number":1
        },
        {
            "part_number":2
        },
        {
            "part_number":3
        }
    ],
    "size":13381200,
    "type":"file"
}

Contoh kode Java untuk menghitung nilai hash SHA-1 dari file:

public static String getFileHash(File file) throws IOException {
 	 return Hex.encodeHexString((getFileHashBytes(file)));
}

public static byte[] getFileHashBytes(File file) throws IOException {
   byte[] sha1;
   try {
     MessageDigest digest = MessageDigest.getInstance("SHA1");
     byte[] buffer = new byte[10 * 1024];
     FileInputStream is = new FileInputStream(file);
     int len;
     while ((len = is.read(buffer)) != -1) {
        digest.update(buffer, 0, len);
     }
     is.close();
     sha1 = digest.digest();
   } catch (NoSuchAlgorithmException e) {
   	 throw new RuntimeException("Algoritma SHA1 tidak ditemukan.");
   }
   return sha1;
}

Contoh badan respons:

{
    "domain_id":"testDomainId",
    "drive_id":"testDriveId",
    "parent_file_id":"root",
    "upload_id":"testUploadId",
    "rapid_upload":true,
    "type":"file",
    "file_id":"testFileId",
    "revision_id":"testRevisionId",
    "file_name":"testName.jpg"
}

Parameter respons inti:

rapid_upload: menunjukkan apakah file diunggah menggunakan fitur pemindahan file instan.

Nilai true menunjukkan bahwa file diunggah menggunakan fitur pemindahan file instan. Berdasarkan nilai SHA-1 hash yang ditentukan, PDS mendeteksi file yang ada yang berisi data yang sama dengan file yang akan diunggah di domain yang sama. Dalam hal ini, URL unggah bagian file tidak dikembalikan dalam badan respons, dan klien tidak perlu melakukan langkah-langkah selanjutnya, termasuk langkah-langkah untuk mengunggah file dan menyelesaikan proses pengunggahan file.

Nilai false menunjukkan bahwa file tidak diunggah menggunakan fitur pemindahan file instan. Dalam hal ini, badan respons berisi URL unggah bagian file. Klien harus melakukan langkah-langkah selanjutnya, termasuk langkah-langkah untuk mengunggah file dan menyelesaikan proses pengunggahan file.

Gunakan fitur pra-hash untuk meningkatkan akurasi

Sebelum menggunakan fitur pemindahan file instan untuk mengunggah file, Anda harus menghitung nilai hash SHA-1 dari file. Dalam banyak kasus, klien memiliki kapasitas komputasi yang terbatas. Menghitung nilai hash SHA-1 lengkap dari file besar memerlukan waktu. Selain itu, jika tidak ada data yang cocok dengan nilai hash SHA-1 dari file di domain PDS, file tidak dapat diunggah menggunakan fitur pemindahan file instan. Ini membuang kapasitas komputasi klien dan meningkatkan jumlah waktu yang digunakan untuk mengunggah file.

Untuk menyelesaikan masalah ini dan meningkatkan akurasi pemindahan file instan, PDS menyediakan fitur pra-hash. Anda hanya perlu menghitung nilai hash SHA-1 dari data 1 KB pertama file. Saat Anda memanggil operasi CreateFile, atur parameter pre_hash ke nilai hash SHA-1 yang dihitung dari data 1 KB pertama file. Server memeriksa apakah data sudah ada di domain PDS.

Pengaturan parameter inti:

pre_hash = "xxxxx": nilai hash SHA-1 dari data 1 KB pertama file.

Pengaturan parameter lainnya sama dengan yang dijelaskan di bagian "Pengunggahan file" dari topik ini.

Contoh badan permintaan:

{
    "drive_id":"10530",
    "name":"testName.jpg",
    "parent_file_id":"root",
    "part_info_list":[
        {
            "part_number":1
        },
        {
            "part_number":2
        },
        {
            "part_number":3
        }
    ],
    "pre_hash":"xxxx",
    "size":13381200,
    "type":"file"
}

Analisis respons:

Jika kode status HTTP 409 dikembalikan, data di domain yang sama cocok dengan nilai hash SHA-1 dari data 1 KB pertama file, yang menunjukkan bahwa file yang ada di domain mungkin berisi data yang sama dengan file yang akan diunggah. Dalam hal ini, klien dapat melanjutkan untuk menghitung nilai hash SHA-1 lengkap dari file, memanggil operasi CreateFile lagi, dan kemudian mencoba mengunggah file menggunakan fitur pemindahan file instan. Perhatikan bahwa fitur pra-hash tidak menjamin akurasi pencocokan karena data 1 KB pertama file mungkin cocok dengan data di PDS dengan probabilitas tinggi.
Jika kode status HTTP 201 dikembalikan, data di domain yang sama tidak cocok dengan nilai hash SHA-1 dari data 1 KB pertama file, yang menunjukkan bahwa tidak ada file di domain yang berisi data yang sama dengan file yang akan diunggah. Dalam hal ini, URL unggah bagian file dikembalikan secara sinkron, dan klien dapat melanjutkan untuk melakukan langkah-langkah selanjutnya dari proses pengunggahan file.

Nilai pra-hash dihitung secara asinkron di latar belakang dan mungkin dikembalikan dengan latensi beberapa menit. Jika Anda mengunggah file duplikat segera setelah file diunggah ke PDS, file duplikat mungkin tidak dapat diunggah menggunakan fitur pemindahan file instan.

Diagram alir

Pengunggahan file dalam mode penimpaan

PDS memungkinkan Anda mengunggah file dengan menimpa file yang ada. Untuk melakukannya, atur parameter file_id ke ID file yang ada saat Anda memanggil operasi CreateFile. Kemudian, ikuti proses pengunggahan file reguler untuk mengunggah file.

Contoh badan permintaan:

{
    "drive_id":"testDriveId",
    "file_id":"testFileId",
    "name":"testName.jpg",
    "parent_file_id":"root",
    "part_info_list":[
        {
            "part_number":1
        },
        {
            "part_number":2
        },
        {
            "part_number":3
        }
    ],
    "size":13373603,
    "type":"file"
}

Masalah utama:

Setelah file ditimpa, ID file tetap tidak berubah. Anda dapat menggunakan ID file yang sama untuk melakukan operasi pada file.
Saat beberapa klien secara bersamaan menimpa file yang sama, versi file yang diunggah oleh klien yang terakhir memanggil operasi CompleteFile digunakan sebagai versi terbaru file.
Jika Anda ingin menyimpan versi file sebelum file ditimpa, Anda harus mengaktifkan fitur versi historis. Untuk informasi lebih lanjut, lihat ListRevision.

FAQ

Apa yang harus saya lakukan jika URL unggah bagian file kedaluwarsa?

URL yang digunakan untuk mengunggah bagian file berlaku selama satu jam. Jika Anda memanggil operasi CreateFile untuk mengunggah bagian file setelah satu jam, kode kesalahan 403 dikembalikan. Misalnya, jika Anda menghentikan pengunggahan file dan melakukan unggah yang dapat dilanjutkan setelah satu jam, kode kesalahan 403 dikembalikan. Dalam hal ini, Anda dapat memanggil operasi ListUploadedParts untuk mendapatkan URL unggah bagian yang tersisa sebelum Anda melakukan unggah yang dapat dilanjutkan.

Batas apa yang perlu saya perhatikan saat mengunggah file?

Ukuran setiap bagian file bisa mencapai maksimal 5 GB.
Server menghitung nilai hash SHA-1 dari file dalam mode streaming. Oleh karena itu, bagian-bagian dari satu file harus diunggah secara berurutan dan tidak dapat diunggah secara bersamaan.
Bagian-bagian file tidak dapat ditimpa.

Berapa periode validitas untuk proses pengunggahan file?

Anda harus menyelesaikan proses pengunggahan file dalam waktu 10 hari. Jika tidak, proses pengunggahan file dibuang. Dalam hal ini, Anda harus memanggil operasi CreateFile untuk membuat file lain di PDS dan mengunggah file lokal lagi.