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 dengan 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 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./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 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
header x-goog-hash 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 untuk setiap bagian
upload. Untuk menentukan checksum individual untuk bagian upload, sertakan
header x-goog-hash 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 sekali kirim atau 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 penulisan upload untuk melindungi dari kondisi race. Permintaan komposisi tidak mendapatkan validasi sisi server, jadi Anda harus melakukan validasi sisi klien pada objek gabungan baru jika Anda 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 pada tempatnya. 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 transfer harus dilewati:
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.
Dalam kasus ketika 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 menggunakan waktu pembuatan untuk objek
sumber sebagai pengganti mtime, dan perintah tidak menggunakan checksum.
Jika mtime maupun checksum tidak tersedia, rsync hanya membandingkan ukuran file
saat menentukan apakah ada perubahan antara versi sumber objek
dan versi tujuan. Misalnya, mtime maupun 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 |
| Library klien .NET Cloud Storage | 2.3.0 dan yang lebih baru. Sebaiknya gunakan 4.15.0, yang menyediakan validasi checksum sisi server. |
| 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 checksumnya sendiri dari file yang didownload berdasarkan byte yang diterimanya 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 transcoding dekompresif: checksum yang disediakan server merepresentasikan objek dalam status terkompresi, sedangkan kompresi data yang disajikan telah dihapus sehingga nilai checksum-nya berbeda.
Respons yang hanya berisi sebagian data objek: jenis respons ini terjadi untuk permintaan
Range.Pembacaan rentang gRPC adalah pengecualian untuk poin ini dan mendukung validasi end-to-end. Dalam pembacaan rentang gRPC, Cloud Storage memvalidasi data dengan menyertakan checksum CRC32C unik di dalam setiap bagian respons individual dari aliran, yang memungkinkan klien Anda langsung memverifikasi bahwa blok data tertentu tidak rusak dalam transit. Untuk validasi yang lebih luas, stream juga menyediakan checksum lengkap seluruh objek, yang dapat digunakan oleh klien tingkat lanjut untuk menghitung total berjalan dan memverifikasi integritas file yang lebih besar.
Jika aplikasi Anda perlu membaca rentang objek, bukan objek lengkap sekaligus, sebaiknya gunakan gRPC. Jika tidak, sebaiknya gunakan permintaan rentang hanya untuk memulai ulang download objek lengkap setelah offset terakhir diterima, di mana Anda dapat menghitung dan memvalidasi checksum setelah download lengkap selesai.
Saat memvalidasi download Anda, ketidakcocokan antara checksum yang dihitung dan checksum yang disediakan server menunjukkan bahwa data rusak saat dalam pengiriman. Dalam kasus ini, Anda harus menghapus data yang rusak dan menggunakan logika percobaan ulang yang direkomendasikan untuk mencoba ulang permintaan.
Langkah berikutnya
- Pelajari upload objek dan download objek di Cloud Storage.
- Pelajari strategi percobaan ulang untuk Cloud Storage.