Objets composites

Créer

Cette page décrit les objets composites, que vous créez à partir d'objets existants sans transférer de données d'objet supplémentaires. Les objets composites sont utiles pour ajouter des éléments à un objet existant, ainsi que pour recréer des objets que vous avez importés en parallèle sous la forme de composants multiples.

Opération de composition

L'opération de composition concatène les données dans une séquence donnée d'objets sources pour créer un objet appelé objet composite. Les objets sources doivent tous :

  • appartenir à la même classe de stockage ;
  • être stockés dans le même bucket Cloud Storage ;

Lorsque vous effectuez une composition :

  • Les objets sources ne sont pas affectés.
  • Vous pouvez utiliser entre 1 et 32 objets sources.
  • Les objets sources peuvent eux-mêmes être des objets composites.

L'objet composite résultant d'une composition :

  • Dispose de la même classe de stockage que les objets sources.
  • Ne change pas si les objets sources sont remplacés ou supprimés par la suite.

Lorsque vous utilisez gcloud storage pour effectuer une composition d'objet, la valeur Content-Type de l'objet obtenu correspond à la valeur Content-Type du premier objet source.

Métadonnées des objets composites

Il existe plusieurs différences entre les métadonnées d'un objet composite et les métadonnées des autres objets :

  • Les objets composites ne possèdent pas de champ de métadonnées de hachage MD5.

  • La valeur ETag d'un objet composite n'est pas basée sur un hachage MD5, et le code client ne doit faire aucune hypothèse concernant les ETags des objets composites, si ce n'est qu'ils changent chaque fois que l'objet sous-jacent est modifié conformément à la spécification IETF pour HTTP/1.1.

  • Chaque objet composite possède un champ de métadonnées nombre de composants, qui compte le nombre d'objets non composites contenus dans l'objet composite.

    • Si vous réécrivez un objet composite dans un autre emplacement ou une autre classe de stockage, vous obtenez alors un objet composite avec un nombre de composants égal à 1.

Contrôle de l'intégrité des objets composites

Cloud Storage utilise CRC32C pour contrôler l'intégrité de chaque objet source lors de l'importation et pour permettre à l'utilisateur à l'origine de l'appel d'effectuer le même type de contrôle sur l'objet composite obtenu lors de son téléchargement. CRC32C est un code de détection d'erreur pouvant être calculé efficacement à partir des valeurs CRC32C de ses composants. Votre application doit utiliser CRC32C comme suit :

  • Lorsque vous importez des objets sources, calculez le code CRC32C pour chaque objet à l'aide d'une bibliothèque CRC32C (telle que l'une de celles affichées sur la page Métadonnées d'objet) et incluez cette valeur dans votre requête. En fonction des valeurs que vous fournissez, Cloud Storage valide chaque importation.
  • L'opération de composition vérifie automatiquement que les objets sources sont correctement assemblés et ignore toute valeur CRC32C que vous fournissez dans la requête de composition. Un code CRC32C de l'objet composite obtenu est renvoyé dans la réponse.
  • Si votre application peut modifier les objets sources entre le moment où ils sont importés et le moment où ils sont composés, spécifiez des noms propres aux générations pour les objets sources afin d'éviter les conditions de concurrence. Vous pouvez également créer une valeur CRC32C à partir des valeurs CRC32C des objets sources prévus et les comparer à la valeur CRC32C renvoyée par l'opération de composition.
  • Lors du téléchargement, calculez le code CRC32C de l'objet téléchargé et comparez-le à la valeur incluse dans la réponse.

Ajouts et modifications limités

Vous pouvez utiliser l'opération de composition pour effectuer des ajouts et des modifications d'objets limités.

Pour effectuer un ajout, vous devez importer des données à un nouvel objet temporaire, composer l'objet que vous souhaitez ajouter avec cet objet temporaire, nommer la sortie de l'opération de composition comme l'objet d'origine (facultatif) et supprimer l'objet temporaire.

Par exemple, dans gcloud CLI, la série de commandes permettant d'ajouter la chaîne new data à un objet Cloud Storage existant est la suivante :

$ 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

Vous pouvez également utiliser la composition pour apporter des modifications élémentaires aux objets. Par exemple, vous avez la possibilité de composer un objet X à partir de la séquence {Y1, Y2, Y3}, de remplacer le contenu de Y2 et de recomposer X à partir des mêmes composants. Notez que cette opération nécessite que Y1, Y2 et Y3 ne soient pas supprimés. Ces composants, ainsi que l'objet composite, vous seront donc facturés.

Contextes d'objets composites

Lors d'une opération de composition d'objet, Cloud Storage fusionne tous les contextes (aperçu) des objets sources et les associe à l'objet de destination. Les contextes sont fusionnés pour gérer les clés de contexte uniques et en double, comme décrit dans les sections suivantes.

Clés de contexte uniques

Si les objets sources ont des clés de contexte uniques, Cloud Storage associe directement ces clés et leurs valeurs correspondantes à l'objet de destination.

Prenons l'exemple suivant :

Contextes de l'objet source A : Department: Engineering, Status: Active

Contextes de l'objet source B : Owner: m_jones, Version: 1.1

Après l'opération de composition, l'objet de destination présente les contextes combinés suivants :

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

Clés de contexte en double

Lorsque plusieurs objets sources ont la même clé de contexte, la valeur du dernier objet traité par Cloud Storage remplace les valeurs des objets traités précédemment.

Par exemple, considérons les objets sources traités dans l'ordre suivant :

  1. Objet source A

  2. Objet source B

Contextes de l'objet source A : Version: 1.0, ReleaseDate: 2024-01-15

Contextes de l'objet source B : Version: 1.1, Owner: m_jones

Les deux objets sources ont une clé Version, mais l'objet A a Version: 1.0 et l'objet B a Version: 1.1. Étant donné que Cloud Storage traite l'objet source B après l'objet source A, la valeur Version de l'objet source B est prioritaire et la valeur finale est 1.1.

L'objet de destination combine ces contextes comme suit :

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

Étapes suivantes