Validasi data dan deteksi perubahan dengan checksum

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 bersama dengan 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 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 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 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 diselesaikan dan objek yang tidak valid 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 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
  • 3.0.18 dan yang lebih baru untuk konektor Cloud Storage 3.0.x
  • 3.1.14 dan yang lebih baru untuk konektor Cloud Storage 3.1.x
  • 4.0.3 dan yang lebih baru untuk konektor Cloud Storage 4.0.x
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 mengirim objek beserta checksum yang disimpan dalam respons. Klien menghitung checksum-nya sendiri dari file yang dibaca atau didownload berdasarkan byte yang diterima dan membandingkan kedua 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 checksum download atau pembacaan objek untuk setiap SDK library klien.

Library klien Petunjuk tentang cara menonaktifkan checksum pembacaan 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 pada jalur baca di library klien Java, teruskan properti sistem JVM -Dcom.google.cloud.storage.Hasher.read=disabled, yang menonaktifkan hasher internal untuk pembacaan. Jika Anda ingin menonaktifkan checksum secara global di seluruh pembacaan dan penulisan, 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 menetapkan 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 dengan 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 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 Range permintaan.

    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 aliran, yang memungkinkan klien Anda langsung memverifikasi bahwa blok data tertentu tidak rusak dalam pengiriman. Untuk validasi yang lebih luas, aliran ini 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