Per convalidare l'integrità dei dati e rilevare le modifiche, Cloud Storage ti consiglia di utilizzare i checksum durante il trasferimento dei dati da e verso i bucket. Questa pagina fornisce informazioni su come vengono utilizzati i checksum in Cloud Storage e su come specificarli quando si inviano richieste.
Evitare 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 del 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 di 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 multiparte 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 di 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 informazioni sui tipi di caricamenti di oggetti, consulta Caricamenti di oggetti.
Quando esegui una richiesta di copia o riscrittura in Cloud Storage. Per le richieste di copia e riscrittura degli oggetti, Cloud Storage esegue automaticamente la convalida lato server in base a un checksum non modificabile archiviato con l'oggetto di origine.
Caricamenti API JSON a richiesta singola (media)
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 contenitore della richiesta, nella sezione dei metadati dell'oggetto o in una stringa di delimitazione di terze parti. Per informazioni dettagliate sulla struttura JSON e sulle chiavi valide di un oggetto, consulta la rappresentazione della risorsa Oggetti.
L'esempio seguente specifica un checksum CRC32C nella parte dei metadati dell'oggetto di un contenitore di richieste:
--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 terza stringa di delimitazione di un contenitore di richieste:
--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 per 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 in base all'intero oggetto, non solo ai dati dell'oggetto nella richiesta finale.
Caricamenti con singola richiesta dell'API XML
Per i caricamenti di singole richieste dell'API XML, puoi specificare i checksum nell'intestazione x-goog-hash 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 con singola richiesta dell'API XML accettano anche l'intestazione Content-MD5 HTTP standard. Per maggiori dettagli, consulta la specifica Content-MD5.
Caricamenti multiparte dell'API XML
Per i caricamenti multiparte dell'API XML, puoi specificare un checksum CRC32C per l'intero oggetto o un checksum individuale per ogni parte del caricamento. Per specificare un checksum
individuale per una parte del caricamento, includi l'intestazione x-goog-hash 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==
Solo i checksum CRC32C possono essere utilizzati per verificare l'integrità dei caricamenti in più parti dell'API XML. 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, 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 paralleli composti
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 race condition. Le richieste di composizione non vengono convalidate lato server, pertanto devi eseguire la convalida lato client sul nuovo oggetto composito se vuoi un controllo di integrità end-to-end.
Google Cloud CLI copia e riscrive
Nell'interfaccia a riga di comando gcloud, i dati copiati in o da 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 quella trovata nella destinazione. Se il checksum dei dati di origine non corrisponde a quello dei dati di destinazione, la gcloud CLI elimina la copia non valida e stampa un messaggio di avviso.
Questo accade molto raramente. In questo caso, dovresti riprovare a eseguire l'operazione.
Questa convalida automatica si verifica dopo la finalizzazione dell'oggetto e
gli oggetti non validi sono visibili per 1-3 secondi prima di essere identificati ed
eliminati. Inoltre, gcloud CLI potrebbe
interrompersi dopo il completamento del caricamento, ma prima di eseguire la convalida,
lasciando l'oggetto non valido al suo posto. Questi problemi possono essere evitati durante il caricamento di 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'ora di modifica del file (
mtime) nell'origine o nella destinazione.
Nei casi in cui un oggetto ha un valore mtime sia nell'origine che 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 differenza tra la versione di origine di un oggetto
e la versione di destinazione. Ad esempio, né mtime né i checksum sono
disponibili quando si confrontano oggetti compositi con oggetti di un provider 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 seguente tabella mostra i client in Cloud Storage che supportano il calcolo dei checksum per le scritture di oggetti per impostazione predefinita, incluse le versioni dei client che supportano i checksum.
| Client | Versioni che supportano i checksum |
|---|---|
| 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 |
| Connettore Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 e versioni successive |
| Google Cloud CLI |
Checksum per le letture dei dati
Per i download di oggetti, il server invia l'oggetto insieme al checksum memorizzato nella risposta. Il client calcola il proprio checksum del file scaricato in base ai byte ricevuti e confronta i due checksum per verificare l'integrità dei dati.
Alcune librerie client non eseguono automaticamente la convalida del checksum degli oggetti scaricati. La tua applicazione potrebbe dover calcolare in modo indipendente il checksum del file scaricato utilizzando i byte ricevuti e confrontarlo con l'hash fornito dal server per verificare l'integrità dei dati.
Convalida lato client per le letture
Per eseguire un controllo dell'integrità dei dati scaricati, calcola il checksum man mano che i dati vengono ricevuti 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 sono stati decompressi 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 con intervallo gRPC fanno eccezione a questo punto elenco e supportano la convalida end-to-end. Nelle letture con intervallo gRPC, Cloud Storage convalida i dati includendo un checksum CRC32C univoco all'interno di ogni singolo blocco di risposta di un flusso, il che consente al client di verificare immediatamente che il blocco specifico di dati non sia stato danneggiato durante il trasferimento. 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 progressivo e verificare l'integrità del file più grande.
Se la tua applicazione deve leggere intervalli di oggetti anziché oggetti completi contemporaneamente, ti consigliamo di utilizzare gRPC. In caso contrario, ti consigliamo di utilizzare richieste con intervallo solo per riavviare il download di un oggetto completo dopo l'ultimo offset ricevuto, dove puoi calcolare e convalidare il checksum dopo il completamento del download completo.
Durante la convalida del download, una mancata corrispondenza tra il checksum calcolato e quello fornito dal server indica che i dati sono stati danneggiati durante il trasferimento. 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.