Use contextos de objetos

Esta página descreve como anexar e gerir contextos em objetos do Cloud Storage sob a forma de pares de chave-valor.

Obtenha as funções necessárias

Para receber as autorizações de que precisa para criar e gerir contextos de objetos, peça ao seu administrador para lhe conceder as seguintes funções de IAM no objeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para criar e gerir contextos de objetos. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar e gerir contextos de objetos:

  • Crie um objeto com contextos de objetos:
    • storage.objects.create
    • storage.objects.createContext
  • Anexe, atualize e elimine contextos de objetos:
    • storage.objects.update
    • storage.objects.createContext
    • storage.objects.updateContext
    • storage.objects.deleteContext
  • Ver contextos de objetos:
    • storage.objects.get
    • storage.objects.list

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Anexe contextos a novos objetos

Anexe contextos a objetos quando carregar novos objetos para contentores do Cloud Storage. Cada contexto consiste numa chave e num valor.

Linha de comandos

Para anexar contextos quando carrega objetos com o comando gcloud alpha storage cp, use a flag --custom-contexts:

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

Onde:

  • OBJECT_LOCATION é o caminho local para o seu objeto. Por exemplo, Desktop/dog.png.
  • DESTINATION_BUCKET_NAME é o nome do contentor para o qual está a carregar o seu objeto. Por exemplo, my-bucket.
  • KEY é a chave de contexto a anexar a um objeto. Por exemplo, Department. Pode especificar vários pares de chave-valor separados por vírgulas.
  • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.

Em alternativa, crie um ficheiro JSON que contenha os contextos que quer anexar aos objetos e use a flag --custom-contexts-file:

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

Onde:

  • KEY é a chave de contexto a anexar a um objeto. Por exemplo, Department. Pode especificar vários pares de chave-valor.
  • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.

Para anexar contextos quando carrega diretórios com o comando gcloud alpha storage rsync, use a flag --custom-contexts ou a flag --custom-contexts-file:

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

Onde:

  • DIRECTORY_LOCATION é o caminho local para o seu diretório. Por exemplo, ~/my_directory.
  • DESTINATION_BUCKET_NAME é o nome do contentor para o qual está a carregar o seu diretório. Por exemplo, my-bucket.
  • KEY é a chave de contexto a anexar aos objetos. Por exemplo, Department. Pode especificar vários pares de chave-valor separados por vírgulas.
  • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.

API JSON

Para anexar contextos a objetos quando carrega novos objetos, use qualquer um dos seguintes métodos:

Como parte dos metadados do objeto no formato JSON, inclua o campo contexts:

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

Onde:

  • KEY é a chave de contexto a anexar a um objeto. Por exemplo, Department. Pode especificar vários pares de chave-valor no objeto custom.
  • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.

Anexe ou modifique contextos a um objeto existente

Pode anexar novos contextos aos objetos existentes nos contentores do Cloud Storage.

Linha de comandos

Use o comando gcloud alpha storage objects update:

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

Onde:

  • BUCKET_NAME é o nome do contentor que contém o objeto para o qual quer editar o contexto. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto. Por exemplo, pets/dog.png.

  • CUSTOM_CONTEXTS_FLAG é qualquer uma das seguintes flags:

    • Para substituir todos os contextos existentes, use --custom-contexts=KEY=VALUE,... ou --custom-contexts-file=CUSTOM_CONTEXTS_FILE

      Onde:

      • KEY é a chave de contexto a anexar a um objeto. Por exemplo, Department. Pode especificar vários pares de chave-valor separados por vírgulas.
      • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.
      • CUSTOM_CONTEXTS_FILE é o caminho para o ficheiro JSON ou YAML que contém os contextos que quer anexar ao objeto.

    • Para eliminar todos os contextos existentes, use --clear-custom-contexts.

    • Para adicionar, modificar ou eliminar contextos individuais, use uma combinação de --update-custom-contexts=KEY=VALUE,... e --remove-custom-contexts=KEY,...

      Onde:

      • KEY é a chave de contexto que quer anexar ou eliminar de um objeto. Por exemplo, Department.
      • VALUE é o valor a associar à chave de contexto que quer anexar a um objeto. Por exemplo, Human resources.

Se for bem-sucedido, a resposta é semelhante ao exemplo seguinte:

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

Bibliotecas cliente

Java

Para mais informações, consulte a documentação de referência da API Java do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 


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. Ter a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um ficheiro JSON que contenha as definições do objeto, que tem de incluir os campos de configuração contexts do objeto.

    Para adicionar, modificar ou substituir contextos existentes, use o seguinte formato:

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

    Onde:

    • KEY é a chave de contexto a anexar a um objeto. Por exemplo, Department. Pode especificar vários pares de chave-valor no objeto custom.
    • VALUE é o valor a associar à chave de contexto. Por exemplo, Human resources.

    Para eliminar todos os contextos existentes, use o seguinte formato:

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

    Para eliminar uma chave específica do contexto, use o seguinte formato:

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

    Onde:

    KEY é a chave de contexto que quer eliminar de um objeto. Por exemplo, Department. Pode especificar várias chaves para eliminar do objeto custom.

  3. Use cURL para chamar a API JSON com um pedido de PATCH objeto:

    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"

    Onde:

    • JSON_FILE_NAME é o caminho para o ficheiro que inclui as informações dos contextos de objetos.
    • BUCKET_NAME é o nome do contentor que contém o objeto para o qual quer editar o contexto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, pets/dog.png é codificado por URL como pets%2Fdog.png.

Em alternativa, pode substituir o contexto de um objeto por um pedido PUT Object. O pedido de objeto PUT também substitui outros metadados de objetos. Por conseguinte, não recomendamos a utilização do pedido de objeto PUT

Veja contextos de objetos

Pode ver os contextos de um objeto listando os metadados do objeto ou descrevendo um objeto específico.

Linha de comandos

Use o comando gcloud alpha storage objects describe:

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

Onde:

  • BUCKET_NAME é o nome do contentor que contém o objeto cujo contexto quer ver. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto cujo contexto quer ver. Por exemplo, pets/dog.png

Se for bem-sucedido, a resposta é semelhante ao seguinte exemplo:

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

Bibliotecas cliente

Java

Para mais informações, consulte a documentação de referência da API Java do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente. 


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. Ter a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com um pedido de GET objeto:

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

    Onde:

    • BUCKET_NAME é o nome do contentor que contém o objeto cujo contexto quer ver. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto cujo contexto quer ver. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.

    Se for bem-sucedido, a resposta é semelhante ao seguinte exemplo:

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

Filtre objetos por contextos

Filtre objetos pela existência de chaves de contexto de objetos ou pelos respetivos valores específicos. Filtrar objetos por contextos ajuda a localizar e gerir grupos de objetos específicos de forma eficiente. Para ver detalhes, consulte o artigo Filtre objetos por contextos.

Faça a gestão dos contextos de objetos durante as operações de objetos

Os contextos de objetos são preservados por predefinição quando copia, reescreve, compõe, move ou restaura objetos. Também pode modificar os contextos durante as operações de cópia, reescrita e composição.

Linha de comandos

O comando gcloud alpha storage cp, o comando gcloud alpha storage rsync e o comando gcloud alpha storage mv preservam os contextos do objeto de origem por predefinição. Para modificar contextos durante estas operações, use qualquer um dos seguintes indicadores:

  • Os indicadores --custom-contexts ou --custom-contexts-file para definir novos contextos para o objeto de destino.
  • O indicador --clear-custom-contexts para impedir que os contextos do objeto de origem sejam anexados ao objeto de destino.
  • Uma combinação das flags --update-custom-contexts e --remove-custom-contexts para modificar contextos individuais do objeto de origem antes de os anexar ao objeto de destino.

O comando gcloud alpha storage objects compose une os contextos dos objetos de origem e anexa-os aos objetos de destino por predefinição. O Cloud Storage resolve conflitos ao dar prioridade aos contextos de objetos de origem processados mais tarde. Para mais informações sobre o comportamento do contexto do objeto durante uma operação de composição, consulte o artigo Contextos de objetos compostos. Também pode especificar novos contextos para o objeto de destino através das flags --custom-contexts ou --custom-contexts-file.

API JSON

  • Para modificar contextos durante uma operação de objeto de cópia ou reescrita, inclua a propriedade contexts.custom no corpo do pedido. Se não incluir esta propriedade, os contextos do objeto de origem são preservados por predefinição.

  • Quando compõe objetos, os contextos dos objetos de origem são unidos no objeto de destino por predefinição. O Cloud Storage resolve conflitos ao dar prioridade aos contextos de objetos de origem processados mais tarde. Para mais informações sobre o comportamento do contexto do objeto durante uma operação de composição, consulte Contextos de objetos compostos. Também pode especificar novos contextos para o objeto de destino na propriedade destination.contexts.custom.

O que se segue?