Utilizzare i contesti degli oggetti

Questa pagina descrive come allegare e gestire i contesti sugli oggetti Cloud Storage sotto forma di coppie chiave-valore.

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per creare e gestire i contesti degli oggetti, chiedi all'amministratore di concederti i seguenti ruoli IAM sull'oggetto:

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare e gestire i contesti degli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare e gestire i contesti degli oggetti sono necessarie le seguenti autorizzazioni:

  • Crea un oggetto con contesti dell'oggetto:
    • storage.objects.create
    • storage.objects.createContext
  • Allegare, aggiornare ed eliminare i contesti degli oggetti:
    • storage.objects.update
    • storage.objects.createContext
    • storage.objects.updateContext
    • storage.objects.deleteContext
  • Visualizza i contesti degli oggetti:
    • storage.objects.get
    • storage.objects.list

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Allegare contesti a nuovi oggetti

Collega i contesti agli oggetti quando carichi nuovi oggetti nei bucket Cloud Storage. Ogni contesto è composto da una chiave e un valore.

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:

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.

Allegare o modificare i contesti di un oggetto esistente

Puoi collegare nuovi contesti agli oggetti esistenti nei bucket Cloud Storage.

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

Java

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le 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.googleapis.com/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.

Visualizzare i contesti degli oggetti

Puoi visualizzare i contesti di un oggetto elencando i metadati dell'oggetto o descrivendo un oggetto specifico.

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

Java

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le 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.googleapis.com/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"
        }
      }
    }
  }

Filtrare gli oggetti per contesti

Filtra gli oggetti in base all'esistenza di chiavi di contesto dell'oggetto o ai relativi valori specifici. Il filtraggio degli oggetti per contesti consente di individuare e gestire in modo efficiente gruppi particolari di oggetti. Per maggiori dettagli, vedi Filtrare gli oggetti per contesti.

Gestisci i contesti degli oggetti durante le operazioni sugli oggetti

I contesti degli oggetti vengono conservati per impostazione predefinita quando copi, riscrivi, componi, sposti o ripristini gli oggetti. Puoi anche modificare i contesti durante le operazioni di copia, riscrittura e composizione.

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.

Passaggi successivi