Eseguire caricamenti ripristinabili

Panoramica

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 ha interrotto il flusso di dati.

Per informazioni sull'utilizzo dei caricamenti ripristinabili in Google Cloud CLI e nelle librerie client, consulta la pagina In che modo gli strumenti e le API utilizzano i 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 della conservazione degli oggetti, chiedi all' amministratore di concederti il ruolo IAM Amministratore oggetti Storage (roles/storage.objectAdmin) per il bucket.

  • In 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 vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

  • storage.objects.create
  • storage.objects.delete
    • Questa autorizzazione è richiesta solo per i caricamenti che sovrascrivono un oggetto esistente.
  • storage.objects.setRetention
    • Questa autorizzazione è richiesta solo per i caricamenti che includono un blocco della conservazione degli oggetti.

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

Per informazioni sulla concessione dei ruoli nei bucket, consulta Impostare e gestire i criteri IAM nei bucket.

Avviare una sessione di caricamento ripristinabile

Per avviare una sessione di caricamento ripristinabile:

API JSON

  1. Assicurati che gcloud CLI sia installato e inizializzato, in modo da poter generare un token di accesso per l'intestazione Authorization.

  2. (Facoltativo) Crea un file JSON contenente i metadati che vuoi impostare sull'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"
}

  3. Utilizza cURL per chiamare l'API JSON con una POST Object richiesta:

    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, 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 in cui stai caricando l'oggetto. Ad esempio, my-bucket.
    • OBJECT_NAME è il nome codificato come URL che vuoi assegnare all'oggetto. Ad esempio, pets/dog.png, codificato come URL pets%2Fdog.png. Questo non è obbligatorio se hai incluso un name nel file di metadati dell'oggetto nel passaggio 2.

    Se hai abilitato la condivisione delle risorse tra origini diverse, devi includere anche un'intestazione Origin in questa e nelle successive richieste di caricamento.

    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 e ha un aspetto simile al seguente:

    HTTP/2 200
content-type: text/plain; charset=utf-8
x-guploader-uploadid: ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
location: https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=cat-pic.jpeg&upload_id=ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
date: Mon, 07 Jul 2025 14:57:21 GMT
vary: Origin
vary: X-Origin
cache-control: no-cache, no-store, max-age=0, must-revalidate
expires: Mon, 01 Jan 1990 00:00:00 GMT
pragma: no-cache
content-length: 0
server: UploadServer
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000

  4. Salva l'URI della sessione ripristinabile fornito nell'intestazione location di risposta alla richiesta POST Object.

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

API XML

  1. Assicurati che gcloud CLI sia installato e inizializzato, in modo da poter generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API XML con una POST Object request 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 contenuti, il sistema Cloud Storage imposta i Content-Type metadati dell'oggetto su application/octet-stream.
    • BUCKET_NAME è il nome del bucket in cui stai caricando l'oggetto. Ad esempio, my-bucket.
    • OBJECT_NAME è il nome codificato come 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 diverse, devi includere anche un'intestazione Origin in questa e nelle successive richieste di caricamento.

    In caso di esito positivo, la risposta include un messaggio di stato 201.

  3. Salva l'URI della sessione ripristinabile fornito nell'location intestazione della risposta alla richiesta POST Object.

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

Carica i dati

Una volta avviato un caricamento ripristinabile, puoi caricare i dati dell'oggetto in due modi:

  • In un singolo blocco: questo approccio è in genere il migliore, poiché richiede meno richieste e quindi offre prestazioni migliori.
  • In più blocchi: utilizza questo approccio se devi ridurre la quantità di dati trasferiti in una singola richiesta, ad esempio quando è presente un limite di tempo fisso per le singole richieste o se non conosci le dimensioni totali del caricamento al momento dell'inizio del caricamento.

Caricamento di un singolo blocco

Per caricare i dati in un singolo blocco:

API JSON

  1. Utilizza cURL per chiamare l'API JSON 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 nell' location intestazione quando hai avviato il caricamento ripristinabile.

    (Facoltativo) Puoi includere intestazioni con il prefisso X-Goog-Meta- per aggiungere metadati personalizzati per l'oggetto come parte di questa richiesta.

API XML

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

Se il caricamento viene completato interamente, ricevi una risposta 200 OK o 201 Created, insieme a tutti i metadati associati alla risorsa.

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

Caricamento di più blocchi

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 che completa il caricamento. Le dimensioni dei blocchi più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e memoria utilizzata. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del blocco.

  2. Utilizza cURL per chiamare l'API JSON 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 blocco 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 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. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione quando hai avviato il caricamento ripristinabile.

    Un esempio Content-Range è Content-Range: bytes 0-8388607/20000000. Per ulteriori informazioni 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.

  3. 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 da dove iniziare ogni blocco successivo; non devi presupporre che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.

    (Facoltativo) Nella richiesta finale del caricamento ripristinabile puoi includere intestazioni con il prefisso X-Goog-Meta- per aggiungere metadati personalizzati per l'oggetto.

API XML

  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 che completa il caricamento. Le dimensioni dei blocchi più grandi in genere velocizzano i caricamenti, ma tieni presente che esiste un compromesso tra velocità e memoria utilizzata. Ti consigliamo di utilizzare almeno 8 MiB per la dimensione del blocco.

  2. Utilizza cURL per chiamare l'API XML con una PUT richiesta 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 blocco 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 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. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione quando hai avviato il caricamento ripristinabile.

    Un esempio Content-Range è Content-Range: bytes 0-8388607/20000000. Per ulteriori informazioni 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.

  3. 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 da dove iniziare ogni blocco successivo; non devi presupporre che il server abbia ricevuto tutti i byte inviati in una determinata richiesta.

Se il caricamento viene completato interamente, ricevi una risposta 200 OK o 201 Created, insieme a tutti i metadati associati alla risorsa.

Se uno dei caricamenti dei blocchi viene interrotto o se ricevi una 5xx risposta, devi inviare nuovamente l'intero blocco interrotto o riprendere il caricamento interrotto dal punto in cui si era interrotto.

Controllare lo stato di un caricamento ripristinabile

Se il caricamento ripristinabile viene interrotto o non sei sicuro che sia stato completato, puoi controllarne lo stato:

API JSON

  1. Utilizza cURL per chiamare l'API JSON 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 dell'oggetto. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione quando hai avviato il caricamento ripristinabile.

API XML

  1. Utilizza cURL per chiamare l'API XML con una PUT richiesta 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 dell'oggetto. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione quando hai avviato il caricamento ripristinabile.

Una risposta 200 OK o 201 Created indica che il caricamento è stato completato e non è necessaria alcuna ulteriore azione.

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

  • Se Cloud Storage non ha ancora reso persistenti i byte, la 308 risposta non ha un'Range intestazione. In questo caso, devi iniziare il caricamento dall'inizio.
  • In caso contrario, la risposta 308 ha un'intestazione Range, che specifica i byte che Cloud Storage ha reso persistenti 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, devi riprendere il caricamento interrotto dal punto in cui si era interrotto. Per riprendere un caricamento interrotto:

API JSON

  1. Controlla lo stato del caricamento ripristinabile.

  2. Salva il valore superiore dell'Range intestazione contenuta nella risposta al controllo dello stato. Se la risposta non ha un'intestazione Range, Cloud Storage non ha ancora reso persistenti i 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. Se la richiesta interrotta conteneva intestazioni con il prefisso X-Goog-Meta-, includile nella richiesta per riprendere il caricamento.

  5. Utilizza cURL per chiamare l'API JSON con una richiesta PUT Object che riprende dal byte successivo al valore nell' Range header:

    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 che stai caricando nella richiesta corrente. Ad esempio, se carichi il resto di un oggetto con una dimensione totale di 20000000 che è stato interrotto dopo il caricamento dei byte 0-42, UPLOAD_SIZE_REMAINING sarà 19999957.
    • NEXT_BYTE è il numero intero successivo al valore salvato nel passaggio 2. Ad esempio, se 42 è il valore superiore 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. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione quando hai avviato il caricamento ripristinabile.

API XML

  1. Controlla lo stato del caricamento ripristinabile.

  2. Salva il valore superiore dell'Rangeintestazione contenuta nella risposta al controllo dello stato. Se la risposta non ha un'Range intestazione, Cloud Storage non ha ancora reso persistenti i 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 la API XML con una PUT Object richiesta che riprende 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 che stai caricando nella richiesta corrente. Ad esempio, se carichi il resto di un oggetto con una dimensione totale di 20000000 che è stato interrotto dopo il caricamento dei byte 0-42, UPLOAD_SIZE_REMAINING sarà 19999957.
    • NEXT_BYTE è il numero intero successivo al valore salvato nel passaggio 2. Ad esempio, se 42 è il valore superiore 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. Se non conosci la dimensione completa dell'oggetto, utilizza * per questo valore.
    • SESSION_URI è il valore restituito nell' Location intestazione 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. Quando i dati vengono 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

  1. Utilizza cURL per chiamare l'API JSON con una 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 499. I tentativi futuri di eseguire query o riprendere il caricamento restituiscono una risposta 4xx.

API XML

  1. Utilizza cURL per chiamare la API XML con una 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 anche i tentativi futuri di eseguire query o riprendere il caricamento restituiscono 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 riprovabile perché le autorizzazioni sul bucket sono cambiate o perché il controllo dell'integrità sull'oggetto caricato finale ha rilevato una mancata corrispondenza. In questo caso, riprova a caricare avviando una nuova sessione di caricamento ripristinabile.

Passaggi successivi