Utiliser les contextes d'objet

Ligne de commande

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

gcloud alpha 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/dog.png
• DESTINATION_BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre objet. Exemple : my-bucket.
• 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

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 est 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 alpha storage rsync, utilisez l'indicateur --custom-contexts ou --custom-contexts-file :

gcloud alpha 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 est 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 importez de nouveaux objets, utilisez l'une des méthodes suivantes :

• Importations en plusieurs parties

• Importations avec reprise

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

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

Où :

• KEY est 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

Ligne de commande

Exécutez la commande gcloud alpha storage objects update :

gcloud alpha 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 : pets/dog.png.

• 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 est la valeur à associer à la clé de contexte. Exemple :Human resources
    • CUSTOM_CONTEXTS_FILE est le 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 --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 associer à un objet. Exemple : Human resources.

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

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

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

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

2. 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 est la clé de contexte à associer à un objet. Exemple :Department Vous pouvez spécifier plusieurs paires clé/valeur dans l'objet custom.
   • VALUE est 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 est 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.

3. Utilisez cURL pour appeler l'API JSON avec une requête PATCH Object :

   curl -X PATCH --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

   Où :

   • JSON_FILE_NAME est le 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. Par exemple, pets/dog.png est encodé au format URL sous la forme pets%2Fdog.png.

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.

Ligne de commande

Exécutez la commande gcloud alpha storage objects describe :

gcloud alpha 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, pets/dog.png.

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: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

Bibliothèques clientes

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

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

2. Utilisez cURL pour appeler l'API JSON avec une requête GET Object :

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.s3nsapis.fr/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. Par exemple, pets/dog.png, encodé au format URL : pets%2Fdog.png.

   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": "HR",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           },
           "DataClassification": {
             "value": "Confidential",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           }
         }
       }
     }
     

Ligne de commande

Les commandes gcloud alpha storage cp, gcloud alpha storage rsync et gcloud alpha 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 :

• Indicateurs --custom-contexts ou --custom-contexts-file permettant de définir de nouveaux contextes pour l'objet de destination.
• L'indicateur --clear-custom-contexts pour 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.

La commande gcloud alpha storage objects compose fusionne les contextes des objets sources et les associe 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. Vous pouvez également spécifier de nouveaux contextes pour l'objet de destination à l'aide des indicateurs --custom-contexts ou --custom-contexts-file.

API JSON

• Pour modifier les contextes lors d'une opération d'objet copy ou rewrite, incluez la propriété contexts.custom dans le corps de la requête. Si vous n'incluez pas cette propriété, les contextes de l'objet source sont conservés par défaut.

• Lorsque vous composez des objets, les contextes des objets sources sont fusionnés dans l'objet 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. Vous pouvez également spécifier de nouveaux contextes pour l'objet de destination dans la propriété destination.contexts.custom.