Utilizzare i contesti degli oggetti

Riga di comando

Per collegare i contesti quando carichi oggetti con il comando gcloud alpha storage cp, utilizza il flag --custom-contexts:

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

Dove:

• OBJECT_LOCATION è il percorso locale dell'oggetto. Ad esempio, Desktop/dog.png.
• DESTINATION_BUCKET_NAME è il nome del bucket in cui stai caricando l'oggetto. Ad esempio, my-bucket.
• KEY è la chiave di contesto da allegare a un oggetto. Ad esempio, Department. Puoi specificare più coppie chiave-valore separate da virgole.
• VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.

In alternativa, crea un file JSON contenente i contesti che vuoi allegare agli oggetti e utilizza il flag --custom-contexts-file:

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

Dove:

• KEY è la chiave di contesto da allegare a un oggetto. Ad esempio, Department. Puoi specificare più coppie chiave-valore.
• VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.

Per allegare contesti quando carichi directory con il comando gcloud alpha storage rsync, utilizza il flag --custom-contexts o il flag --custom-contexts-file:

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

Dove:

• DIRECTORY_LOCATION è il percorso locale della tua directory. Ad esempio, ~/my_directory.
• DESTINATION_BUCKET_NAME è il nome del bucket in cui stai caricando la directory. Ad esempio, my-bucket.
• KEY è la chiave di contesto da collegare agli oggetti. Ad esempio, Department. Puoi specificare più coppie chiave-valore separate da virgole.
• VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.

API JSON

Per collegare i contesti agli oggetti quando carichi nuovi oggetti, utilizza uno dei seguenti metodi:

• Caricamenti multiparte

• Caricamenti ripristinabili

Come parte dei metadati dell'oggetto in formato JSON, includi il campo contexts:

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

Dove:

• KEY è la chiave di contesto da allegare a un oggetto. Ad esempio, Department. Puoi specificare più coppie chiave-valore nell'oggetto custom.
• VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.

Riga di comando

Utilizza il comando gcloud alpha storage objects update:

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

Dove:

• BUCKET_NAME è il nome del bucket che contiene l'oggetto per cui vuoi modificare il contesto. Ad esempio, my-bucket.
• OBJECT_NAME è il nome dell'oggetto. Ad esempio, pets/dog.png.

• CUSTOM_CONTEXTS_FLAG è uno dei seguenti flag:

  • Per sostituire tutti i contesti esistenti, utilizza --custom-contexts=KEY=VALUE,... o --custom-contexts-file=CUSTOM_CONTEXTS_FILE

    Dove:

    • KEY è la chiave di contesto da allegare a un oggetto. Ad esempio, Department. Puoi specificare più coppie chiave-valore separate da virgole.
    • VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.
    • CUSTOM_CONTEXTS_FILE è il percorso del file JSON o YAML che contiene i contesti da allegare all'oggetto.

  • Per eliminare tutti i contesti esistenti, utilizza --clear-custom-contexts.

  • Per aggiungere, modificare o eliminare singoli contesti, utilizza una combinazione di --update-custom-contexts=KEY=VALUE,... e --remove-custom-contexts=KEY,...

    Dove:

    • KEY è la chiave di contesto che vuoi allegare a un oggetto o eliminare da un oggetto. Ad esempio, Department.
    • VALUE è il valore da associare alla chiave di contesto che vuoi collegare a un oggetto. Ad esempio, Human resources.

Se l'operazione ha esito positivo, la risposta è simile al seguente esempio:

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

Librerie client

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. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Crea un file JSON contenente le impostazioni dell'oggetto, che deve includere i campi di configurazione contexts per l'oggetto.

   Per aggiungere, modificare o sovrascrivere i contesti esistenti, utilizza il seguente formato:

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

   Dove:

   • KEY è la chiave di contesto da allegare a un oggetto. Ad esempio, Department. Puoi specificare più coppie chiave-valore nell'oggetto custom.
   • VALUE è il valore da associare alla chiave di contesto. Ad esempio, Human resources.

   Per eliminare tutti i contesti esistenti, utilizza il seguente formato:

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

   Per eliminare una chiave specifica dal contesto, utilizza il seguente formato:

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

   Dove:

   KEY è la chiave di contesto che vuoi eliminare da un oggetto. Ad esempio, Department. Puoi specificare più chiavi da eliminare dall'oggetto custom.

3. Utilizza cURL per chiamare l'API JSON con una richiesta di PATCH oggetto:

   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"

   Dove:

   • JSON_FILE_NAME è il percorso del file che include le informazioni sui contesti degli oggetti.
   • BUCKET_NAME è il nome del bucket che contiene l'oggetto per cui vuoi modificare il contesto. Ad esempio, my-bucket.
   • OBJECT_NAME è il nome codificato nell'URL dell'oggetto. Ad esempio, pets/dog.png viene codificato nell'URL come pets%2Fdog.png.

In alternativa, puoi sostituire il contesto di un oggetto con una richiesta PUT Object. La richiesta dell'oggetto PUT sostituisce anche altri metadati dell'oggetto. Pertanto, non consigliamo di utilizzare la richiesta di oggetti PUT.

Riga di comando

Utilizza il comando gcloud alpha storage objects describe:

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Dove:

• BUCKET_NAME è il nome del bucket contenente l'oggetto di cui vuoi visualizzare il contesto. Ad esempio, my-bucket.
• OBJECT_NAME è il nome dell'oggetto di cui vuoi visualizzare il contesto. Ad esempio, pets/dog.png

Se l'operazione ha esito positivo, la risposta è simile al seguente esempio:

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

Librerie client

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. Avere gcloud CLI installata e inizializzata, il che ti consente di generare un token di accesso per l'intestazione Authorization.

2. Utilizza cURL per chiamare l'API JSON con una richiesta di GET oggetto:

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

   Dove:

   • BUCKET_NAME è il nome del bucket che contiene l'oggetto di cui vuoi visualizzare il contesto. Ad esempio, my-bucket.
   • OBJECT_NAME è il nome codificato tramite URL dell'oggetto di cui vuoi visualizzare il contesto. Ad esempio, pets/dog.png, codificato come URL pets%2Fdog.png.

   Se l'operazione ha esito positivo, la risposta è simile al seguente esempio:

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

Riga di comando

I comandi gcloud alpha storage cp, gcloud alpha storage rsync e gcloud alpha storage mv conservano i contesti dell'oggetto di origine per impostazione predefinita. Per modificare i contesti durante queste operazioni, utilizza uno dei seguenti flag:

• I flag --custom-contexts o --custom-contexts-file per impostare nuovi contesti per l'oggetto di destinazione.
• Il flag --clear-custom-contexts per impedire che i contesti dell'oggetto origine vengano allegati all'oggetto di destinazione.
• Una combinazione dei flag --update-custom-contexts e --remove-custom-contexts per modificare i singoli contesti dell'oggetto origine prima di collegarli all'oggetto di destinazione.

Il comando gcloud alpha storage objects compose unisce i contesti degli oggetti di origine e li collega agli oggetti di destinazione per impostazione predefinita. Cloud Storage risolve i conflitti dando la priorità ai contesti degli oggetti di origine elaborati in un secondo momento. Per ulteriori informazioni sul comportamento del contesto dell'oggetto durante un'operazione di composizione, consulta Contesti degli oggetti compositi. Puoi anche specificare nuovi contesti per l'oggetto di destinazione utilizzando i flag --custom-contexts o --custom-contexts-file.

API JSON

• Per modificare i contesti durante un'operazione di copia o riscrittura di un oggetto, includi la proprietà contexts.custom nel corpo della richiesta. Se non includi questa proprietà, i contesti dell'oggetto di origine vengono conservati per impostazione predefinita.

• Quando componi gli oggetti, i contesti degli oggetti di origine vengono uniti nell'oggetto di destinazione per impostazione predefinita. Cloud Storage risolve i conflitti dando la priorità ai contesti degli oggetti di origine elaborati in un secondo momento. Per saperne di più sul comportamento del contesto dell'oggetto durante un'operazione di composizione, consulta Contesti degli oggetti compositi. Puoi anche specificare nuovi contesti per l'oggetto di destinazione nella proprietà destination.contexts.custom.