Per convalidare l'integrità dei dati e rilevare le modifiche, Cloud Storage ti consiglia di utilizzare i checksum quando trasferisci dati da e verso i bucket. Questa pagina fornisce informazioni su come vengono utilizzati i checksum in Cloud Storage e su come specificarli quando invii le richieste.
Prevenire il danneggiamento dei dati utilizzando i checksum
A volte i dati possono danneggiarsi durante il trasferimento da o verso il cloud a causa di bug software o hardware, errori di memoria o router, disturbi elettrici o modifiche ai dati di origine durante i caricamenti di file di lunga durata.
Per proteggerti dal danneggiamento dei dati, Cloud Storage supporta l' utilizzo dei checksum CRC32C e MD5 per verificare l'integrità dei dati e rilevare le modifiche.
CRC32C è il metodo di convalida consigliato per eseguire i controlli di integrità. La convalida tramite hash MD5 è supportata per i caricamenti di singoli file, ma non è supportata per gli oggetti caricati in blocchi, come gli oggetti compositi e gli oggetti caricati utilizzando un caricamento in più parti dell'API XML.
Checksum per le scritture di dati
Per le scritture di oggetti, il client calcola il checksum del file locale e lo allega alle intestazioni HTTP della richiesta di caricamento dell'oggetto. Il server
riceve il payload dei dati, calcola il proprio checksum e
convalida i dati confrontando entrambi i checksum al termine del caricamento.
Se i checksum corrispondono, l'oggetto viene archiviato in Cloud Storage insieme ai relativi checksum. Se i checksum non corrispondono, la richiesta di scrittura viene rifiutata con un errore BadRequestException: 400.
Convalida lato server per le scritture di dati
Cloud Storage esegue la convalida lato server nei seguenti casi:
Quando fornisci l'hash MD5 o CRC32C di un oggetto in una richiesta di caricamento dell'oggetto. Per scoprire di più sui tipi di caricamenti di oggetti, vedi Caricamenti di oggetti.
Quando esegui una richiesta di copia o riscrittura in Cloud Storage. Per le richieste di copia e riscrittura di oggetti, Cloud Storage esegue automaticamente la convalida lato server in base a un checksum non modificabile archiviato con l'oggetto di origine.
Caricamenti (media) di singole richieste dell'API JSON
Per i caricamenti di contenuti multimediali dell'API JSON, puoi specificare i checksum nell'intestazione X-Goog-Hash della richiesta. Ad esempio:
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"Caricamenti in più parti dell'API JSON
Per i caricamenti in più parti dell'API JSON, puoi specificare i checksum come parte del container della richiesta, nella sezione dei metadati dell'oggetto o in una stringa di terzo limite. Per informazioni dettagliate sulla struttura JSON e sulle chiavi valide di un oggetto, consulta la rappresentazione della risorsa Objects.
L'esempio seguente specifica un checksum CRC32C nella parte dei metadati dell'oggetto di un container della richiesta:
--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--
L'esempio seguente specifica un checksum CRC32C nella stringa di terzo limite di un container della richiesta:
--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--
Caricamenti ripristinabili dell'API JSON
Per i caricamenti ripristinabili dell'API JSON, puoi specificare i checksum nell'intestazione X-Goog-Hash della richiesta finale che completa il caricamento. Ad esempio:
curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Content-Length: 2000000" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"SESSION_URI"Il checksum specificato nella richiesta finale viene calcolato sull'intero oggetto, non solo sui dati dell'oggetto nella richiesta finale.
Caricamenti di singole richieste dell'API XML
Per i caricamenti di singole richieste dell'API XML, puoi specificare i checksum nell'
x-goog-hashintestazione della richiesta.
Ad esempio:
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"I caricamenti di singole richieste dell'API XML accettano anche l'intestazione HTTP standard Content-MD5. Per maggiori dettagli, consulta la specifica Content-MD5.
Caricamenti in più parti dell'API XML
Per i caricamenti in più parti dell'API XML, puoi specificare un checksum per ogni singola parte di caricamento. Per specificare un checksum individuale per una parte di caricamento, includi l'
x-goog-hash intestazione nella richiesta per quella parte specifica.
Ad esempio:
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==
Per verificare l'integrità dei caricamenti in più parti dell'API XML è possibile utilizzare solo i checksum CRC32C. I checksum MD5 non sono supportati.
Caricamenti gRPC
Quando carichi oggetti utilizzando gRPC, puoi specificare i checksum a livello di oggetto
nel primo o nell'ultimo messaggio WriteObject di qualsiasi richiesta di caricamento, sia che si tratti di un
caricamento singolo o di un caricamento ripristinabile.
Inoltre, gRPC supporta i checksum per messaggio. Ogni messaggio WriteObject contiene blocchi di dati fino a 2 MiB e ogni blocco può includere il proprio checksum. Puoi specificare i checksum per messaggio al posto di o insieme a un checksum a livello di oggetto.
Caricamenti compositi paralleli
Nel caso di caricamenti compositi paralleli, devi eseguire un controllo di integrità per ogni caricamento dei componenti e poi utilizzare le precondizioni con la richiesta di composizione del caricamento per proteggerti dalle condizioni di competizione. Le richieste di composizione non vengono convalidate lato server, quindi devi eseguire la convalida lato client sul nuovo oggetto composito se vuoi un controllo di integrità end-to-end.
Copie e riscritture di Google Cloud CLI
In gcloud CLI, i dati copiati da o verso un
bucket Cloud Storage vengono convalidati automaticamente. Per i comandi cp, mv e rsync, gcloud CLI utilizza i checksum MD5 o CRC32C per determinare se esiste una differenza tra la versione di un oggetto trovata nell'origine e la versione trovata nella destinazione. Se il checksum dei dati di origine non corrisponde al checksum dei dati di destinazione, gcloud CLI elimina la copia non valida e stampa un messaggio di avviso.
Questo accade molto raramente. In questo caso, devi riprovare a eseguire l'operazione.
Questa convalida automatica si verifica dopo che l'oggetto è stato finalizzato e gli oggetti non validi sono visibili per 1-3 secondi prima di essere identificati ed eliminati. Inoltre, gcloud CLI potrebbe essere interrotto dopo il completamento del caricamento, ma prima di eseguire la convalida, lasciando l'oggetto non valido al suo posto. Questi problemi possono essere evitati quando carichi
singoli file in Cloud Storage utilizzando la convalida lato server,
che si verifica quando utilizzi il flag --content-md5 per specificare un hash MD5.
Google Cloud CLI ignora il flag --content-md5 per gli oggetti che non hanno un hash MD5.
Rilevamento delle modifiche per rsync
Il comando gcloud storage rsync confronta i checksum nei seguenti
scenari per determinare se saltare un trasferimento:
L'origine e la destinazione sono entrambi bucket Cloud Storage e l'oggetto ha un checksum MD5 o CRC32C in entrambi i bucket.
L'oggetto non ha un orario di modifica del file (
mtime) nell'origine o nella destinazione.
Nei casi in cui un oggetto ha un valore mtime sia nell'origine sia nella destinazione, ad esempio quando l'origine e la destinazione sono file system, il comando rsync confronta le dimensioni e il valore mtime degli oggetti anziché utilizzare i checksum. Allo stesso modo, se l'origine è un bucket e la destinazione è un file system locale, il comando rsync utilizza l'ora di creazione dell'oggetto di origine come sostituto di mtime e non utilizza i checksum.
Se non sono disponibili né mtime né checksum, rsync confronta solo le dimensioni dei file per determinare se esiste una modifica tra la versione di origine di un oggetto e la versione di destinazione. Ad esempio, non sono disponibili né mtime né checksum quando si confrontano oggetti compositi con oggetti di un provider di servizi cloud che non supporta CRC32C, perché gli oggetti compositi non hanno checksum MD5.
Convalida lato client per le scritture di dati
Puoi eseguire la convalida lato client dei caricamenti inviando una richiesta per i metadati dell'oggetto caricato, confrontando il valore hash dell'oggetto caricato con il valore previsto ed eliminando l'oggetto in caso di mancata corrispondenza. Questo metodo è utile se l'hash MD5 o CRC32C dell'oggetto non è noto all'inizio del caricamento.
La tabella seguente contiene la versione minima di ogni client Cloud Storage che supporta i checksum di scrittura degli oggetti.
| Client | Versione che supporta i checksum di scrittura degli oggetti |
|---|---|
| Libreria client C++ di Cloud Storage | 2.46 e versioni successive |
| Libreria client Go di Cloud Storage | 1.60.0 e versioni successive |
| Libreria client Java di Cloud Storage | 2.62 e versioni successive |
| Libreria client Node.js di Cloud Storage | 7.19.0 e versioni successive |
| Libreria client PHP di Cloud Storage | 1.51.0 e versioni successive |
| Libreria client Python di Cloud Storage | 3.7.0 e versioni successive |
| Libreria client Ruby di Cloud Storage | 1.60.0 |
| Libreria client .NET di Cloud Storage | 2.3.0 e versioni successive. Ti consigliamo di utilizzare la versione 4.15.0, che fornisce la convalida dei checksum lato server. |
| Connettore Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 e versioni successive |
| Google Cloud CLI |
Checksum per le letture e i download di dati
Per le letture e i download di oggetti, il server invia l'oggetto insieme al checksum memorizzato nella risposta. Il client calcola il proprio checksum del file letto o scaricato in base ai byte ricevuti e confronta i due checksum per verificare l'integrità dei dati.
Convalida lato client per letture e download
Per impostazione predefinita, tutti gli SDK delle librerie client di Cloud Storage supportano il calcolo dei checksum per i download e le letture degli oggetti. La tabella seguente contiene informazioni su come disattivare i checksum di lettura o download degli oggetti per ogni SDK della libreria client.
| Libreria client | Istruzioni per disattivare i checksum di lettura o download degli oggetti |
|---|---|
| Libreria client C++ di Cloud Storage | Nella libreria client C++, disattiva la verifica dei checksum impostando DownloadChecksumValidationOption sul valore
ChecksumAlgorithm::kNone. |
| Libreria client Go di Cloud Storage | Nella libreria client Go, disattiva la verifica dei checksum fornendo le opzioni del lettore durante l'inizializzazione. Passa
WithDisableReaderChecksum() quando chiami
NewReader o passa WithDisableMRDReadChecksum()
quando chiami NewMultiRangeDownloader. |
| Libreria client Java di Cloud Storage | Per disattivare la convalida interna dei checksum CRC32C sui percorsi di lettura nella
libreria client Java, passa la proprietà di sistema JVM
-Dcom.google.cloud.storage.Hasher.read=disabled, che disattiva
l'hashing interno per le letture. Se vuoi disattivare il checksum
a livello globale sia per le letture sia per le scritture, utilizza
-Dcom.google.cloud.storage.Hasher.default=disabled invece.
|
| Libreria client Node.js di Cloud Storage | Nella libreria client Node.js, disattiva la convalida dei checksum passando { validation: false } all'interno dell'oggetto delle opzioni di configurazione fornito alle chiamate al metodo di download. |
| Libreria client PHP di Cloud Storage | Nella libreria client PHP, disattiva la convalida dei checksum sui percorsi di lettura delle API JSON e API XML passando 'validate' => false o
'validate' => 'none' all'interno dell'array di opzioni associative
($options['validate']) quando chiami i metodi di download. |
| Libreria client Python di Cloud Storage | Nella libreria client Python, la disattivazione della verifica dei checksum dipende
dal trasporto del client: per il client JSON, passa
checksum=None (supportato in metodi come
download_to_file), mentre per il client gRPC, imposta
enable_checksum=False. |
| Libreria client Ruby di Cloud Storage | Nella libreria client Ruby, disattiva la verifica dei checksum passando gli argomenti delle parole chiave (checksum: o verify:) direttamente ai metodi di download, in particolare impostando verify: none o verify: false. |
| Libreria client .NET di Cloud Storage | Nella libreria client .NET, disattiva la verifica dei checksum impostando la proprietà ChecksumValidation su DownloadValidationMode.Never nell'oggetto DownloadObjectOptions passato alle chiamate dei metodi di download. |
Eseguire controlli di integrità dei dati sugli oggetti scaricati o letti
In alcuni casi, l'applicazione potrebbe dover calcolare in modo indipendente il checksum del file scaricato o letto utilizzando i byte ricevuti e confrontarlo con l'hash fornito dal server per verificare l'integrità dei dati.
Per eseguire un controllo di integrità dei dati scaricati, calcola il checksum durante la ricezione dei dati e confronta i risultati con il checksum fornito dal server.
I checksum lato server si basano sull'oggetto completo così come è archiviato in Cloud Storage, il che significa che i seguenti tipi di download non possono essere convalidati rispetto ai checksum forniti dal server:
Download sottoposti a transcodifica decompressiva: il checksum fornito dal server rappresenta l'oggetto nel suo stato compresso, mentre i dati pubblicati hanno la compressione rimossa e di conseguenza hanno un valore di checksum diverso.
Una risposta che contiene solo una parte dei dati dell'oggetto: questo tipo di risposta si verifica per le richieste
Range.Le letture a intervalli gRPC sono un'eccezione a questo punto e supportano la convalida end-to-end. Nelle letture a intervalli gRPC, Cloud Storage convalida i dati includendo un checksum CRC32C univoco all'interno di ogni singolo blocco di risposta di uno stream, il che consente al client di verificare immediatamente che il blocco di dati specifico non sia stato danneggiato durante il transito. Per una convalida più ampia, lo stream fornisce anche il checksum completo dell'intero oggetto, che i client avanzati possono utilizzare per calcolare un totale cumulativo e verificare l'integrità del file più grande.
Se l'applicazione deve leggere gli intervalli di oggetti anziché gli oggetti completi contemporaneamente, ti consigliamo di utilizzare gRPC. In caso contrario, ti consigliamo di utilizzare le richieste a intervalli solo per riavviare il download di un oggetto completo dopo l'ultimo offset ricevuto, dove puoi calcolare e convalidare il checksum al termine del download completo.
Quando convalidi il download, una mancata corrispondenza tra il checksum calcolato e il checksum fornito dal server indica che i dati sono stati danneggiati durante il transito. In questi casi, devi eliminare i dati danneggiati e utilizzare la logica di ripetizione consigliata per riprovare a inviare la richiesta.
Passaggi successivi
- Scopri di più sui caricamenti di oggetti e sui download di oggetti in Cloud Storage.
- Scopri di più sulle strategie di ripetizione per Cloud Storage.