Hash dan ETag: praktik terbaik

Cloud Storage menyarankan Anda untuk memvalidasi data yang ditransfer ke/dari bucket. Halaman ini menjelaskan praktik terbaik untuk melakukan validasi menggunakan checksum CRC32C atau MD5.

Melindungi dari kerusakan data menggunakan hash

Ada berbagai penyebab kerusakan data saat mengupload ke atau mendownload dari Cloud:

  • Error memori pada komputer klien atau server, atau router di sepanjang jalur
  • Bug software (misalnya, di library yang digunakan pelanggan)
  • Perubahan pada file sumber saat upload terjadi dalam jangka waktu yang lebih panjang

Cloud Storage mendukung dua jenis hash yang dapat Anda gunakan untuk memeriksa integritas data: CRC32C dan MD5. CRC32C adalah metode validasi yang direkomendasikan untuk melakukan pemeriksaan integritas. Pelanggan yang memilih MD5 dapat menggunakan hash tersebut, tetapi hash MD5 tidak didukung untuk objek gabungan atau objek yang dibuat dari upload multibagian XML API.

CRC32C

Semua objek Cloud Storage memiliki hash CRC32C. Library untuk menghitung CRC32C meliputi:

CRC32C yang dienkode Base64 memiliki urutan byte big-endian.

MD5

Cloud Storage mendukung hash MD5 untuk objek yang memenuhi kriteria berikut:

Hash ini hanya berlaku untuk objek lengkap, sehingga tidak dapat digunakan untuk memeriksa integritas download parsial yang disebabkan oleh pengimplementasian rentang GET.

ETags

Header ETag objek akan menampilkan nilai MD5 objek jika semua hal berikut ini benar:

Pada kasus lainnya, pengguna tidak boleh membuat asumsi tentang nilai yang digunakan dalam ETag kecuali bahwa nilai tersebut akan berubah setiap kali data atau metadata yang mendasarinya berubah, sesuai dengan spesifikasi.

Objek yang sama dapat memiliki nilai ETag yang berbeda jika diminta dari API XML dibandingkan dengan JSON API.

Validasi

Pemeriksaan integritas download dapat dilakukan dengan melakukan hashing pada data yang didownload dengan cepat dan membandingkan hasil Anda dengan hash yang disediakan server. Anda harus menghapus data yang didownload dengan nilai hash yang salah, dan Anda harus menggunakan logika percobaan ulang untuk menghindari loop tak terbatas yang berpotensi meningkatkan biaya secara signifikan.

Cloud Storage melakukan validasi sisi server dalam kasus berikut:

  • Saat Anda membuat permintaan penyalinan atau penulisan ulang dalam Cloud Storage.

  • Saat memberikan hash MD5 atau CRC32C yang diharapkan dari objek dalam permintaan upload. Cloud Storage hanya membuat objek jika hash yang Anda berikan cocok dengan nilai yang dihitung Cloud Storage. Jika tidak cocok, permintaan akan ditolak dengan error BadRequestException: 400.

Atau, pengguna dapat memilih untuk melakukan validasi sisi klien atas upload mereka dengan mengajukan permintaan untuk metadata objek yang diupload, membandingkan nilai hash yang dilaporkan, dan menghapus objek jika ada ketidakcocokan. Metode ini berguna jika hash MD5 atau CRC32C objek tidak diketahui di awal upload. Untuk menghindari kondisi race saat proses independen menghapus atau mengganti data satu sama lain, gunakan pembuatan dan prasyarat objek.

Dalam kasus upload gabungan paralel, pengguna harus melakukan pemeriksaan integritas untuk setiap upload komponen, lalu menggunakan prasyarat komponen dengan permintaan penulisan untuk melindungi dari kondisi race. Komposisi objek tidak menawarkan validasi MD5 sisi server, sehingga pengguna yang ingin melakukan pemeriksaan integritas menyeluruh harus menerapkan validasi sisi klien ke objek gabungan baru.

XML API

Dalam XML API, hash MD5 dan CRC32C berenkode base64 ditampilkan dan diterima melalui header x-goog-hash. Sebelumnya, MD5 digunakan sebagai ETag objek, tetapi pengguna harus menghindari asumsi ini karena beberapa objek menggunakan nilai ETag tersembunyi yang tidak memberikan jaminan di luar perubahan saat objek berubah.

Validasi upload sisi server dapat dilakukan dengan menyediakan hash yang dihitung secara lokal melalui header permintaan x-goog-hash. Selain itu, MD5 dapat disediakan menggunakan header Content-MD5 HTTP standar (lihat spesifikasi).

JSON API

Di JSON API, properti resource objek md5Hash dan crc32c masing-masing berisi hash MD5 dan CRC32C yang dienkode base64. Menyediakan properti metadata bersifat opsional. Menyediakan properti sebagai bagian dari upload yang dapat dilanjutkan atau upload multibagian JSON API akan memicu validasi sisi server untuk objek baru. Jika Cloud Storage menghitung nilai untuk salah satu properti yang tidak cocok dengan nilai yang diberikan, objek tidak akan dibuat. Jika properti tidak disediakan pada upload, Cloud Storage akan menghitung nilai dan menuliskannya ke metadata objek.

Google Cloud CLI

Untuk Google Cloud CLI, data yang disalin ke atau dari bucket Cloud Storage divalidasi. Ini berlaku untuk perintah cp, mv, dan rsync. Jika checksum data sumber tidak cocok dengan checksum data tujuan, gcloud CLI akan menghapus salinan yang tidak valid dan mencetak pesan peringatan. Ini sangat jarang terjadi. Jika ya, Anda harus mencoba lagi operasi tersebut.

Validasi otomatis ini terjadi setelah objek itu sendiri diselesaikan, sehingga objek yang tidak valid terlihat selama 1-3 detik sebelum diidentifikasi dan dihapus. Selain itu, ada kemungkinan bahwa gcloud CLI dapat terganggu setelah upload selesai, tetapi sebelum melakukan validasi, gcloud CLI ditinggalkan agar objek yang tidak valid tetap berada di tempatnya. Masalah ini dapat dihindari saat mengupload satu file ke Cloud Storage menggunakan validasi sisi server yang terjadi saat menggunakan tanda --content-md5=MD5.

Langkah selanjutnya