Eseguire caricamenti ripristinabili

API JSON

1. Avere gcloud CLI installata e inizializzata, il che ti consente di 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 richiesta POST 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 elemento, 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 carichi l'oggetto. Ad esempio, my-bucket.
   • OBJECT_NAME è il nome con codifica URL che vuoi dare al tuo oggetto. Ad esempio, pets/dog.png, codificato come URL pets%2Fdog.png. Questo passaggio non è obbligatorio se hai incluso un name nel file dei metadati dell'oggetto nel passaggio 2.

   Se hai attivato la condivisione delle risorse tra origini, devi anche includere 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 della risposta alla richiesta dell'oggetto POST.

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

API XML

1. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Utilizza cURL per chiamare l'API XML con una richiesta POST Object che ha 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 metadati Content-Type dell'oggetto su application/octet-stream.
   • BUCKET_NAME è il nome del bucket in cui carichi l'oggetto. Ad esempio, my-bucket.
   • OBJECT_NAME è il nome con codifica URL che vuoi dare al tuo oggetto. Ad esempio, pets/dog.png, codificato come URL come pets%2Fdog.png.

   Se hai attivato la condivisione delle risorse tra origini, devi anche includere 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'intestazione location della risposta alla richiesta dell'oggetto POST.

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

API JSON

1. 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 nel tuo oggetto. Ad esempio, 20000000.
   • SESSION_URI è il valore restituito nell'intestazione location quando hai avviato il caricamento ripristinabile.

   Se vuoi, puoi includere intestazioni con il 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 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 nel tuo oggetto. Ad esempio, 20000000.
   • SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

API JSON

1. Crea un blocco di dati a partire 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 le dimensioni del chunk.

2. 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 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'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 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 caricare, utilizzando il valore superiore 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.

   Se vuoi, 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 a partire 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 le dimensioni del chunk.

2. 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 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'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 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 caricare, utilizzando il valore superiore 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.

API JSON

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

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

API JSON

1. Controlla lo stato del caricamento ripristinabile.

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 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 di oggetto PUT che inizia 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 della parte rimanente dei dati che vuoi caricare.
   • UPLOAD_SIZE_REMAINING è il numero di byte che stai caricando nella richiesta corrente. Ad esempio, il caricamento del resto di un oggetto con una dimensione totale di 20.000.000 che è stato interrotto dopo il caricamento dei byte 0-42 avrebbe un UPLOAD_SIZE_REMAINING di 19999957.
   • NEXT_BYTE è il numero intero successivo al valore che hai 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.
   • SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

API XML

1. Controlla lo stato del caricamento ripristinabile.

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 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 l'API XML con una richiesta di PUT Object che inizia 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 della parte rimanente dei dati che vuoi caricare.
   • UPLOAD_SIZE_REMAINING è il numero di byte che stai caricando nella richiesta corrente. Ad esempio, il caricamento del resto di un oggetto con una dimensione totale di 20.000.000 che è stato interrotto dopo il caricamento dei byte 0-42 avrebbe un UPLOAD_SIZE_REMAINING di 19999957.
   • NEXT_BYTE è il numero intero successivo al valore che hai 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.
   • SESSION_URI è il valore restituito nell'intestazione Location quando hai avviato il caricamento ripristinabile.

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:

   • 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. I tentativi futuri di eseguire query o riprendere il caricamento restituiscono una risposta 4xx.

API XML

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

In caso di esito positivo, la risposta contiene un codice di stato 204 e i tentativi futuri di eseguire query o riprendere il caricamento restituiscono anche una risposta 204.