In questa pagina viene descritto come effettuare una richiesta di caricamento ripristinabile nel API JSON e XML di Cloud Storage. Questo protocollo consente di riprendere un caricamento dell'operazione dopo un errore di comunicazione interrompe il flusso di dati.
Per informazioni sull'utilizzo di caricamenti ripristinabili in Google Cloud CLI e nel client librerie, consulta l'articolo su come 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 al tuo che ti conceda il ruolo di Amministratore oggetti Storage (
roles/storage.objectAdmin
) Ruolo IAM per il bucket.In tutti gli altri casi, chiedi all'amministratore di concederti l'oggetto Storage Ruolo IAM dell'utente (
roles/storage.objectUser
) per il bucket.
Questi ruoli predefiniti contengono le autorizzazioni necessarie per caricare un oggetto in un per i rispettivi casi. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
storage.objects.create
storage.objects.delete
- Questa autorizzazione è richiesta solo per i caricamenti che sovrascrivono un file .
storage.objects.setRetention
- Questa autorizzazione è richiesta solo per i caricamenti che includono un oggetto Blocco conservazione.
Puoi ottenere queste autorizzazioni anche con altri ruoli predefiniti oppure ruoli personalizzati.
Per informazioni sulla concessione dei ruoli nei bucket, consulta Utilizzare IAM con i bucket.
Avviare una sessione di caricamento ripristinabile
Per avviare una sessione di caricamento ripristinabile:
API JSON
Avere gcloud CLI installato e inizializzato, per generare un token di accesso per l'intestazione
Authorization
.In alternativa, puoi creare un token di accesso utilizzando il metodo OAuth 2.0 Playground e includilo nell'intestazione
Authorization
.Facoltativamente, crea un file JSON contenente i metadati che hai da impostare sull'oggetto che stai caricando. Ad esempio, il seguente file JSON imposta i metadati
contentType
dell'oggetto vuoi caricare suimage/png
:{ "contentType": "image/png" }
Utilizza
cURL
per chiamare l'API JSON con un RichiestaPOST
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 File JSON contenente i metadati facoltativi specificati nel passaggio precedente. Se non intendi includere un file di metadati, escludi insieme a--data-binary @
e all'intestazioneContent-Type
.INITIAL_REQUEST_LENGTH
è il numero di byte nel corpo di questa richiesta iniziale, ad esempio79
. No necessaria se utilizzi la codifica del trasferimento a blocchi.BUCKET_NAME
è il nome del bucket dell'oggetto. Ad esempio,my-bucket
.OBJECT_NAME
è il nome con codifica URL che vuoi per assegnare l'oggetto. Ad esempio,pets/dog.png
, con codifica URLpets%2Fdog.png
. Questa operazione non è necessaria se hai incluso un valorename
nella il file dei metadati dell'oggetto nel passaggio 2.
Se hai abilitato la condivisione delle risorse tra origini, dovresti anche includi 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
eX-Upload-Content-Length
.In caso di esito positivo, la risposta include un codice di stato
200
.Salva l'URI di sessione ripristinabile fornito nell'intestazione
Location
di la risposta alla tua richiesta di oggettoPOST
.Questo URI viene utilizzato nelle richieste successive di caricamento dei dati dell'oggetto.
API XML
Avere gcloud CLI installato e inizializzato, per generare un token di accesso per l'intestazione
Authorization
.In alternativa, puoi creare un token di accesso utilizzando il metodo OAuth 2.0 Playground e includilo nell'intestazione
Authorization
.Utilizza
cURL
per chiamare l'API XML con un Richiesta di oggettoPOST
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 contenuto, il sistema Cloud Storage imposta i metadatiContent-Type
per l'oggettoapplication/octet-stream
.BUCKET_NAME
è il nome del bucket dell'oggetto. Ad esempio,my-bucket
.OBJECT_NAME
è il nome codificato nell'URL che da assegnare all'oggetto. Ad esempio,pets/dog.png
, con codifica URL comepets%2Fdog.png
.
Se hai abilitato la condivisione delle risorse tra origini, dovresti anche includi un'intestazione
Origin
in questa richiesta di caricamento e in quelle successive.In caso di esito positivo, la risposta include un messaggio di stato
201
.Salva l'URI della sessione ripristinabile fornito nell'intestazione
Location
della risposta alla tua richiesta di oggettoPOST
.Questo URI viene utilizzato nelle richieste successive di caricamento dei dati dell'oggetto.
Carica i dati
Una volta avviato un caricamento ripristinabile, esistono due modi per caricare il file i dati dell'oggetto:
- In un singolo blocco: questo approccio di solito è l'ideale, in quanto richiede di richieste e quindi ha un rendimento migliore.
- In più blocchi: utilizza questo approccio se devi ridurre la quantità di Dati trasferiti in ogni singola richiesta, ad esempio quando c'è un orario fisso il limite per le singole richieste o se non conosci la dimensione totale al momento dell'inizio del caricamento.
Caricamento di blocchi singoli
Per caricare i dati in un unico blocco:
API JSON
Utilizza
cURL
per chiamare l'API JSON con unPUT
Richiesta oggetto:curl -i -X PUT --data-binary @OBJECT_LOCATION \ -H "Content-Length: OBJECT_SIZE" \ "SESSION_URI"
Dove:
OBJECT_LOCATION
è il percorso locale . Ad esempio,Desktop/dog.png
.OBJECT_SIZE
è il numero di byte in . Ad esempio,20000000
.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Se vuoi, puoi includere intestazioni con prefisso
X-Goog-Meta-
per aggiungere metadati personalizzati per l'oggetto come parte di questa richiesta.
API XML
Utilizza
cURL
per chiamare l'API XML con unPUT
Richiesta oggetto:curl -i -X PUT --data-binary @OBJECT_LOCATION \ -H "Content-Length: OBJECT_SIZE" \ "SESSION_URI"
Dove:
OBJECT_LOCATION
è il percorso locale . Ad esempio,Desktop/dog.png
.OBJECT_SIZE
è il numero di byte in . Ad esempio,20000000
.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Se il caricamento viene completato nella sua interezza, ricevi un 200 OK
o 201 Created
insieme agli eventuali metadati associati alla risorsa.
Se la richiesta di caricamento viene interrotta o se ricevi un 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. Dimensioni del chunk più grandi di solito i caricamenti sono più veloci, ma c'è 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 unPUT
Richiesta 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 blocco che stai caricando.CHUNK_SIZE
è il numero di byte che stai caricamento nella richiesta corrente. Ad esempio,8388608
.CHUNK_FIRST_BYTE
è il byte iniziale in all'oggetto complessivo contenuto nel blocco che stai caricando.CHUNK_LAST_BYTE
è il byte finale in all'oggetto complessivo contenuto nel blocco che stai caricando.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Un esempio di
Content-Range
èContent-Range: bytes 0-8388607/20000000
. ConsultaContent-Range
per ulteriori informazioni su questa intestazione.Se la richiesta ha esito positivo, il server risponde
308 Resume Incomplete
. La risposta contiene un'intestazioneRange
.Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi utilizzando il valore più alto contenuto nell'intestazione
Range
di ogni risposta per determinare dove iniziare ogni blocco successivo; dovresti non presupporre che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.Se vuoi, nella richiesta finale del caricamento ripristinabile puoi includere intestazioni con prefisso
X-Goog-Meta-
per aggiungere metadati personalizzati per dell'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. Dimensioni del chunk più grandi di solito i caricamenti sono più veloci, ma c'è 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 unPUT
Richiesta 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 blocco che stai caricando.CHUNK_SIZE
è il numero di byte che stai caricamento nella richiesta corrente. Ad esempio,8388608
.CHUNK_FIRST_BYTE
è il byte iniziale in all'oggetto complessivo contenuto nel blocco che stai caricando.CHUNK_LAST_BYTE
è il byte finale in all'oggetto complessivo contenuto nel blocco che stai caricando.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Un esempio di
Content-Range
èContent-Range: bytes 0-8388607/20000000
. ConsultaContent-Range
per ulteriori informazioni su questa intestazione.Se la richiesta ha esito positivo, il server risponde
308 Resume Incomplete
. La risposta contiene un'intestazioneRange
.Ripeti i passaggi precedenti per ogni blocco di dati rimanente che vuoi utilizzando il valore più alto contenuto nell'intestazione
Range
di ogni risposta per determinare dove iniziare ogni blocco successivo; dovresti non presupporre che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.
Una volta completato il caricamento, riceverai un 200 OK
o
201 Created
, insieme agli eventuali metadati associati alla risorsa.
Se uno o più caricamenti di blocchi vengono interrotti o se ricevi un 5xx
devi inviare nuovamente il blocco interrotto nella sua interezza oppure
riprendi il caricamento interrotto dal punto in cui era stato interrotto.
Controllare lo stato di un caricamento ripristinabile
Se il caricamento ripristinabile viene interrotto o non sei sicuro che il caricamento completato, puoi controllare lo stato del caricamento:
API JSON
Utilizza
cURL
per chiamare l'API JSON con unPUT
Richiesta 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 in dell'oggetto. Se non conosci la dimensione originale dell'oggetto, utilizza*
per questo valore.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
API XML
Utilizza
cURL
per chiamare l'API XML con unPUT
Richiesta 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 in dell'oggetto. Se non conosci la dimensione originale dell'oggetto, utilizza*
per questo valore.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Una risposta 200 OK
o 201 Created
indica che il caricamento è stato
è stata completata e non sono necessarie ulteriori azioni.
Una risposta 308 Resume Incomplete
indica che devi continuare
caricare i dati.
- Se Cloud Storage non ha ancora mantenuto alcun byte, la risposta
308
non ha un'intestazioneRange
. In questo caso, dovresti iniziare per il caricamento dall'inizio. - In caso contrario, la risposta
308
ha un'intestazioneRange
, che specifica i byte mantenuti finora da Cloud Storage. Usa questo valore quando il ripristino di 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
, poi devi riprendere
il caricamento interrotto da dove era stato interrotto. Per riprendere un caricamento interrotto:
API JSON
Controlla lo stato del caricamento ripristinabile.
Salva il valore superiore dell'intestazione
Range
contenuta nella risposta. al controllo dello stato. Se la risposta non ha un'intestazioneRange
, Cloud Storage non ha ancora mantenuto alcun byte. Dovresti effettuare il caricamento dall'inizio.Assicurati che i dati oggetto che stai per caricare inizino nel byte seguendo il valore più alto nell'intestazione
Range
.Se la richiesta interrotta conteneva intestazioni con prefisso
X-Goog-Meta-
, includi queste intestazioni nella richiesta di ripristino il tuo caricamento.Utilizza
cURL
per chiamare l'API JSON con unPUT
dell'oggetto che viene selezionato nel byte dopo il valore nellaRange
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 per la parte rimanente di dati che vuoi caricare.UPLOAD_SIZE_REMAINING
è il numero di byte che stai caricando nella richiesta attuale. Ad esempio, il caricamento resto di un oggetto con una dimensione totale di 20000000 che è stato interrotto dopo i byte caricati tra 0 e 42 avrebberoUPLOAD_SIZE_REMAINING
di19999957
.NEXT_BYTE
è il numero intero successivo dopo il valore salvato nel passaggio 2. Ad esempio, se42
è il valore più alto in Passaggio 2, il valore diNEXT_BYTE
è43
.LAST_BYTE
è il byte finale contenuto in questo RichiestaPUT
. Ad esempio, per completare il caricamento di un oggetto il cui totale la dimensione è20000000
, il valore diLAST_BYTE
è19999999
.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando. Ad esempio,20000000
.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
API XML
Controlla lo stato del caricamento ripristinabile.
Salva il valore superiore dell'intestazione
Range
contenuta nei in risposta al controllo dello stato. Se la risposta non include unRange
intestazione, Cloud Storage non ha ancora mantenuto alcun byte e tu dovrebbe caricare dall'inizio.Assicurati che i dati oggetto che stai per caricare inizino nel byte seguendo il valore più alto nell'intestazione
Range
.Utilizza
cURL
per chiamare l'API XML con un oggettoPUT
che viene prelevata al byte dopo il valore nell'elementoRange
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 per la parte rimanente di dati che vuoi caricare.UPLOAD_SIZE_REMAINING
è il numero di byte che stai caricando nella richiesta attuale. Ad esempio, il caricamento resto di un oggetto con una dimensione totale di 20000000 che è stato interrotto dopo i byte caricati tra 0 e 42 avrebberoUPLOAD_SIZE_REMAINING
di19999957
.NEXT_BYTE
è il numero intero successivo dopo il valore salvato nel passaggio 2. Ad esempio, se42
è il valore più alto in Passaggio 2, il valore diNEXT_BYTE
è43
.LAST_BYTE
è il byte finale contenuto in questo RichiestaPUT
. Ad esempio, per completare il caricamento di un oggetto il cui totale la dimensione è20000000
, il valore diLAST_BYTE
è19999999
.TOTAL_OBJECT_SIZE
è la dimensione totale dell'oggetto che stai caricando. Ad esempio,20000000
.SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Puoi riprendere i caricamenti tutte le volte necessarie mentre l'URI della sessione
attivo; l'URI della sessione scade dopo una settimana. Una volta che i dati vengono
caricato, Cloud Storage risponde con un 200 OK
o 201 created
codice di stato.
Annullare un caricamento
Per annullare un caricamento ripristinabile incompleto e impedire qualsiasi ulteriore azione:
API JSON
Utilizza
cURL
per chiamare l'API JSON con unDELETE
richiesta:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dove:
SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
In caso di esito positivo, la risposta contiene un codice di stato 499
. Tentativi futuri
per eseguire query o riprendere il caricamento, restituisce una risposta 4xx
.
API XML
Utilizza
cURL
per chiamare l'API XML con unDELETE
richiesta:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dove:
SESSION_URI
è il valore restituito nelLocation
quando hai avviato il caricamento ripristinabile.
Se l'esito è positivo, la risposta contiene un codice di stato 204
e una risposta
i tentativi di eseguire una query o riprendere il caricamento comportano anche una risposta 204
.
Passaggi successivi
- Scopri di più sui caricamenti ripristinabili.
- Leggi una panoramica dell'API JSON e dell'API XML.
- Caricamenti in streaming di dimensioni sconosciute.
- Batch più richieste all'API JSON di Cloud Storage.