Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui caricamenti ripristinabili

Questa pagina descrive come effettuare una richiesta di caricamento ripristinabile nelle API JSON e XML di Cloud Storage. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione interrompe il flusso di dati.

Per informazioni sull'utilizzo di caricamenti ripristinabili in Google Cloud CLI e nelle librerie client, consulta In che modo strumenti e API utilizzano caricamenti ripristinabili.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire un caricamento ripristinabile, chiedi all'amministratore di concederti uno dei seguenti ruoli:

Per i caricamenti che includono un blocco per la conservazione degli oggetti, chiedi all'amministratore di concederti il ruolo IAM Amministratore oggetti Storage (roles/storage.objectAdmin) per il bucket.
Per tutti gli altri casi, chiedi all'amministratore di concederti il ruolo IAM Utente oggetti Storage (roles/storage.objectUser) per il bucket.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per caricare un oggetto in un bucket per i rispettivi casi. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

storage.objects.create
storage.objects.delete

Questa autorizzazione è necessaria solo per i caricamenti che sovrascrivono un oggetto esistente.

storage.objects.setRetention
- Questa autorizzazione è richiesta solo per i caricamenti che includono un blocco per la conservazione degli oggetti.

Puoi ottenere queste autorizzazioni anche con altri ruoli predefiniti o ruoli personalizzati.

Per informazioni sulla concessione dei ruoli nei bucket, consulta Utilizzare IAM con i bucket.

Avvio di una sessione di caricamento ripristinabile

Per avviare una sessione di caricamento ripristinabile:

API JSON

Assicurati che gcloud CLI sia installato e inizializzato per generare un token di accesso per l'intestazione Authorization.

In alternativa, puoi creare un token di accesso utilizzando OAuth 2.0 Playground e includerlo nell'intestazione Authorization.
Se vuoi, puoi creare un file JSON contenente i metadati che vuoi impostare nell'oggetto che stai caricando. Ad esempio, il seguente file JSON imposta i metadati contentType dell'oggetto che vuoi caricare su image/png:
```
{
    "contentType": "image/png"
}
```
Utilizza cURL per chiamare l'API JSON con una richiesta POST oggetto:
```
curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "Content-Length: INITIAL_REQUEST_LENGTH" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"
```
Dove:
- METADATA_LOCATION è il percorso locale del file JSON contenente i metadati facoltativi che hai specificato nel passaggio precedente. Se non includi un file di metadati, escludi questo, insieme a --data-binary @ e all'intestazione Content-Type.
- INITIAL_REQUEST_LENGTH è il numero di byte nel corpo di questa richiesta iniziale, ad esempio 79. Non obbligatorio se utilizzi la codifica del trasferimento in blocchi.
- BUCKET_NAME è il nome del bucket in cui stai caricando l'oggetto. Ad esempio, my-bucket.
- OBJECT_NAME è il nome con codifica URL che vuoi assegnare all'oggetto. Ad esempio, pets/dog.png, con codifica URL come pets%2Fdog.png. Questa operazione non è necessaria se hai incluso un elemento name nel file di metadati dell'oggetto nel passaggio 2.
Se hai abilitato la condivisione delle risorse tra origini, devi includere anche un'intestazione Origin in questa richiesta di caricamento e in quelle successive.

Le intestazioni facoltative che puoi aggiungere alla richiesta includono X-Upload-Content-Type e X-Upload-Content-Length.

Se l'esito è positivo, la risposta include un codice di stato 200.
Salva l'URI della sessione ripristinabile specificato nell'intestazione Location della risposta alla richiesta dell'oggetto POST.

Questo URI viene utilizzato nelle richieste successive per caricare i dati dell'oggetto.

Attenzione: fai attenzione quando condividi l'URI della sessione ripristinabile, perché può essere utilizzato da chiunque per caricare dati nel bucket di destinazione senza ulteriore autenticazione.

API XML

Assicurati che gcloud CLI sia installato e inizializzato per generare un token di accesso per l'intestazione Authorization.

In alternativa, puoi creare un token di accesso utilizzando OAuth 2.0 Playground e includerlo nell'intestazione Authorization.
Utilizza cURL per chiamare l'API XML con una richiesta POST oggetto con un corpo vuoto:
```
curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
Dove:
- OBJECT_CONTENT_TYPE è il tipo di contenuti dell'oggetto. Ad esempio: image/png. Se non specifichi un tipo di contenuto, il sistema Cloud Storage imposta i metadati Content-Type per l'oggetto in modo che siano application/octet-stream.
- BUCKET_NAME è il nome del bucket in cui stai caricando l'oggetto. Ad esempio, my-bucket.
- OBJECT_NAME è il nome con codifica URL che vuoi assegnare all'oggetto. Ad esempio, pets/dog.png, con codifica URL pets%2Fdog.png.
Se hai abilitato la condivisione delle risorse tra origini, devi includere anche un'intestazione Origin in questa richiesta di caricamento e in quelle successive.

Se l'esito è positivo, la risposta include un messaggio di stato 201.
Salva l'URI della sessione ripristinabile specificato nell'intestazione Location della risposta alla richiesta dell'oggetto POST.

Questo URI viene utilizzato nelle richieste successive per caricare i dati dell'oggetto.

Attenzione: fai attenzione quando condividi l'URI della sessione ripristinabile, perché può essere utilizzato da chiunque per caricare dati nel bucket di destinazione senza ulteriore autenticazione.

Carica i dati

Una volta avviato un caricamento ripristinabile, i dati dell'oggetto possono essere caricati in due modi:

In un unico blocco: questo approccio è in genere l'ideale, poiché richiede meno richieste e quindi ha prestazioni migliori.
In più blocchi: utilizza questo approccio se devi ridurre la quantità di dati trasferiti in una singola richiesta, ad esempio se esiste un limite di tempo fisso per le singole richieste o se non conosci le dimensioni totali del caricamento nel momento in cui inizia il caricamento.

Caricamento di un singolo blocco

Per caricare i dati in un unico blocco:

API JSON

Utilizza cURL per chiamare l'API JSON con una richiesta di oggetto PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- OBJECT_LOCATION è il percorso locale dell'oggetto. Ad esempio, Desktop/dog.png.
- OBJECT_SIZE è il numero di byte nell'oggetto. Ad esempio, 20000000.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.
Se vuoi, puoi includere intestazioni precedute da X-Goog-Meta- per aggiungere metadati personalizzati per l'oggetto nell'ambito di questa richiesta.

API XML

Utilizza cURL per chiamare l'API XML con una richiesta di oggetto PUT:
```
curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- OBJECT_LOCATION è il percorso locale dell'oggetto. Ad esempio, Desktop/dog.png.
- OBJECT_SIZE è il numero di byte nell'oggetto. Ad esempio, 20000000.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

Se il caricamento viene completato completamente, riceverai una risposta 200 OK o 201 Created, insieme agli eventuali metadati associati alla risorsa.

Se la richiesta di caricamento viene interrotta o se ricevi una risposta 5xx, segui la procedura descritta in Riprendere un caricamento interrotto.

Caricamento di più blocchi

Per caricare i dati in più blocchi:

API JSON

Crea un blocco di dati dai dati complessivi che vuoi caricare.

La dimensione del blocco deve essere un multiplo di 256 KiB (256 x 1024 byte), a meno che non sia l'ultimo blocco a completare il caricamento. I blocchi di dimensioni maggiori in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e utilizzo della memoria. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del blocco.
Utilizza cURL per chiamare l'API JSON con una richiesta di oggetto PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- CHUNK_LOCATION è il percorso locale del blocco che stai caricando attualmente.
- CHUNK_SIZE è il numero di byte che stai caricando nella richiesta corrente. Ad esempio, 8388608.
- CHUNK_FIRST_BYTE è il byte iniziale dell'oggetto complessivo contenuto nel blocco che stai caricando.
- CHUNK_LAST_BYTE è il byte finale dell'oggetto complessivo contenuto nel blocco che stai caricando.
- TOTAL_OBJECT_SIZE è la dimensione totale dell'oggetto che stai caricando.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.
Un esempio di Content-Range è Content-Range: bytes 0-8388607/20000000. Per saperne di più su questa intestazione, consulta Content-Range.

Se la richiesta ha esito positivo, il server risponde con 308 Resume Incomplete. La risposta contiene un'intestazione Range.
Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi caricare, utilizzando il valore più alto contenuto nell'intestazione Range di ogni risposta per determinare da dove iniziare ogni blocco successivo. Non devi presumere che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.

Facoltativamente, nella richiesta finale del caricamento ripristinabile puoi includere intestazioni precedute da X-Goog-Meta- per aggiungere metadati personalizzati per l'oggetto.

API XML

Crea un blocco di dati dai dati complessivi che vuoi caricare.

La dimensione del blocco deve essere un multiplo di 256 KiB (256 x 1024 byte), a meno che non sia l'ultimo blocco a completare il caricamento. I blocchi di dimensioni maggiori in genere velocizzano i caricamenti, ma tieni presente che c'è un compromesso tra velocità e utilizzo della memoria. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del blocco.
Utilizza cURL per chiamare l'API XML con una richiesta di oggetto PUT:
```
curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- CHUNK_LOCATION è il percorso locale del blocco che stai caricando attualmente.
- CHUNK_SIZE è il numero di byte che stai caricando nella richiesta corrente. Ad esempio, 8388608.
- CHUNK_FIRST_BYTE è il byte iniziale dell'oggetto complessivo contenuto nel blocco che stai caricando.
- CHUNK_LAST_BYTE è il byte finale dell'oggetto complessivo contenuto nel blocco che stai caricando.
- TOTAL_OBJECT_SIZE è la dimensione totale dell'oggetto che stai caricando.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.
Un esempio di Content-Range è Content-Range: bytes 0-8388607/20000000. Per saperne di più su questa intestazione, consulta Content-Range.

Se la richiesta ha esito positivo, il server risponde con 308 Resume Incomplete. La risposta contiene un'intestazione Range.
Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi caricare, utilizzando il valore più alto contenuto nell'intestazione Range di ogni risposta per determinare da dove iniziare ogni blocco successivo. Non devi presumere che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.

Al termine del caricamento, riceverai una risposta 200 OK o 201 Created, insieme a tutti i metadati associati alla risorsa.

Se i caricamenti di blocchi vengono interrotti o se ricevi una risposta 5xx, devi inviare nuovamente il blocco interrotto completamente o riprendere il caricamento interrotto dal punto in cui era stato interrotto.

Controllare lo stato di un caricamento ripristinabile

Se il tuo caricamento ripristinabile viene interrotto o non hai la certezza che il caricamento sia stato completato, puoi controllare lo stato del caricamento:

API JSON

Utilizza cURL per chiamare l'API JSON con una richiesta di oggetto PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- OBJECT_SIZE è il numero totale di byte nell'oggetto. Se non conosci le dimensioni complete dell'oggetto, utilizza * per questo valore.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

API XML

Utilizza cURL per chiamare l'API XML con una richiesta di oggetto PUT:
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- OBJECT_SIZE è il numero totale di byte nell'oggetto. Se non conosci le dimensioni complete dell'oggetto, utilizza * per questo valore.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

Una risposta 200 OK o 201 Created indica che il caricamento è stato completato e non sono necessarie ulteriori azioni.

Una risposta 308 Resume Incomplete indica che devi continuare a caricare i dati.

Se Cloud Storage non ha ancora mantenuto alcun byte, la risposta 308 non ha un'intestazione Range. In questo caso, dovresti iniziare il caricamento dall'inizio.
In caso contrario, la risposta 308 ha un'intestazione Range, che specifica i byte mantenuti finora da Cloud Storage. Utilizza questo valore quando riprendi un caricamento interrotto.

Riprendere un caricamento interrotto

Se una richiesta di caricamento viene terminata prima di ricevere una risposta o se ricevi una risposta 503 o 500, devi riprendere il caricamento interrotto dal punto in cui è stato interrotto. Per riprendere un caricamento interrotto:

API JSON

Controlla lo stato del caricamento ripristinabile.
Salva il valore più alto dell'intestazione Range contenuta nella risposta al controllo dello stato. Se la risposta non ha un'intestazione Range, Cloud Storage non ha ancora mantenuto alcun byte e dovresti eseguire il caricamento dall'inizio.
Assicurati che i dati oggetto che stai per caricare inizino a partire dal byte che segue il valore più alto nell'intestazione Range.
Se la richiesta interrotta conteneva intestazioni con prefisso X-Goog-Meta-, includile nella richiesta per riprendere il caricamento.
Utilizza cURL per chiamare l'API JSON con una richiesta dell'oggetto PUT che viene prelevata dal byte che segue il valore nell'intestazione Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- PARTIAL_OBJECT_LOCATION è il percorso locale della parte rimanente di dati che vuoi caricare.
- UPLOAD_SIZE_REMAINING è il numero di byte che stai caricando nella richiesta attuale. Ad esempio, il caricamento del resto di un oggetto con una dimensione totale di 2.000.0000 interrotta dopo i byte da 0 a 42 caricati avrà un valore di UPLOAD_SIZE_REMAINING pari a 19999957.
- NEXT_BYTE è il numero intero successivo dopo il valore salvato nel passaggio 2. Ad esempio, se 42 è il valore più alto nel passaggio 2, il valore di NEXT_BYTE è 43.
- LAST_BYTE è il byte finale contenuto in questa richiesta PUT. Ad esempio, per completare il caricamento di un oggetto la cui dimensione totale è 20000000, il valore di LAST_BYTE è 19999999.
- TOTAL_OBJECT_SIZE è la dimensione totale dell'oggetto che stai caricando. Ad esempio, 20000000.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

API XML

Controlla lo stato del caricamento ripristinabile.
Salva il valore più alto dell'intestazione Range contenuta nella risposta al controllo dello stato. Se la risposta non ha un'intestazione Range, Cloud Storage non ha ancora mantenuto alcun byte in modo permanente e dovresti caricare dall'inizio.
Assicurati che i dati oggetto che stai per caricare inizino a partire dal byte che segue il valore più alto nell'intestazione Range.
Utilizza cURL per chiamare l'API XML con una richiesta di oggetto PUT che prende il byte che segue il valore nell'intestazione Range:
```
curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"
```
Dove:
- PARTIAL_OBJECT_LOCATION è il percorso locale della parte rimanente di dati che vuoi caricare.
- UPLOAD_SIZE_REMAINING è il numero di byte che stai caricando nella richiesta attuale. Ad esempio, il caricamento del resto di un oggetto con una dimensione totale di 2.000.0000 interrotta dopo i byte da 0 a 42 caricati avrà un valore di UPLOAD_SIZE_REMAINING pari a 19999957.
- NEXT_BYTE è il numero intero successivo dopo il valore salvato nel passaggio 2. Ad esempio, se 42 è il valore più alto nel passaggio 2, il valore di NEXT_BYTE è 43.
- LAST_BYTE è il byte finale contenuto in questa richiesta PUT. Ad esempio, per completare il caricamento di un oggetto la cui dimensione totale è 20000000, il valore di LAST_BYTE è 19999999.
- TOTAL_OBJECT_SIZE è la dimensione totale dell'oggetto che stai caricando. Ad esempio, 20000000.
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

Puoi riprendere i caricamenti tutte le volte che vuoi mentre l'URI della sessione è attivo; l'URI della sessione scade dopo una settimana. Una volta caricati correttamente, Cloud Storage risponde con un codice di stato 200 OK o 201 created.

Annullare un caricamento

Per annullare un caricamento ripristinabile incompleto e impedire ulteriori azioni:

API JSON

Utilizza cURL per chiamare l'API JSON con una richiesta DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Dove:
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

In caso di esito positivo, la risposta contiene un codice di stato 499. Tentativi futuri di eseguire query o riprendere il caricamento avranno come risultato una risposta 4xx.

API XML

Utilizza cURL per chiamare l'API XML con una richiesta DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Dove:
- SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

Se l'esito è positivo, la risposta contiene un codice di stato 204 e anche i tentativi futuri di eseguire query o riprendere il caricamento generano una risposta 204.

Passaggi successivi

Scopri di più sui caricamenti ripristinabili.
Leggi una panoramica dell'API JSON e dell'API XML.
Caricamenti di stream di dimensioni sconosciute.
Esegui in batch più richieste all'API JSON di Cloud Storage.