Untuk memvalidasi integritas data dan mendeteksi perubahan, Cloud Storage menyarankan Anda untuk menggunakan checksum saat mentransfer data ke dan dari bucket. Halaman ini memberikan informasi tentang cara checksum digunakan dalam Cloud Storage dan cara menentukan checksum saat mengirim permintaan.
Mencegah kerusakan data menggunakan checksum
Data terkadang dapat rusak saat ditransfer ke atau dari cloud karena bug software atau hardware, error memori atau router, gangguan listrik, atau perubahan pada data sumber selama upload file dalam jangka waktu yang lama.
Untuk membantu melindungi Anda dari kerusakan data, Cloud Storage mendukung penggunaan checksum CRC32C dan MD5 untuk memverifikasi integritas data Anda dan mendeteksi perubahan pada data Anda.
CRC32C adalah metode validasi yang direkomendasikan untuk melakukan pemeriksaan integritas. Validasi menggunakan hash MD5 didukung untuk upload file tunggal, tetapi tidak didukung untuk objek yang diupload dalam potongan, seperti objek gabungan dan objek yang diupload menggunakan upload multibagian XML API.
Checksum untuk penulisan data
Untuk penulisan objek, klien menghitung checksum file lokal dan melampirkannya ke header HTTP permintaan upload objek. Server
menerima payload data, menghitung checksum-nya sendiri, dan
memvalidasi data dengan membandingkan kedua checksum setelah upload selesai.
Jika checksum cocok, objek akan disimpan di Cloud Storage beserta checksum-nya. Jika checksum tidak cocok, permintaan tulis akan ditolak dengan error BadRequestException: 400.
Validasi sisi server untuk penulisan data
Cloud Storage melakukan validasi sisi server dalam kasus berikut:
Saat Anda memberikan hash MD5 atau CRC32C objek dalam permintaan upload objek. Untuk mempelajari jenis upload objek, lihat Upload objek.
Saat Anda membuat permintaan penyalinan atau penulisan ulang dalam Cloud Storage. Untuk permintaan penyalinan dan penulisan ulang objek, Cloud Storage secara otomatis melakukan validasi sisi server berdasarkan checksum yang tidak dapat diedit yang disimpan dengan objek sumber.
Upload permintaan tunggal (media) JSON API
Untuk upload media JSON API, Anda dapat menentukan checksum di header X-Goog-Hash permintaan. Contoh:
curl -X POST --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=dog-pic.jpeg"Upload multibagian JSON API
Untuk upload multibagian JSON API, Anda dapat menentukan checksum sebagai bagian dari penampung permintaan, baik di bagian metadata objek maupun di bawah string batas ketiga. Untuk mengetahui detail tentang struktur JSON dan kunci objek yang valid, lihat Representasi resource objek.
Contoh berikut menentukan checksum CRC32C di bagian metadata objek dari penampung permintaan:
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt",
"crc32c": "n03x6A=="
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string--
Contoh berikut menentukan checksum CRC32C dalam string batas ketiga dari penampung permintaan:
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt"
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string
Content-Type: application/json; charset=UTF-8
{ "crc32c": "n03x6A==" }
--separator_string--
Upload yang dapat dilanjutkan JSON API
Untuk upload yang dapat dilanjutkan JSON API, Anda dapat menentukan checksum di header X-Goog-Hash permintaan akhir yang menyelesaikan upload. Contoh:
curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Content-Length: 2000000" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"SESSION_URI"Checksum yang ditentukan dalam permintaan akhir dihitung dari seluruh objek, bukan hanya data objek dalam permintaan akhir.
Upload permintaan tunggal XML API
Untuk upload permintaan tunggal XML API, Anda dapat menentukan checksum di
x-goog-hash header permintaan.
Contoh:
curl -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "x-goog-hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/my-bucket/dog-pic.jpeg"Upload permintaan tunggal XML API juga menerima header Content-MD5 HTTP standar . Untuk mengetahui detailnya, lihat spesifikasi Content-MD5.
Upload multibagian XML API
Untuk upload multibagian XML API, Anda dapat menentukan checksum CRC32C untuk seluruh objek atau checksum individual untuk setiap bagian upload. Untuk menentukan checksum individual untuk bagian upload, sertakan x-goog-hash header dalam permintaan untuk bagian tertentu tersebut.
Contoh:
PUT /dog-pic.jpeg?partNumber=1&uploadId=ABgVH8 HTTP/1.1 Host: my-bucket.storage.googleapis.com Content-Length: 1000000 x-goog-hash: crc32c=n03x6A==
Hanya checksum CRC32C yang dapat digunakan untuk memverifikasi integritas upload multibagian XML API. Checksum MD5 tidak didukung.
Upload gRPC
Saat mengupload objek menggunakan gRPC, Anda dapat menentukan checksum tingkat objek
dalam pesan WriteObject pertama atau terakhir dari permintaan upload apa pun, baik itu
upload satu kali maupun upload yang dapat dilanjutkan.
Selain itu, gRPC mendukung checksum per pesan. Setiap pesan WriteObject berisi potongan data hingga 2 MiB, dan setiap potongan dapat menyertakan checksum-nya sendiri. Anda dapat menentukan checksum per pesan sebagai pengganti atau bersama dengan checksum tingkat objek.
Upload gabungan paralel
Dalam kasus upload gabungan paralel, Anda harus melakukan pemeriksaan integritas untuk setiap upload komponen, lalu menggunakan prasyarat dengan permintaan gabungan upload untuk melindungi dari kondisi race. Permintaan gabungan tidak mendapatkan validasi sisi server, jadi Anda harus melakukan validasi sisi klien pada objek gabungan baru jika menginginkan pemeriksaan integritas menyeluruh.
Salinan dan penulisan ulang Google Cloud CLI
Di gcloud CLI, data yang disalin ke atau dari
bucket Cloud Storage akan otomatis divalidasi. Untuk perintah cp, mv, dan rsync, gcloud CLI menggunakan checksum MD5 atau CRC32C untuk menentukan apakah ada perbedaan antara versi objek yang ditemukan di sumber dan versi yang ditemukan di tujuan. 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 kembali operasi tersebut.
Validasi otomatis ini terjadi setelah objek selesai dan objek yang tidak valid akan terlihat selama 1-3 detik sebelum diidentifikasi dan dihapus. Selain itu, gcloud CLI mungkin terganggu setelah upload selesai, tetapi sebelum melakukan validasi, sehingga objek yang tidak valid tetap ada. Masalah ini dapat dihindari saat mengupload
file tunggal ke Cloud Storage menggunakan validasi sisi server,
yang terjadi saat Anda menggunakan flag --content-md5 untuk menentukan hash MD5.
Google Cloud CLI mengabaikan flag --content-md5 untuk objek yang tidak memiliki hash MD5.
Deteksi perubahan untuk rsync
Perintah gcloud storage rsync membandingkan checksum dalam skenario berikut
untuk menentukan apakah akan melewati transfer:
Sumber dan tujuan adalah bucket Cloud Storage dan objek memiliki checksum MD5 atau CRC32C di kedua bucket.
Objek tidak memiliki waktu modifikasi file (
mtime) di sumber atau tujuan.
Jika objek memiliki nilai mtime di sumber dan tujuan, seperti saat sumber dan tujuan adalah sistem file, perintah rsync akan membandingkan ukuran objek dan nilai mtime, bukan menggunakan checksum. Demikian pula, jika sumbernya adalah bucket dan tujuannya adalah sistem file lokal, perintah rsync akan menggunakan waktu yang dibuat untuk objek sumber sebagai pengganti mtime, dan perintah tidak menggunakan checksum.
Jika mtime dan checksum tidak tersedia, rsync hanya membandingkan ukuran file saat menentukan apakah ada perubahan antara versi sumber objek dan versi tujuan. Misalnya, mtime dan checksum tidak
tersedia saat membandingkan objek gabungan dengan objek di penyedia cloud
yang tidak mendukung CRC32C, karena objek gabungan tidak memiliki checksum MD5.
Validasi sisi klien untuk penulisan data
Anda dapat melakukan validasi sisi klien atas upload dengan mengajukan permintaan untuk metadata objek yang diupload, membandingkan nilai hash objek yang diupload dengan nilai yang diharapkan, dan menghapus objek jika ada ketidakcocokan. Metode ini berguna jika hash MD5 atau CRC32C objek tidak diketahui di awal upload.
Tabel berikut menunjukkan klien di Cloud Storage yang mendukung penghitungan checksum untuk penulisan objek secara default, termasuk versi klien yang mendukung checksum.
| Klien | Versi yang mendukung checksum |
|---|---|
| Library klien C++ Cloud Storage | 2.46 dan yang lebih baru |
| Library klien Go Cloud Storage | 1.60.0 dan yang lebih baru |
| Library klien Java Cloud Storage | 2.62 dan yang lebih baru |
| Library klien Node.js Cloud Storage | 7.19.0 dan yang lebih baru |
| Library klien PHP Cloud Storage | 1.51.0 dan yang lebih baru |
| Library klien Python Cloud Storage | 3.7.0 dan yang lebih baru |
| Library klien Ruby Cloud Storage | 1.60.0 |
| Konektor Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 dan yang lebih baru |
| Google Cloud CLI |
Checksum untuk pembacaan data
Untuk download objek, server mengirimkan objek beserta checksum yang disimpan dalam respons. Klien menghitung checksum file yang didownload berdasarkan byte yang diterima dan membandingkan kedua checksum untuk memverifikasi integritas data.
Beberapa library klien tidak otomatis melakukan validasi checksum pada objek yang didownload. Aplikasi Anda mungkin perlu menghitung checksum file yang didownload secara independen menggunakan byte yang diterima dan membandingkannya dengan hash yang disediakan server untuk memverifikasi integritas data.
Validasi sisi klien untuk pembacaan
Untuk melakukan pemeriksaan integritas data yang didownload, hitung checksum saat data diterima dan bandingkan hasil Anda dengan checksum yang disediakan server.
Checksum sisi server didasarkan pada objek lengkap seperti yang disimpan di Cloud Storage, yang berarti bahwa jenis download berikut tidak dapat divalidasi terhadap checksum yang disediakan server:
Download yang menjalani transkode dekompresif: checksum yang disediakan server mewakili objek dalam status terkompresi, sedangkan data yang disajikan telah dihapus kompresinya dan akibatnya memiliki nilai checksum yang berbeda.
Respons yang hanya berisi sebagian data objek: jenis respons ini terjadi untuk
Rangepermintaan.Pembacaan rentang gRPC adalah pengecualian untuk poin ini dan mendukung validasi menyeluruh. Dalam pembacaan rentang gRPC, Cloud Storage memvalidasi data dengan menyertakan checksum CRC32C unik di dalam setiap potongan respons individual dari streaming, yang memungkinkan klien Anda langsung memverifikasi bahwa blok data tertentu tidak rusak dalam pengiriman. Untuk validasi yang lebih luas, streaming juga menyediakan checksum lengkap seluruh objek, yang dapat digunakan oleh klien lanjutan untuk menghitung total bergulir dan memverifikasi integritas file yang lebih besar.
Jika aplikasi Anda perlu membaca rentang objek, bukan seluruh objek sekaligus, sebaiknya gunakan gRPC. Jika tidak, sebaiknya gunakan permintaan rentang hanya untuk memulai ulang download objek lengkap setelah offset terakhir diterima, tempat Anda dapat menghitung dan memvalidasi checksum setelah download lengkap selesai.
Saat memvalidasi download, ketidakcocokan antara checksum yang dihitung dan checksum yang disediakan server menunjukkan bahwa data rusak dalam pengiriman. Dalam kasus ini, Anda harus menghapus data yang rusak dan menggunakan logika percobaan ulang yang direkomendasikan untuk mencoba kembali permintaan.
Langkah berikutnya
- Pelajari upload objek dan download objek di Cloud Storage.
- Pelajari tentang strategi percobaan ulang untuk Cloud Storage.