Utiliser les contextes d'objet

Cette page explique comment associer et gérer des contextes sur des objets Cloud Storage sous forme de paires clé-valeur.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des contextes d'objet, demandez à votre administrateur de vous accorder les rôles IAM suivants sur l'objet :

Créer des objets avec des contextes : Créateur d'objets de l'espace de stockage (roles/storage.objectCreator)
Associer, modifier, afficher et supprimer des contextes d'objets : Utilisateur des objets Storage (roles/storage.objectUser)
Afficher les clés et valeurs de contexte associées aux objets : Lecteur des objets Storage (roles/storage.objectViewer)
Supprimer les contextes d'objet lors des opérations de réécriture, de copie et de composition : Propriétaire des anciens objets de l'espace de stockage (roles/storage.legacyObjectOwner)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour créer et gérer des contextes d'objet. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour créer et gérer des contextes d'objet :

Créez un objet avec des contextes d'objet :
- storage.objects.create
- storage.objects.createContext
Associer, mettre à jour et supprimer des contextes d'objet :
- storage.objects.update
- storage.objects.createContext
- storage.objects.updateContext
- storage.objects.deleteContext
Contextes de l'objet déposé : storage.objects.dropContexts
Afficher les contextes d'objet :
- storage.objects.get
- storage.objects.list

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Associer des contextes à de nouveaux objets

Associez des contextes à des objets lorsque vous importez de nouveaux objets dans des buckets Cloud Storage. Chaque contexte se compose d'une clé et d'une valeur.

Ligne de commande

Pour associer des contextes lorsque vous importez des objets avec la commande gcloud storage cp, utilisez l'option --custom-contexts :

gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

Où :

OBJECT_LOCATION correspond au chemin d'accès local à votre objet. Exemple : Desktop/employees.txt.
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre objet. Exemple : my-bucket.
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

Vous pouvez également créer un fichier JSON contenant les contextes que vous souhaitez associer aux objets, puis utiliser l'indicateur --custom-contexts-file :

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

Où :

KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

Pour associer des contextes lorsque vous importez des répertoires avec la commande gcloud storage rsync, utilisez l'indicateur --custom-contexts ou --custom-contexts-file :

gcloud storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

Où :

DIRECTORY_LOCATION correspond au chemin d'accès local à votre répertoire. Exemple :~/my_directory
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre répertoire. Exemple : my-bucket.
KEY correspond à la clé de contexte à associer aux objets. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

API JSON

Pour associer des contextes à des objets lorsque vous en importez de nouveaux, utilisez l'une des méthodes suivantes :

Dans les métadonnées de l'objet au format JSON, incluez le champ contexts :

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Où :

KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur dans l'objet custom.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

Associer ou modifier des contextes pour un objet existant

Vous pouvez associer de nouveaux contextes à vos objets existants dans les buckets Cloud Storage.

Ligne de commande

Exécutez la commande gcloud storage objects update :

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

Où :

BUCKET_NAME correspond au nom du bucket contenant l'objet dont vous souhaitez modifier le contexte. Exemple : my-bucket.
OBJECT_NAME correspond au nom de l'objet. Exemple : employees.txt.
CUSTOM_CONTEXTS_FLAG est l'un des indicateurs suivants :
- Pour remplacer tous les contextes existants, utilisez --custom-contexts=KEY=VALUE,... ou --custom-contexts-file=CUSTOM_CONTEXTS_FILE.
  
  Où :
  - KEY est la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
  - VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources
  - CUSTOM_CONTEXTS_FILE correspond au chemin d'accès au fichier JSON ou YAML contenant les contextes que vous souhaitez associer à l'objet.
- Pour supprimer tous les contextes existants, utilisez l'option --clear-custom-contexts.
- Pour ajouter, modifier ou supprimer des contextes individuels, utilisez une combinaison de --update-custom-contexts=KEY=VALUE,... et --remove-custom-contexts=KEY,....
  
  Où :
  - KEY correspond à la clé de contexte que vous souhaitez associer à un objet ou en supprimer. Exemple :Department
  - VALUE correspond à la valeur à associer à la clé de contexte que vous souhaitez joindre à un objet ou en supprimer. Exemple : Human resources.

Si l'opération réussit, la réponse se présente comme suit :

Patching gs://my-bucket/employees.txt#1560574162144861...
  Completed 1

Bibliothèques clientes

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour les bibliothèques clientes.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

API JSON

Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Créez un fichier JSON contenant les paramètres de l'objet, qui doit inclure les champs de configuration contexts pour l'objet.

Pour ajouter, modifier ou remplacer des contextes existants, utilisez le format suivant :

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Où :

KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur dans l'objet custom.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple : Human resources.

Pour supprimer tous les contextes existants, utilisez le format suivant :

  {
    "contexts": {
      "custom": null
    }
  }

Pour supprimer une clé spécifique du contexte, utilisez le format suivant :

  {
    "contexts": {
      "custom": {
        "KEY": null,
        ...
      }
    }
  }

Où :

KEY correspond à la clé de contexte que vous souhaitez supprimer d'un objet. Exemple :Department Vous pouvez spécifier plusieurs clés à supprimer de l'objet custom.

Utilisez cURL pour appeler l'API JSON avec une requête d'objet PATCH :
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier contenant les informations sur les contextes d'objet.
- BUCKET_NAME correspond au nom du bucket contenant l'objet dont vous souhaitez modifier le contexte. Exemple : my-bucket.
- OBJECT_NAME correspond au nom encodé au format URL de l'objet. Exemple :employees.txt

Vous pouvez également remplacer le contexte d'un objet par une requête PUT Object. La requête d'objet PUT remplace également les autres métadonnées d'objet. Par conséquent, nous vous déconseillons d'utiliser la requête d'objet PUT.

Afficher les contextes d'objet

Vous pouvez afficher les contextes d'un objet en listant les métadonnées de l'objet ou en décrivant un objet spécifique.

Ligne de commande

Exécutez la commande gcloud storage objects describe :

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Où :

BUCKET_NAME correspond au nom du bucket contenant l'objet dont vous souhaitez afficher le contexte. Exemple :my-bucket
OBJECT_NAME correspond au nom de l'objet dont vous souhaitez afficher le contexte. Par exemple, employees.txt.

Si l'opération réussit, la réponse se présente comme suit :

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Human resources
name: employees.txt

Bibliothèques clientes

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

API JSON

Vous devez installer et initialiser gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Utilisez cURL pour appeler l'API JSON avec une requête d'objet GET :

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

Où :

BUCKET_NAME correspond au nom du bucket contenant l'objet dont vous souhaitez afficher le contexte. Exemple : my-bucket.
OBJECT_NAME correspond au nom encodé en URL de l'objet dont vous souhaitez afficher le contexte. Exemple :employees.txt

Si l'opération réussit, la réponse se présente comme suit :

  {
    "kind": "storage#object",
    "name": "employees.txt",
    "bucket": "my-bucket",
    "contexts": {
      "custom": {
        "Department": {
          "value": "Human resources",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        }
      }
    }
  }

Filtrer les objets par contexte

Filtrez les objets en fonction de l'existence de clés de contexte d'objet ou de leurs valeurs spécifiques. Filtrer les objets par contexte permet de localiser et de gérer efficacement des groupes d'objets spécifiques. Pour en savoir plus, consultez Filtrer les objets par contexte.

Gérer les contextes d'objet lors des opérations sur les objets

Par défaut, Cloud Storage conserve les contextes d'objet lorsque vous copiez, réécrivez, composez, déplacez ou restaurez des objets.

Copier des objets

Par défaut, Cloud Storage conserve les contextes d'objet de l'objet source lors d'une opération de copie, même si vous remplacez d'autres métadonnées. Pour modifier les contextes d'objet lors d'une opération de copie, procédez comme suit :

Ligne de commande

Les commandes gcloud storage cp, gcloud storage rsync et gcloud storage mv conservent les contextes de l'objet source par défaut. Pour modifier les contextes lors de ces opérations, utilisez l'un des indicateurs suivants :

L'indicateur --custom-contexts permet de définir de nouveaux contextes pour l'objet de destination.
L'indicateur --clear-custom-contexts permet d'empêcher l'association des contextes de l'objet source à l'objet de destination.
Combinaison des indicateurs --update-custom-contexts et --remove-custom-contexts permettant de modifier des contextes individuels de l'objet source avant de les associer à l'objet de destination.

Pour définir de nouveaux contextes lorsque vous copiez un objet, utilisez la commande gcloud storage cp :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :employees.txt
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :employees-backup.txt
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

Pour supprimer tous les contextes de l'objet source lorsque vous copiez un objet, utilisez la commande gcloud storage cp :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :pets/dog.png
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :pets/cat.png

Pour modifier des contextes individuels de l'objet source lorsque vous copiez un objet, utilisez la commande gcloud storage cp avec --update-custom-contexts et --remove-custom-contexts :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :pets/dog.png
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :pets/cat.png
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur ou clés séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

API JSON

Pour remplacer les contextes lors de la copie d'un objet, incluez la propriété contexts.custom dans le corps de la requête :

Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Créez un fichier JSON contenant les contextes à associer à l'objet de destination :

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }

Où :

KEY correspond à la clé de contexte à associer à un objet. Exemple : Department.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple : Human resources.

Exécutez cURL pour appeler l'API JSON avec une requête d'objet POST :
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier JSON qui inclut les informations sur les contextes d'objet.
- SOURCE_BUCKET_NAME est le nom du bucket contenant l'objet à copier. Exemple : my-source-bucket.
- SOURCE_OBJECT_NAME correspond au nom encodé au format URL de l'objet à copier. Exemple :employees.txt
- DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple : my-destination-bucket.
- DESTINATION_OBJECT_NAME correspond au nom encodé au format URL de l'objet de destination. Exemple :employees-backup.txt

Pour supprimer tous les contextes sources sans fournir de remplacement, utilisez le paramètre de requête dropContextGroups=custom dans votre requête :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Pour conserver les contextes, omettez la propriété contexts.custom dans le corps de la requête et excluez dropContextGroups=custom dans les paramètres de requête :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

Pour en savoir plus sur le comportement des contextes lors des opérations de copie, consultez le paramètre de requête dropContextGroups.

Réécrire des objets

Par défaut, Cloud Storage conserve les contextes d'objet de l'objet source lors d'une opération de réécriture, même si vous remplacez d'autres métadonnées. Pour modifier les contextes d'objet lors d'une opération de réécriture, procédez comme suit :

Ligne de commande

Les commandes gcloud storage cp, gcloud storage rsync et gcloud storage mv effectuent des réécritures automatiquement lorsque cela est nécessaire, par exemple lors de la copie d'objets entre différents emplacements ou classes de stockage. gcloud storage cp et gcloud storage rsync génèrent un objet source et un objet de destination, tandis que gcloud storage mv crée l'objet de destination et supprime l'objet source. Étant donné que ces opérations créent un nouvel objet, vous pouvez également modifier ou associer des contextes dans la même commande en utilisant l'un des indicateurs suivants :

L'indicateur --custom-contexts permet de définir de nouveaux contextes pour l'objet de destination.
L'indicateur --clear-custom-contexts permet d'empêcher l'association des contextes de l'objet source à l'objet de destination.
Combinaison des indicateurs --update-custom-contexts et --remove-custom-contexts permettant de modifier des contextes individuels de l'objet source avant de les associer à l'objet de destination.

Pour définir de nouveaux contextes lorsque vous copiez un objet, utilisez la commande gcloud storage cp :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :employees.txt
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :employees-backup.txt
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

Pour supprimer tous les contextes de l'objet source lorsque vous copiez un objet, utilisez la commande gcloud storage cp :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :pets/dog.png
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :pets/cat.png

Pour modifier des contextes individuels de l'objet source lorsque vous copiez un objet, utilisez la commande gcloud storage cp avec --update-custom-contexts et --remove-custom-contexts :

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Où :

SOURCE_BUCKET_NAME correspond au nom du bucket contenant l'objet à copier. Exemple :my-source-bucket
SOURCE_OBJECT_NAME correspond au nom de l'objet à copier. Exemple :pets/dog.png
DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel copier l'objet. Exemple :my-destination-bucket
DESTINATION_OBJECT_NAME correspond au nom de l'objet de destination. Exemple :pets/cat.png
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur ou clés séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple :Human resources

API JSON

Pour remplacer les contextes lors de la réécriture d'un objet, incluez la propriété contexts.custom dans le corps de la requête :

Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Créez un fichier JSON contenant les contextes à associer à l'objet de destination :

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }

Où :

KEY correspond à la clé de contexte à associer à un objet. Par exemple : Department.
VALUE correspond à la valeur à associer à la clé de contexte. Par exemple : Human resources.

Utilisez cURL pour appeler l'API JSON avec une requête d'objet POST de réécriture :
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier JSON qui inclut les informations sur les contextes d'objet.
- SOURCE_BUCKET_NAME est le nom du bucket contenant l'objet à réécrire. Exemple :my-source-bucket
- SOURCE_OBJECT_NAME correspond au nom encodé en URL de l'objet à réécrire. Exemple :employees.txt
- DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel réécrire l'objet. Exemple :my-destination-bucket
- DESTINATION_OBJECT_NAME correspond au nom encodé au format URL de l'objet de destination. Exemple :employees-backup.txt

Pour supprimer tous les contextes sources sans fournir de remplacement, utilisez le paramètre de requête dropContextGroups=custom dans votre requête :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Pour conserver les contextes, omettez la propriété contexts.custom du corps de la requête et excluez dropContextGroups=custom dans les paramètres de requête :

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

Pour en savoir plus sur le comportement des contextes lors des opérations de réécriture, consultez le paramètre de requête dropContextGroups.

Composer des objets

La commande gcloud storage objects compose et la méthode compose de l'API JSON fusionnent les contextes des objets sources et les associent aux objets de destination par défaut. Cloud Storage résout les conflits en donnant la priorité aux contextes des objets sources traités ultérieurement. Pour en savoir plus sur le comportement du contexte d'objet lors d'une opération de composition, consultez Contextes d'objets composites.

Ligne de commande

Pour spécifier de nouveaux contextes pour l'objet de destination lors de la composition d'objets, utilisez l'option --contexts :

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --contexts=KEY=VALUE,...

Où :

BUCKET_NAME est le nom du bucket qui contient les objets sources et dans lequel l'objet de destination est créé. Exemple :my-bucket
SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont des objets sources à composer.
DESTINATION_OBJECT_NAME est le nom de l'objet de destination à créer. Exemple :my-composite-object
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur séparées par des virgules.
VALUE correspond à la valeur à associer à la clé de contexte. Exemple : Human resources.

Pour empêcher l'association de contextes sources à des objets composites, utilisez l'option --clear-custom-contexts :

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Où :

BUCKET_NAME est le nom du bucket qui contient les objets sources et dans lequel l'objet de destination est créé. Exemple :my-bucket
SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont les objets sources à composer.
DESTINATION_OBJECT_NAME est le nom de l'objet de destination à créer. Exemple :my-composite-object

API JSON

Pour spécifier de nouveaux contextes pour l'objet de destination lors de la composition d'objets, incluez des contextes dans la propriété destination du corps de la requête.

Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Créez un fichier JSON contenant le corps de la requête :

{
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain",
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }
}

Où :

SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont des objets sources à composer.
KEY correspond à la clé de contexte à associer à un objet. Exemple :Department
VALUE correspond à la valeur à associer à la clé de contexte. Exemple : Human resources.

Utilisez cURL pour appeler l'API JSON avec une requête d'objet POST compose :
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/DESTINATION_OBJECT_NAME/compose"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier JSON qui inclut le corps de la requête.
- BUCKET_NAME est le nom du bucket qui contient les objets sources et où l'objet de destination sera créé. Exemple :my-bucket
- DESTINATION_OBJECT_NAME est le nom de l'objet de destination à créer. Exemple :my-composite-object

Pour éviter que des contextes sources soient associés à des objets composites, utilisez le paramètre de requête dropContextGroups=custom dans votre requête :

Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

Créez un fichier JSON contenant le corps de la requête :

{
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain"
}
}

Où :

SOURCE_OBJECT_1 et SOURCE_OBJECT_2 sont des objets sources à composer.

Utilisez cURL pour appeler l'API JSON avec une requête d'objet POST compose :
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/DESTINATION_OBJECT_NAME/compose?dropContextGroups=custom"
```
Où :
- JSON_FILE_NAME correspond au chemin d'accès au fichier JSON qui inclut le corps de la requête.
- BUCKET_NAME est le nom du bucket qui contient les objets sources et où l'objet de destination sera créé. Exemple :my-bucket
- DESTINATION_OBJECT_NAME est le nom de l'objet de destination à créer. Exemple :my-composite-object

Étapes suivantes

Découvrez les propriétés du contexte d'objet dans la documentation de l'API Cloud Storage.

Utiliser les contextes d'objet Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Obtenir les rôles requis

Autorisations requises

Associer des contextes à de nouveaux objets

Ligne de commande

API JSON

Associer ou modifier des contextes pour un objet existant

Ligne de commande

Bibliothèques clientes

Java

API JSON

Afficher les contextes d'objet

Ligne de commande

Bibliothèques clientes

Java

API JSON

Filtrer les objets par contexte

Gérer les contextes d'objet lors des opérations sur les objets

Copier des objets

Ligne de commande

API JSON

Réécrire des objets

Ligne de commande

API JSON

Composer des objets

Ligne de commande

API JSON

Étapes suivantes

Utiliser les contextes d'objet