Convalida dei dati e rilevamento delle modifiche con checksum

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 invii richieste.

Evita 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 dalla corruzione dei dati, Cloud Storage supporta l'utilizzo di checksum CRC32C e MD5 per verificare l'integrità dei dati e rilevare le modifiche apportate.

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 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 scoprire di più sui tipi di caricamento 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 di singole richieste (media) 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 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 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 in base all'intero oggetto, non solo ai dati dell'oggetto nella richiesta finale.

Caricamenti con singola richiesta 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 HTTP standard Content-MD5. Per maggiori dettagli, consulta la specifica Content-MD5.

Caricamenti multiparte dell'API XML

Per i caricamenti in più parti dell'API XML, puoi specificare un checksum 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 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 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

Nella gcloud CLI, 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. Ciò accade molto raramente. In questo caso, riprova 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 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 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 tabella seguente contiene la versione minima di ogni client Cloud Storage che supporta i checksum di scrittura degli oggetti.

Checksum per letture e download di dati

Per le letture e i download di oggetti, il server invia l'oggetto insieme al relativo 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 seguente tabella contiene informazioni su come disattivare il download di oggetti o leggere i checksum per ogni SDK della libreria client.

Esecuzione di 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 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 non sono compressi 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 in 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 il checksum 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 dei tentativi per Cloud Storage.