Hash ed ETag: best practice

Cloud Storage ti incoraggia a convalidare i dati che trasferisci da/verso i tuoi bucket. In questa pagina vengono descritte le best practice per l'esecuzione delle convalide utilizzando checksum CRC32C o MD5.

Proteggiti dal danneggiamento dei dati usando 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 del software (ad es. in una libreria utilizzata dai clienti)
  • Modifiche al file di origine quando viene eseguito un caricamento per un periodo di tempo prolungato

Cloud Storage supporta due tipi di hash che puoi usare 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 compositi o per gli oggetti creati da un caricamento multiparte dell'API XML.

CRC32C

Tutti gli oggetti di 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 controllare l'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 tranne 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à di download può essere eseguito eseguendo l'hashing dei dati scaricati in tempo reale e confrontando i risultati con hash forniti dal server. Devi ignorare i dati scaricati con valori hash non corretti e utilizzare una logica di nuovo tentativo 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 si fornisce 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 loro 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 race condizioni in cui processi indipendenti eliminano o sostituiscono i dati degli altri, utilizza le generazioni e le precondizioni degli oggetti.

Nel caso di 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 scrittura per proteggersi dalle condizioni di gara. La composizione degli oggetti non offre alcuna convalida MD5 lato server, di conseguenza 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 codificati in 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 di presumere che ciò accada, poiché alcuni oggetti utilizzano valori ETag opachi che non garantiscono alcuna garanzia al di fuori della 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, MD5 può essere fornito utilizzando l'intestazione Content-MD5 HTTP standard (consulta la specifica).

API JSON

Nell'API JSON, le proprietà della risorsa degli oggetti md5Hash e crc32c contengono rispettivamente hash MD5 e CRC32C con codifica base64. La specifica della proprietà dei metadati è facoltativa. La fornitura di una delle due proprietà come parte di un caricamento ripristinabile o di un caricamento multiparte dell'API JSON attiva la convalida lato server del nuovo oggetto. Se Cloud Storage calcola per una delle due proprietà un valore 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. 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 visualizza un messaggio di avviso. Questo accade molto raramente. In caso affermativo, dovrai ripetere l'operazione.

Questa convalida automatica avviene dopo che l'oggetto stesso è stato finalizzato, quindi gli oggetti non validi sono visibili per 1-3 secondi prima di essere identificati ed eliminati. Inoltre, è possibile che gcloud CLI possa essere interrotto dopo il completamento del caricamento, ma prima che esegua la convalida, lasciando l'oggetto non valido. Questi problemi possono essere evitati durante il caricamento di singoli file in Cloud Storage utilizzando la convalida lato server, che si verifica quando viene utilizzato il flag --content-md5=MD5.

Passaggi successivi