Oggetti compositi

Crea

Questa pagina descrive gli oggetti composti, che vengono creati da oggetti esistenti senza trasferire dati aggiuntivi degli oggetti. Gli oggetti composti 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 composto. Tutti gli oggetti di origine devono:

Quando esegui una composizione:

  • Gli oggetti di origine non vengono modificati.
  • Puoi utilizzare da 1 a 32 oggetti di origine.
  • Gli oggetti di origine possono essere oggetti composti.

L'oggetto composto risultante da una composizione:

  • Ha la stessa classe di archiviazione degli oggetti di origine.
  • 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 al Content-Type del primo oggetto di origine.

Metadati degli oggetti composti

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

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

    • Qualsiasi valore MD5 fornito come parte di una richiesta di composizione viene ignorato.

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

  • Ogni oggetto composto ha un campo di metadati conteggio componenti che conta il numero di oggetti non composti contenuti nell'oggetto composto.

    • Se riscrivi un oggetto composto in una posizione o classe di archiviazione diversa, il risultato è un oggetto composto con un conteggio componenti pari a 1.

Controllo dell'integrità degli oggetti composti

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

  • Quando carichi gli oggetti di origine, devi calcolare il CRC32C per ogni oggetto utilizzando una libreria CRC32C, ad esempio una di quelle elencate nella pagina Metadati degli oggetti, e includere questo valore nella richiesta. In base a i valori che fornisci, 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 come parte della richiesta di composizione. Nella risposta viene restituito un CRC32C dell'oggetto composto risultante.
  • Se la tua applicazione potrebbe modificare gli oggetti di origine tra il momento del caricamento e della composizione di questi oggetti, devi specificare nomi specifici per la generazione degli oggetti di origine per evitare condizioni di race. 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.

Aggiunta e modifica limitate

Puoi utilizzare l'operazione di composizione per eseguire aggiunte e modifiche limitate degli oggetti.

Per aggiungere dati, carica i dati in un nuovo oggetto temporaneo, componi l'oggetto a cui vuoi aggiungere i dati con questo oggetto temporaneo, facoltativamente assegna all'output dell'operazione di composizione lo stesso nome dell'oggetto originale ed elimina l'oggetto temporaneo.

Ad esempio, in gcloud CLI, la serie di comandi per aggiungere la stringa new data a un oggetto Cloud Storage esistente è la seguente:

$ echo 'new data' | gcloud storage cp - gs://bucket/temporary_object
$ gcloud storage objects compose gs://bucket/object_to_append gs://bucket/temporary_object \
    gs://bucket/object_to_append
$ gcloud storage rm gs://bucket/temporary_object

Puoi anche utilizzare la composizione per supportare una versione di base della modifica degli oggetti. Ad esempio, potresti comporre un oggetto X dalla sequenza {Y1, Y2, Y3}, sostituire i contenuti di Y2 e ricomporre X da questi stessi componenti. Tieni presente che questo richiede che Y1, Y2 e Y3 non vengano eliminati, quindi ti verrà addebitato il costo per questi componenti e per l'oggetto composto.

Contesti degli oggetti composti

Quando utilizzi l'operazione di composizione compose operation, Cloud Storage unisce tutti i contexts dagli oggetti di origine e li associa all'oggetto di destinazione. Questa procedura gestisce sia le chiavi di contesto univoche sia quelle duplicate, come descritto nelle sezioni seguenti.

Questo comportamento di unione è quello predefinito. 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 univoche

Se gli oggetti di origine hanno chiavi di contesto univoche, Cloud Storage associa direttamente queste chiavi e i relativi valori all'oggetto di destinazione.

Considera il seguente esempio:

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 dell'oggetto di origine B: 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 nel seguente modo:

  {
    "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