Best practice per hash ed ETag

Cloud Storage incoraggia a convalidare i dati trasferiti da/verso i bucket. Questa pagina descrive le best practice per eseguire le convalide utilizzando i checksum CRC32C o MD5.

Proteggiti dal danneggiamento dei dati utilizzando hash

Esistono diversi modi in cui i dati possono essere danneggiati durante il caricamento o il download dal cloud:

  • Errori di memoria su computer client o server oppure router lungo il percorso
  • Bug software (ad es. in una libreria utilizzata dai clienti)
  • Modifiche al file di origine quando un caricamento si verifica per un periodo di tempo prolungato

Cloud Storage supporta due tipi di hash che puoi utilizzare per verificare l'integrità dei tuoi dati: CRC32C e MD5. CRC32C è il metodo di convalida consigliato per eseguire i controlli di integrità. I clienti che preferiscono MD5 possono utilizzare questo hash, ma gli hash MD5 non sono supportati per gli oggetti composti o per gli oggetti creati da un caricamento multiparte dell'API XML.

CRC32C

Tutti gli oggetti Cloud Storage hanno un hash CRC32C. Le librerie per il calcolo di CRC32C includono:

Il CRC32C codificato in Base64 è in ordine di byte big-endian.

MD5

Cloud Storage supporta un hash MD5 per gli oggetti che soddisfano i seguenti criteri:

Questo hash si applica solo a un oggetto completo, quindi non può essere utilizzato per il controllo dell'integrità dei download parziali causati dall'esecuzione di un intervallo GET.

ETags

L'intestazione ETag di un oggetto restituisce il valore MD5 dell'oggetto se tutte le seguenti condizioni sono vere:

In tutti gli altri casi, gli utenti non devono fare ipotesi sul valore utilizzato in un ETag, ad eccezione del fatto che cambia ogni volta che i dati o i metadati sottostanti cambiano, in base alla specifica.

Lo stesso oggetto può avere un valore ETag diverso quando viene richiesto dall'API XML rispetto all'API JSON.

Convalida

Un controllo dell'integrità dei download può essere eseguito eseguendo rapidamente l'hashing dei dati scaricati e confrontando i risultati con gli hash forniti dal server. Dovresti ignorare i dati scaricati con valori hash errati e utilizzare la logica per i nuovi tentativi per evitare loop infiniti potenzialmente costosi.

Cloud Storage esegue la convalida lato server nei seguenti casi:

  • Quando esegui una richiesta di copia o riscrittura in Cloud Storage.

  • Quando fornisci l'hash MD5 o CRC32C previsto di un oggetto in una richiesta di caricamento. Cloud Storage crea l'oggetto solo se l'hash fornito corrisponde al valore calcolato da Cloud Storage. Se non corrisponde, la richiesta viene rifiutata con un errore BadRequestException: 400.

In alternativa, gli utenti possono scegliere di eseguire la convalida lato client dei caricamenti inviando una richiesta per i metadati dell'oggetto caricato, confrontando il valore hash segnalato 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. Per evitare condizioni di gara in cui processi indipendenti eliminano o sostituiscono i dati degli altri, utilizza generazioni e precondizioni di oggetti.

Nel caso dei caricamenti compositi paralleli, gli utenti devono eseguire un controllo di integrità per ogni caricamento di componenti e quindi utilizzare le precondizioni dei componenti nelle richieste di composizione per proteggersi dalle condizioni di gara. La composizione dell'oggetto non offre la convalida MD5 lato server, quindi gli utenti che vogliono eseguire un controllo dell'integrità end-to-end devono applicare la convalida lato client al nuovo oggetto composito.

API XML

Nell'API XML, gli hash MD5 e CRC32C con codifica base64 vengono esposti e accettati tramite l'intestazione x-goog-hash. In passato, gli MD5 venivano utilizzati come ETag dell'oggetto, ma gli utenti dovrebbero evitare questa ipotesi poiché alcuni oggetti usano valori ETag opachi che non forniscono alcuna garanzia, a parte la modifica quando l'oggetto viene modificato.

La convalida del caricamento lato server può essere eseguita fornendo hash calcolati localmente tramite l'intestazione della richiesta x-goog-hash. Inoltre, l'MD5 può essere fornito utilizzando l'intestazione Content-MD5 HTTP standard (consulta la specifica).

API JSON

Nell'API JSON, le proprietà md5Hash e crc32c della risorsa degli oggetti contengono rispettivamente hash MD5 e CRC32C con codifica base64. La specifica della proprietà dei metadati è facoltativa. Se fornisci una proprietà come parte di un caricamento ripristinabile o di un caricamento multiparte dell'API JSON, viene attivata la convalida lato server per il nuovo oggetto. Se Cloud Storage calcola un valore per una delle proprietà che non corrisponde a un valore fornito, l'oggetto non viene creato. Se le proprietà non vengono fornite in un caricamento, Cloud Storage calcola i valori e li scrive nei metadati dell'oggetto.

Google Cloud CLI

Per Google Cloud CLI, vengono convalidati i dati copiati in o da un bucket Cloud Storage. Questo si applica ai comandi cp, mv e rsync. 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 caso affermativo, devi riprovare a eseguire l'operazione.

Questa convalida automatica avviene dopo la finalizzazione dell'oggetto stesso, quindi gli oggetti non validi restano visibili per 1-3 secondi prima di essere identificati ed eliminati. Inoltre, c'è la possibilità che gcloud CLI possa essere interrotto al termine del caricamento, ma prima di eseguire la convalida, lasciando l'oggetto non valido sul posto. Puoi evitare questi problemi durante il caricamento di singoli file in Cloud Storage utilizzando la convalida lato server, che si verifica utilizzando il flag --content-md5=MD5.

Passaggi successivi