Esegui caricamenti ripristinabili

Panoramica

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.

  • Per 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 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 nei bucket, consulta Utilizzare IAM con i bucket.

Avviare una sessione di caricamento ripristinabile

Per avviare una sessione di caricamento ripristinabile:

API JSON

  1. Avere gcloud CLI installato e inizializzato, che consente generi un token di accesso per l'intestazione Authorization.

  2. Facoltativamente, crea un file JSON contenente i metadati che da impostare sull'oggetto che stai caricando. Ad esempio, il seguente file JSON imposta i metadati contentType dell'oggetto che vuoi caricare in image/png:

    {
    "contentType": "image/png"
}

  3. Utilizza cURL per chiamare l'API JSON con un 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 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'intestazione Content-Type.
    • INITIAL_REQUEST_LENGTH è il numero di byte nel corpo di questa richiesta iniziale, ad esempio 79.
    • BUCKET_NAME è il nome del bucket dell'oggetto. Ad esempio, my-bucket.
    • OBJECT_NAME è il nome con codifica URL da assegnare all'oggetto. Ad esempio, pets/dog.png, codificato come URL come pets%2Fdog.png. Questo passaggio non è necessario se hai incluso un name 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 richiesta di caricamento sia nelle successive.

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

    In caso di esito positivo, la risposta include un codice di stato 200.

  4. Salva l'URI di sessione ripristinabile fornito nell'intestazione Location di la risposta alla tua richiesta di oggetto POST.

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

API XML

  1. Avere installato e inizializzato l'interfaccia a riga di comando gcloud, che consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API XML con una richiesta di POSToggetto 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 metadati Content-Type per l'oggetto 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, codificato come URL come pets%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.

  3. Salva l'URI della sessione ripristinabile fornito nell'intestazione Location della risposta alla tua richiesta di oggetto POST.

    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 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 blocchi singoli

Per caricare i dati in un unico blocco:

API JSON

  1. Utilizza cURL per chiamare l'API JSON con una richiesta di PUT 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

  1. Utilizza cURL per chiamare l'API XML con una richiesta PUT 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 nel Location quando hai avviato il caricamento ripristinabile.

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 un 5xx segui la procedura descritta in Riprendere un caricamento interrotto.

Caricamento di più chunk

Per caricare i dati in più blocchi:

API JSON

  1. 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 in genere 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.

  2. Utilizza cURL per chiamare l'API JSON con un PUT 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 chunk che stai caricando.
    • CHUNK_SIZE è il numero di byte che stai caricamento 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 nel Location quando hai avviato il caricamento ripristinabile.

    Un esempio di Content-Range è Content-Range: bytes 0-8388607/20000000. Consulta Content-Range per ulteriori informazioni su questa intestazione.

    Se la richiesta riesce, il server risponde con 308 Resume Incomplete. La risposta contiene un'intestazione Range.

  3. 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 riavviabile puoi includere parametri iniziali con prefisso X-Goog-Meta- per aggiungere metadati personalizzati per l'oggetto.

API XML

  1. Crea un frammento 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 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.

  2. Utilizza cURL per chiamare l'API XML con una richiesta PUT 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 caricamento 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, vedi Content-Range.

    Se la richiesta ha esito positivo, il server risponde 308 Resume Incomplete. La risposta contiene un'intestazione Range.

  3. Ripeti i passaggi precedenti per ogni blocco di dati rimanente da 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 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

  1. Utilizza cURL per chiamare l'API JSON con un PUT 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 nel tuo oggetto. Se non conosci le dimensioni complete dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nel Location quando hai avviato il caricamento ripristinabile.

API XML

  1. Utilizza cURL per chiamare l'API XML con una richiesta PUT 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 in dell'oggetto. Se non conosci la dimensione originale 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'intestazione Range. In questo caso, devi avviare il caricamento da capo.
  • In caso contrario, la risposta 308 ha un'intestazione Range, 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 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

  1. Controlla lo stato del caricamento.

  2. Salva il valore superiore 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. Dovresti effettuare il caricamento dall'inizio.

  3. Assicurati che i dati dell'oggetto che stai per caricare inizino dal byte successivo al valore superiore nell'intestazione Range.

  4. Se la richiesta interrotta conteneva intestazioni con prefisso X-Goog-Meta-, includi queste intestazioni nella richiesta di ripristino il tuo caricamento.

  5. Utilizza cURL per chiamare l'API JSON con un PUT dell'oggetto che viene selezionato nel byte dopo il valore nella 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 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 avrebbero UPLOAD_SIZE_REMAINING di 19999957.
    • NEXT_BYTE è l'intero successivo al valore salvato nel passaggio 2. Ad esempio, se 42 è il valore più alto in Passaggio 2, il valore di NEXT_BYTE è 43.
    • LAST_BYTE è il byte finale contenuto in questa PUT richiesta. Ad esempio, per completare il caricamento di un oggetto di 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 nel Location quando hai avviato il caricamento ripristinabile.

API XML

  1. Controlla lo stato del caricamento.

  2. Salva il valore superiore dell'intestazione Range contenuta nella risposta al controllo dello stato. Se la risposta non ha un Range header, Cloud Storage non ha ancora mantenuto alcun byte e devi caricare dall'inizio.

  3. Assicurati che i dati dell'oggetto che stai per caricare inizino dal byte successivo al valore superiore nell'intestazione Range.

  4. Utilizza cURL per chiamare l'API XML con una richiesta di oggetto PUT che riprende dal byte successivo al 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 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 avrebbero UPLOAD_SIZE_REMAINING di 19999957.
    • NEXT_BYTE è l'intero successivo al valore salvato nel passaggio 2. Ad esempio, se 42 è il valore più alto in Passaggio 2, il valore di NEXT_BYTE è 43.
    • LAST_BYTE è il byte finale contenuto in questa PUT richiesta. Ad esempio, per completare il caricamento di un oggetto di 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 nel Location quando hai avviato il caricamento ripristinabile.

Puoi riprendere i caricamenti tutte le volte necessarie mentre l'URI della sessione active; l'URI della 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 parziale con possibilità di ripresa e impedire qualsiasi ulteriore azione al riguardo:

API JSON

  1. Utilizza cURL per chiamare l'API JSON con una richiesta DELETE:

    curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    Dove:

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

  1. Utilizza cURL per chiamare l'API XML con un DELETE richiesta:

    curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    Dove:

In caso di 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.

Gestione degli errori

In rari casi, la richiesta di riprendere un caricamento interrotto potrebbe non andare a buon fine con un file "4xx" non recuperabile perché le autorizzazioni sul bucket sono state modificate, o perché il controllo dell'integrità dell'oggetto caricato finale ha rilevato una mancata corrispondenza. In questo caso, riprova a caricare avviando una nuova sessione di caricamento interrompibile.

Passaggi successivi