Per convalidare l'integrità dei dati e rilevare le modifiche, Cloud Storage ti consiglia di utilizzare i checksum quando trasferisci i 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 composti 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 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, consulta 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 (multimediali) con singola richiesta dell'API JSON
Per i caricamenti 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 multiparte dell'API JSON
Per i caricamenti multiparte dell'API JSON, puoi specificare i checksum come parte del container 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 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 terza stringa di delimitazione 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 con singola richiesta dell'API XML
Per i caricamenti con singola richiesta 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 con singola richiesta dell'API XML accettano anche l'intestazione HTTP standard Content-MD5. Per maggiori dettagli, consulta la specifica Content-MD5.
Caricamenti multiparte dell'API XML
Per i caricamenti multiparte 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 multiparte 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 che 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 composti paralleli
Nel caso di caricamenti composti 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 composto 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'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 il comando non utilizza i checksum.
Se non sono disponibili né mtime né i 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, né mtime né i checksum sono
disponibili quando si confrontano oggetti composti con oggetti di un provider di servizi cloud
che non supporta CRC32C, perché gli oggetti composti 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 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 di 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 sugli 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 di 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 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 la tua 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.