Questa pagina descrive come effettuare una richiesta di caricamento ripristinabile nelle API JSON e XML di Cloud Storage. Questo protocollo ti consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso di dati.
Per informazioni sull'utilizzo dei caricamenti riavviabili in Google Cloud CLI e nelle librerie client, consulta In che modo gli strumenti e le API utilizzano i caricamenti riavviabili.
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 di conservazione degli oggetti, chiedi all'amministratore di concederti il ruolo IAM Amministratore oggetti di archiviazione (
roles/storage.objectAdmin
) per il bucket.In tutti gli altri casi, chiedi all'amministratore di concederti il ruolo IAM Utente oggetto archiviazione (
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 richieste, 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 è obbligatoria solo per i caricamenti che includono un blocco di conservazione degli oggetti.
Puoi anche ottenere queste autorizzazioni con altri ruoli predefiniti o ruoli personalizzati.
Per informazioni sulla concessione dei ruoli ai bucket, consulta Utilizzare IAM con i bucket.
Avviare una sessione di caricamento ripristinabile
Per avviare una sessione di caricamento ripristinabile:
API JSON
Avere installato e inizializzatogcloud CLI, che consente di generare un token di accesso per l'intestazione
Authorization
.Facoltativamente, crea un file JSON contenente i metadati da impostare sull'oggetto che stai caricando. Ad esempio, il seguente file JSON imposta i metadati
contentType
dell'oggetto che vuoi caricare inimage/png
:{ "contentType": "image/png" }
Utilizza
cURL
per chiamare l'API JSON con una richiesta diPOST
Object: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 specificati nel passaggio precedente. Se non includi un file di metadati, escludi questo file, insieme a--data-binary @
e all'intestazioneContent-Type
.INITIAL_REQUEST_LENGTH
è il numero di byte nel corpo di questa richiesta iniziale, ad esempio79
.BUCKET_NAME
è il nome del bucket in cui stai caricando l'oggetto. Ad esempio,my-bucket
.OBJECT_NAME
è il nome con codifica URL da assegnare all'oggetto. Ad esempio,pets/dog.png
, codificato come URL comepets%2Fdog.png
. Questo passaggio non è necessario se hai incluso unname
nel file dei metadati dell'oggetto nel passaggio 2.
Se hai attivato la condivisione delle risorse tra origini (CORS), devi anche includere un'intestazione
Origin
sia in questa che nelle richieste di caricamento successive.Le intestazioni facoltative che puoi aggiungere alla richiesta includono
X-Upload-Content-Type
eX-Upload-Content-Length
.In caso di esito positivo, la risposta include un codice di stato
200
.Salva l'URI sessione riassumibile indicato nell'intestazione
Location
della risposta alla richiesta dell'oggettoPOST
.Questo URI viene utilizzato nelle richieste successive per caricare i dati dell'oggetto.
API XML
Avere installato e inizializzatogcloud CLI, che consente di generare un token di accesso per l'intestazione
Authorization
.Utilizza
cURL
per chiamare l'API XML con una richiesta diPOST
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 contenuto dell'oggetto. Ad esempio:image/png
. Se non specifichi un tipo di contenuti, il sistema Cloud Storage imposta i metadatiContent-Type
per l'oggetto suapplication/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
, codificato come URL comepets%2Fdog.png
.
Se hai attivato la condivisione delle risorse tra origini (CORS), devi anche includere un'intestazione
Origin
sia in questa richiesta di caricamento sia nelle successive.In caso di esito positivo, la risposta include un messaggio di stato
201
.Salva l'URI sessione riassumibile indicato nell'intestazione
Location
della risposta alla richiesta dell'oggettoPOST
.Questo URI viene utilizzato nelle richieste successive per caricare i dati dell'oggetto.
Carica i dati
Dopo aver avviato un caricamento ripristinabile, hai due modi per caricare i dati dell'oggetto:
- In un unico chunk:in genere, questo approccio è il migliore, poiché richiede meno richieste e, di conseguenza, ha un rendimento migliore.
- In più parti:utilizza questo approccio se devi ridurre la quantità di dati trasferiti in una singola richiesta, ad esempio quando esiste un limite di tempo fisso per le singole richieste o se non conosci le dimensioni totali del caricamento all'inizio del caricamento.
Caricamento di un singolo chunk
Per caricare i dati in un unico blocco:
API JSON
Utilizza
cURL
per chiamare l'API JSON con una richiesta diPUT
oggetto: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 dell'oggetto. Ad esempio,20000000
.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
Se vuoi, puoi includere intestazioni con prefisso
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 richiestaPUT
Object: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 dell'oggetto. Ad esempio,20000000
.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
Se il caricamento viene completato per intero, ricevi una risposta 200 OK
o 201 Created
insieme a 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ù chunk
Per caricare i dati in più blocchi:
API JSON
Crea un frammento di dati dai dati complessivi che vuoi caricare.
La dimensione del chunk deve essere un multiplo di 256 KiB (256 x 1024 byte), a meno che non si tratti dell'ultimo chunk che completa il caricamento. Dimensioni dei chunk più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del chunk.
Utilizza
cURL
per chiamare l'API JSON con una richiesta diPUT
oggetto: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 chunk che stai caricando.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 chunk che stai caricando.CHUNK_LAST_BYTE
è il byte finale dell'oggetto complessivo contenuto nel chunk che stai caricando.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
Un esempio di
Content-Range
èContent-Range: bytes 0-8388607/20000000
. Per ulteriori informazioni su questa intestazione, vediContent-Range
.Se la richiesta riesce, il server risponde con
308 Resume Incomplete
. La risposta contiene un'intestazioneRange
.Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi caricare, utilizzando il valore superiore contenuto nell'intestazione
Range
di ogni risposta per determinare dove iniziare ogni blocco successivo. Non assumere che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.Se vuoi, nella richiesta finale del caricamento ripristinabile puoi includere parametri iniziali con prefisso
X-Goog-Meta-
per aggiungere metadati personalizzati per l'oggetto.
API XML
Crea un frammento di dati dai dati complessivi che vuoi caricare.
La dimensione del chunk deve essere un multiplo di 256 KiB (256 x 1024 byte), a meno che non si tratti dell'ultimo chunk che completa il caricamento. Dimensioni dei chunk più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e utilizzo della memoria. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del chunk.
Utilizza
cURL
per chiamare l'API XML con una richiestaPUT
Object: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 chunk che stai caricando.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 chunk che stai caricando.CHUNK_LAST_BYTE
è il byte finale dell'oggetto complessivo contenuto nel chunk che stai caricando.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
Un esempio di
Content-Range
èContent-Range: bytes 0-8388607/20000000
. Per ulteriori informazioni su questa intestazione, vediContent-Range
.Se la richiesta riesce, il server risponde con
308 Resume Incomplete
. La risposta contiene un'intestazioneRange
.Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi caricare, utilizzando il valore superiore contenuto nell'intestazione
Range
di ogni risposta per determinare dove iniziare ogni blocco successivo. Non assumere che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.
Una volta completato il caricamento, riceverai una risposta 200 OK
o
201 Created
, insieme a eventuali metadati associati alla risorsa.
Se uno dei caricamenti dei chunk viene interrotto o se ricevi una risposta 5xx
, devi inviare nuovamente il chunk interrotto nella sua interezza o riprendere il caricamento interrotto da dove si era interrotto.
Controllare lo stato di un caricamento ripristinabile
Se il caricamento ripristinabile viene interrotto o non hai la certezza che sia stato completato, puoi controllare il relativo stato:
API JSON
Utilizza
cURL
per chiamare l'API JSON con una richiesta diPUT
oggetto:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Dove:
OBJECT_SIZE
è il numero totale di byte nel tuo oggetto. Se non conosci le dimensioni complete dell'oggetto, utilizza*
per questo valore.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
API XML
Utilizza
cURL
per chiamare l'API XML con una richiestaPUT
Object:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Dove:
OBJECT_SIZE
è il numero totale di byte nel tuo oggetto. Se non conosci le dimensioni complete dell'oggetto, utilizza*
per questo valore.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
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'intestazioneRange
. In questo caso, devi avviare il caricamento da capo. - In caso contrario, la risposta
308
ha un'intestazioneRange
, che specifica i byte che Cloud Storage ha mantenuto finora. Utilizza questo valore quando riprendi un caricamento interrotto.
Riprendere un caricamento interrotto
Se una richiesta di caricamento viene interrotta 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.
Salva il valore superiore dell'intestazione
Range
contenuta nella risposta al controllo dello stato. Se la risposta non contiene un'intestazioneRange
, Cloud Storage non ha ancora mantenuto alcun byte e devi caricare dall'inizio.Assicurati che i dati dell'oggetto che stai per caricare inizino dal byte successivo al valore superiore 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 diPUT
oggetto che viene rilevata dal byte successivo al valore nell'Range
intestazione: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 dei dati che vuoi caricare.UPLOAD_SIZE_REMAINING
è il numero di byte caricati nella richiesta corrente. Ad esempio, il caricamento del resto di un oggetto con dimensioni totali pari a 20000000 che è stato interrotto dopo il caricamento dei byte 0-42 avrà un valoreUPLOAD_SIZE_REMAINING
pari a19999957
.NEXT_BYTE
è il numero intero successivo al valore salvato nel passaggio 2. Ad esempio, se42
è il valore superiore nel passaggio 2, il valore diNEXT_BYTE
è43
.LAST_BYTE
è il byte finale contenuto in questaPUT
richiesta. Ad esempio, per completare il caricamento di un oggetto di dimensione totale20000000
, il valore diLAST_BYTE
è19999999
.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando. Ad esempio,20000000
.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
API XML
Controlla lo stato del caricamento.
Salva il valore superiore dell'intestazione
Range
contenuta nella risposta al controllo dello stato. Se la risposta non contiene unRange
header, Cloud Storage non ha ancora mantenuto alcun byte e devi caricare da capo.Assicurati che i dati dell'oggetto che stai per caricare inizino dal byte successivo al valore superiore nell'intestazione
Range
.Utilizza
cURL
per chiamare l'API XML con una richiesta di oggettoPUT
che viene rilevata dal byte successivo al valore nell'intestazioneRange
: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 dei dati che vuoi caricare.UPLOAD_SIZE_REMAINING
è il numero di byte caricati nella richiesta corrente. Ad esempio, il caricamento del resto di un oggetto con dimensioni totali pari a 20000000 che è stato interrotto dopo il caricamento dei byte 0-42 avrà un valoreUPLOAD_SIZE_REMAINING
pari a19999957
.NEXT_BYTE
è il numero intero successivo al valore salvato nel passaggio 2. Ad esempio, se42
è il valore superiore nel passaggio 2, il valore diNEXT_BYTE
è43
.LAST_BYTE
è il byte finale contenuto in questaPUT
richiesta. Ad esempio, per completare il caricamento di un oggetto di dimensione totale20000000
, il valore diLAST_BYTE
è19999999
.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando. Ad esempio,20000000
.SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
Puoi riprendere i caricamenti tutte le volte che vuoi finché l'URI sessione è attivo. L'URI sessione scade dopo una settimana. Quando i dati vengono caricati correttamente, Cloud Storage risponde con un codice stato 200 OK
o 201 created
.
Annullare un caricamento
Per annullare un caricamento ripristinabile possibilità di ripresa e impedire qualsiasi ulteriore azione al riguardo:
API JSON
Utilizza
cURL
per chiamare l'API JSON con una richiestaDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dove:
SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
In caso di esito positivo, la risposta contiene un codice di stato 499
. I tentativi futuri di eseguire query o riprendere il caricamento generano una risposta 4xx
.
API XML
Utilizza
cURL
per chiamare l'API XML con una richiestaDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dove:
SESSION_URI
è il valore restituito nell'Location
quando hai avviato il caricamento riavviabile.
In caso di esito positivo, la risposta contiene un codice di stato 204
e i tentativi futuri di eseguire query o riprendere il caricamento generano anche una risposta 204
.
Gestione degli errori
In rare circostanze, una richiesta di ripresa di un caricamento interrotto potrebbe non riuscire con un errore "4xx" non recuperabile perché le autorizzazioni del bucket sono cambiate o perché il controllo dell'integrità dell'oggetto caricato finale ha rilevato una mancata corrispondenza. In questo caso, riprova a caricare avviando una nuova caricamento ripristinabile interrompibile.
Passaggi successivi
- Scopri di più sui caricamenti ripristinabili.
- Leggi una panoramica dell'API JSON e dell'API XML.
- Caricamenti in streaming di dimensioni sconosciute.
- Esegui più richieste collettive all'API Cloud Storage JSON.