Oggetti compositi

Crea

Questa pagina descrive gli oggetti compositi, che vengono creati da oggetti esistenti senza trasferire dati aggiuntivi. Gli oggetti compositi sono utili per aggiungere dati a un oggetto esistente, nonché per ricreare oggetti che hai caricato come più componenti in parallelo.

Operazione di composizione

L'operazione di composizione concatena i dati in una determinata sequenza di oggetti di origine per creare un nuovo oggetto chiamato oggetto composito. Gli oggetti di origine devono soddisfare i seguenti requisiti:

• Tutti gli oggetti di origine devono avere la stessa classe di archiviazione.
• Tutti gli oggetti di origine devono essere archiviati nello stesso bucket Cloud Storage.

Quando esegui una composizione, tieni presente quanto segue:

• Se vuoi, puoi eliminare definitivamente gli oggetti di origine nell'ambito del processo di composizione. Utilizza questa opzione per ridurre al minimo la fatturazione per gli oggetti temporanei che non devono essere protetti dall'eliminazione temporanea o dal controllo delle versioni degli oggetti.
• Puoi comporre da 1 a 32 oggetti di origine.
• Gli oggetti di origine possono essere a loro volta oggetti compositi.

L'oggetto composito risultante da una composizione ha le seguenti caratteristiche:

• L'oggetto composito ha la stessa classe di archiviazione degli oggetti di origine.
• L'oggetto composito non cambia se gli oggetti di origine vengono successivamente sostituiti o eliminati.

Quando utilizzi gcloud storage per eseguire la composizione degli oggetti, l'oggetto risultante ha un Content-Type impostato in modo che corrisponda alla Content-Type del primo oggetto di origine.

Metadati degli oggetti compositi

Esistono diverse differenze tra i metadati di un oggetto composito e i metadati di altri oggetti:

• Gli oggetti compositi non hanno un campo di metadati hash MD5.

  • Qualsiasi valore MD5 fornito nell'ambito di una richiesta di composizione viene ignorato.

• Il valore ETag di un oggetto composito non si basa su un hash MD5 e il codice client non deve fare ipotesi sugli ETag degli oggetti compositi, se non che cambiano ogni volta che l'oggetto sottostante cambia in base alla specifica IETF per HTTP/1.1.

  Attenzione: presta attenzione quando utilizzi per la prima volta gli oggetti compositi, poiché i client che si aspettano di trovare un digest MD5 nell'intestazione ETag potrebbero concludere che i dati dell'oggetto sono stati danneggiati, il che potrebbe attivare infiniti tentativi di ritrasmissione dei dati.

• Ogni oggetto composito ha un campo dei metadati conteggio dei componenti, che conta il numero di oggetti non compositi contenuti nell'oggetto composito.

  • Se riscrivi un oggetto composito in una località o una classe di archiviazione diversa, il risultato è un oggetto composito con un conteggio dei componenti pari a 1.

Controllo dell'integrità degli oggetti compositi

Cloud Storage utilizza CRC32C per controllare l'integrità di ogni oggetto di origine al momento del caricamento e per consentire al chiamante di eseguire un controllo di integrità dell'oggetto composito risultante quando viene scaricato. CRC32C è un codice di rilevamento degli errori che può essere calcolato in modo efficiente dai valori CRC32C dei suoi componenti. L'applicazione deve utilizzare CRC32C come segue:

• Quando carichi gli oggetti di origine, devi calcolare il CRC32C per ogni oggetto utilizzando una libreria CRC32C, come una di quelle elencate nella pagina dei metadati degli oggetti, e includere questo valore nella richiesta. In base ai valori forniti, Cloud Storage convalida ogni caricamento.
• L'operazione di composizione verifica automaticamente che gli oggetti di origine siano assemblati correttamente e ignora qualsiasi valore CRC32C fornito nell'ambito della richiesta di composizione. Nella risposta viene restituito un CRC32C dell'oggetto composito risultante.
• Se la tua applicazione potrebbe modificare gli oggetti di origine tra il momento del caricamento e quello della composizione, devi specificare nomi specifici per la generazione degli oggetti di origine per evitare race condition. In alternativa, puoi creare un valore CRC32C dai valori CRC32C degli oggetti di origine previsti e confrontarlo con il valore CRC32C restituito dall'operazione di composizione.
• Al momento del download, devi calcolare il CRC32C dell'oggetto scaricato e confrontarlo con il valore incluso nella risposta.

Nota: CRC32C non è destinato a proteggere dagli attacchi "man-in-the-middle", in cui qualcuno modifica i contenuti in modo che corrispondano comunque al checksum fornito. La protezione da questi attacchi viene fornita utilizzando connessioni SSL durante il caricamento e il download di oggetti, che è l'impostazione predefinita per molti strumenti e librerie, come Google Cloud CLI.

Aggiungi e modifica

Puoi utilizzare l'operazione di composizione per aggiungere e modificare oggetti.

Per aggiungere dati a un oggetto esistente, devi prima creare un oggetto temporaneo che contiene i dati da aggiungere. Quindi, componi l'oggetto esistente con l'oggetto temporaneo. Nell'ambito del processo di composizione, puoi eliminare l'oggetto temporaneo e la versione precedente dell'oggetto originale. Puoi anche assegnare all'oggetto risultante lo stesso nome dell'oggetto originale.

Ad esempio, in gcloud CLI, i seguenti comandi aggiungono la stringa new data a un oggetto esistente:

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/existing_object gs://bucket/temporary_object \
    gs://bucket/existing_object --delete-source-objects

Attenzione: le operazioni di composizione creano una nuova versione di un oggetto. Quando esegui aggiunte in un bucket con il controllo delle versioni degli oggetti o l'eliminazione temporanea abilitati, assicurati di utilizzare l'opzione --delete-source-objects per evitare di creare versioni aggiuntive che comportano costi di archiviazione aggiuntivi.

Puoi anche utilizzare la composizione per supportare una versione di base della modifica degli oggetti. Ad esempio, puoi comporre un oggetto X dalla sequenza {Y1, Y2, Y3}, sostituire i contenuti di Y2 e ricomporre X dagli stessi componenti. Tieni presente che ciò richiede che Y1, Y2 e Y3 non vengano eliminati, quindi ti verranno addebitati i costi per questi componenti e per il composito.

Contesti degli oggetti compositi

Quando utilizzi l'operazione di composizione, Cloud Storage unisce tutti i contesti degli oggetti di origine e li associa all'oggetto di destinazione. Questo processo gestisce sia le chiavi di contesto univoche sia quelle duplicate, come descritto nelle sezioni seguenti.

Questo comportamento di unione è quello predefinito. Questo si verifica quando non specifichi i contesti per l'oggetto di destinazione nella richiesta di composizione. Puoi eseguire l'override di questo comportamento predefinito cancellando i contesti o specificando nuovi contesti per l'oggetto di destinazione durante l'operazione di composizione.

Chiavi di contesto uniche

Se gli oggetti di origine hanno chiavi di contesto univoche, Cloud Storage le associa direttamente, insieme ai valori corrispondenti, all'oggetto di destinazione.

Considera l'esempio seguente:

Contesti dell'oggetto di origine A: Department: Engineering, Status: Active

Contesti dell'oggetto di origine B: Owner: m_jones, Version: 1.1

Dopo l'operazione di composizione, l'oggetto di destinazione ha i seguenti contesti combinati:

  {
    "contexts": {
      "custom": {
        "Department": {
          "value": "Engineering",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Status": {
          "value": "Active",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        },
        "Version": {
          "value": "1.1",
          "createTime": "2023-10-26T10:00:00.000Z",
          "updateTime": "2023-10-26T10:00:00.000Z"
        }
      }
    }
  }
  

Chiavi di contesto duplicate

Quando più oggetti di origine hanno la stessa chiave di contesto, per l'oggetto composto viene utilizzato il valore dell'ultimo oggetto di origine nell'elenco di composizione che contiene la chiave.

Ad esempio, considera gli oggetti di origine elaborati nel seguente ordine:

1. Oggetto di origine A

2. Oggetto di origine B

Contesti dell'oggetto di origine A: Version: 1.0, ReleaseDate: 2024-01-15

Contesti B dell'oggetto di origine: Version: 1.1, Owner: m_jones

Entrambi gli oggetti di origine hanno una chiave Version, ma l'oggetto A ha Version: 1.0 e l'oggetto B ha Version: 1.1. Poiché Cloud Storage elabora l'oggetto di origine B dopo l'oggetto di origine A, il valore Version dell'oggetto di origine B ha la precedenza e il valore finale è 1.1.

L'oggetto di destinazione combina questi contesti come segue:

  {
    "contexts": {
      "custom": {
        "Version": {
          "value": "1.1",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "ReleaseDate": {
          "value": "2024-01-15",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        },
        "Owner": {
          "value": "m_jones",
          "createTime": "2025-01-01T00:00:00.000Z",
          "updateTime": "2025-01-01T00:00:00.000Z"
        }
      }
    }
  }
  

Passaggi successivi

• Componi un oggetto.
• Scopri di più sui caricamenti compositi paralleli.
• Scopri di più sui caricamenti multiparte, un modo alternativo per caricare oggetti in più blocchi per gli utenti dell'API XML.
• Scopri di più sui contesti degli oggetti.