Untuk memvalidasi integritas data dan mendeteksi perubahan, Cloud Storage menyarankan Anda untuk menggunakan checksum saat mentransfer data ke dan dari bucket Anda. 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 berdurasi panjang.
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.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
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 divalidasi secara otomatis. 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 diselesaikan 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 suatu 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 berisi versi minimum setiap klien Cloud Storage yang mendukung checksum penulisan objek.
| Klien | Versi yang mendukung checksum penulisan objek |
|---|---|
| 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 dan download data
Untuk pembacaan dan download objek, server mengirimkan objek beserta checksum yang tersimpan dalam respons. Klien menghitung checksumnya sendiri dari file yang dibaca atau didownload berdasarkan byte yang diterimanya dan membandingkan dua checksum untuk memverifikasi integritas data.
Validasi sisi klien untuk pembacaan dan download
Secara default, semua SDK library klien Cloud Storage mendukung penghitungan checksum untuk download dan pembacaan objek. Tabel berikut berisi informasi tentang cara menonaktifkan download objek atau membaca checksum untuk setiap SDK library klien.
| Library klien | Petunjuk tentang cara menonaktifkan checksum baca atau download objek |
|---|---|
| Library klien C++ Cloud Storage | Di library klien C++, Anda menonaktifkan verifikasi checksum dengan
menetapkan DownloadChecksumValidationOption ke nilai
ChecksumAlgorithm::kNone. |
| Library klien Go Cloud Storage | Di library klien Go, Anda menonaktifkan verifikasi checksum dengan
memberikan opsi pembaca saat inisialisasi. Teruskan
WithDisableReaderChecksum() saat memanggil
NewReader atau teruskan WithDisableMRDReadChecksum()
saat memanggil NewMultiRangeDownloader. |
| Library klien Java Cloud Storage | Untuk menonaktifkan validasi checksum CRC32C internal di jalur baca di
library klien Java, teruskan properti sistem JVM
-Dcom.google.cloud.storage.Hasher.read=disabled, yang akan menonaktifkan
hasher internal untuk baca. Jika Anda ingin menonaktifkan checksum secara global di seluruh operasi baca dan tulis, gunakan -Dcom.google.cloud.storage.Hasher.default=disabled sebagai gantinya.
|
| Library klien Node.js Cloud Storage | Di library klien Node.js, Anda menonaktifkan validasi checksum dengan
meneruskan { validation: false } dalam objek opsi konfigurasi
yang diberikan ke panggilan metode download. |
| Library klien PHP Cloud Storage | Di library klien PHP, Anda menonaktifkan validasi checksum di seluruh jalur baca JSON dan XML API dengan meneruskan 'validate' => false atau 'validate' => 'none' di dalam array opsi asosiatif ($options['validate']) saat memanggil metode download. |
| Library klien Python Cloud Storage | Di library klien Python, menonaktifkan verifikasi checksum bergantung
pada transportasi klien: untuk klien JSON, teruskan
checksum=None (didukung dalam metode seperti
download_to_file), sedangkan untuk klien gRPC, tetapkan
enable_checksum=False. |
| Library klien Ruby Cloud Storage | Di library klien Ruby, Anda menonaktifkan verifikasi checksum dengan
meneruskan argumen kata kunci (checksum: atau verify:)
langsung ke metode download, khususnya menyetel
verify: none atau verify: false. |
| Library klien .NET Cloud Storage | Di library klien .NET, Anda menonaktifkan verifikasi checksum dengan
menetapkan properti ChecksumValidation ke
DownloadValidationMode.Never pada
objek DownloadObjectOptions yang diteruskan ke panggilan
metode download. |
Melakukan pemeriksaan integritas data pada objek yang didownload atau dibaca
Dalam beberapa kasus, aplikasi Anda mungkin perlu menghitung checksum file yang didownload atau dibaca secara independen menggunakan byte yang diterima dan membandingkannya dengan hash yang disediakan server untuk memverifikasi integritas data.
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 dekompresi: 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 potongan respons individual dari aliran, yang memungkinkan klien Anda langsung memverifikasi bahwa blok data tertentu tidak rusak saat transit. Untuk validasi yang lebih luas, stream juga menyediakan checksum lengkap seluruh objek, yang dapat digunakan oleh klien tingkat lanjut untuk menghitung total bergulir 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 berjangkauan 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 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.