Usar contextos de objeto

Nesta página, descrevemos como anexar e gerenciar contextos em objetos do Cloud Storage na forma de pares de chave-valor.

Ter os papéis necessários

Para receber as permissões necessárias para criar e gerenciar contextos de objetos, peça ao administrador para conceder a você os seguintes papéis do IAM no objeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar e gerenciar contextos de objetos. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar e gerenciar contextos de objetos:

  • Crie um objeto com contextos de objeto:
    • storage.objects.create
    • storage.objects.createContext
  • Anexe, atualize e exclua 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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Anexar contextos a novos objetos

Anexe contextos a objetos ao fazer upload de novos objetos para buckets do Cloud Storage. Cada contexto consiste em uma chave e um valor.

Linha de comando

Para anexar contextos ao fazer upload de 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,...

Em que:

  • OBJECT_LOCATION é o caminho local do objeto. Por exemplo, Desktop/dog.png.
  • DESTINATION_BUCKET_NAME é o nome do bucket de upload do objeto. Por exemplo, my-bucket.
  • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
  • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Outra opção é criar um arquivo JSON com os contextos que você quer anexar aos objetos e usar a flag --custom-contexts-file:

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

Em que:

  • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor.
  • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Para anexar contextos ao fazer upload de diretórios com o comando gcloud alpha storage rsync, use a sinalização --custom-contexts ou --custom-contexts-file:

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

Em que:

  • DIRECTORY_LOCATION é o caminho local para o diretório. Por exemplo, ~/my_directory.
  • DESTINATION_BUCKET_NAME é o nome do bucket de upload do diretório. Por exemplo, my-bucket.
  • KEY é a chave de contexto a ser anexada aos objetos. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
  • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

API JSON

Para anexar contextos a objetos ao fazer upload de 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"
        },
        ...
      }
    }
  }

Em que:

  • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor no objeto custom.
  • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

Anexar ou modificar contextos em um objeto

É possível anexar novos contextos aos objetos atuais nos buckets do Cloud Storage.

Linha de comando

Use o comando gcloud alpha storage objects update:

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

Em que:

  • BUCKET_NAME é o nome do bucket que contém o objeto para o qual você 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 atuais, use --custom-contexts=KEY=VALUE,... ou --custom-contexts-file=CUSTOM_CONTEXTS_FILE

      Em que:

      • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor separados por vírgulas.
      • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.
      • CUSTOM_CONTEXTS_FILE é o caminho para o arquivo JSON ou YAML que contém os contextos que você quer anexar ao objeto.

    • Para excluir todos os contextos atuais, use --clear-custom-contexts.

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

      Em que:

      • KEY é a chave de contexto que você quer anexar ou excluir de um objeto. Por exemplo, Department.
      • VALUE é o valor a ser associado à chave de contexto que você quer anexar a um objeto. Por exemplo, Human resources.

Se funcionar, a resposta será parecida com esta:

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

Bibliotecas de cliente

Java

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar 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 CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

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

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

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

    Em que:

    • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor no objeto custom.
    • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

    Para excluir todos os contextos atuais, use o seguinte formato:

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

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

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

    Em que:

    KEY é a chave de contexto que você quer excluir de um objeto. Por exemplo, Department. É possível especificar várias chaves para excluir do objeto custom.

  3. Use cURL para chamar a API JSON com uma solicitação de objeto PATCH:

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

    Em que:

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

Como alternativa, você pode substituir o contexto de um objeto por uma solicitação PUT Object. A solicitação de objeto PUT também substitui outros metadados de objeto. Portanto, não recomendamos usar a solicitação de objeto PUT.

Ver contextos de objetos

É possível conferir os contextos de um objeto listando os metadados dele ou descrevendo um objeto específico.

Linha de comando

Use o comando gcloud alpha storage objects describe:

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

Em que:

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

Se a operação for bem-sucedida, a resposta será semelhante a esta:

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 de cliente

Java

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar 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 CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com uma solicitação de objeto GET:

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

    Em que:

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

    Se a operação for bem-sucedida, a resposta será semelhante a esta:

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

Filtrar objetos por contextos

Filtre objetos pela existência de chaves de contexto de objeto ou pelos valores específicos deles. Filtrar objetos por contextos ajuda a localizar e gerenciar grupos específicos de objetos com eficiência. Para mais detalhes, consulte Filtrar objetos por contextos.

Gerenciar contextos de objetos durante operações de objetos

Os contextos de objeto são preservados por padrão quando você copia, reescreve, compõe, move ou restaura objetos. Também é possível modificar contextos durante as operações de cópia, reescrita e composição.

Linha de comando

Os comandos gcloud alpha storage cp, gcloud alpha storage rsync e gcloud alpha storage mv preservam os contextos do objeto de origem por padrão. Para modificar contextos durante essas operações, use qualquer uma das seguintes flags:

  • As flags --custom-contexts ou --custom-contexts-file para definir novos contextos para o objeto de destino.
  • A flag --clear-custom-contexts para impedir que 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 anexá-los ao objeto de destino.

O comando gcloud alpha storage objects compose mescla contextos dos objetos de origem e os anexa aos objetos de destino por padrão. O Cloud Storage resolve conflitos priorizando contextos de objetos de origem processados posteriormente. Para mais informações sobre o comportamento do contexto de objeto durante uma operação de composição, consulte Contextos de objetos compostos. Também é possível especificar novos contextos para o objeto de destino usando as flags --custom-contexts ou --custom-contexts-file.

API JSON

  • Para modificar contextos durante uma operação de objeto cópia ou regravação, inclua a propriedade contexts.custom no corpo da solicitação. Se você não incluir essa propriedade, os contextos do objeto de origem serão preservados por padrão.

  • Quando você compõe objetos, os contextos dos objetos de origem são mesclados ao objeto de destino por padrão. O Cloud Storage resolve conflitos priorizando contextos de objetos de origem processados posteriormente. Para mais informações sobre o comportamento do contexto de objeto durante uma operação de composição, consulte Contextos de objetos compostos. Você também pode especificar novos contextos para o objeto de destino na propriedade destination.contexts.custom.

A seguir