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 :

  • hérite 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.

    • Toute valeur MD5 que vous fournissez dans une requête de composition est ignorée.

  • 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 lorsque celui-ci est téléchargé. 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 listé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ù les objets résultants 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 modifications et ajouts d'objets limités.

Pour effectuer un ajout, vous devez importer des données dans un nouvel objet temporaire, composer l'objet que vous souhaitez ajouter à cet objet temporaire, attribuer à la sortie de l'opération de composition le même nom que pour l'objet d'origine, et supprimer l'objet temporaire.

Par exemple, dans la 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'objet composite

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 la gestion des 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 les 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 des 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 pour l'objet A, la valeur est Version: 1.0, alors que pour l'objet B, la valeur est 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