Usar contextos de objeto

Os contextos de objeto são pares de chave-valor personalizados que podem ser anexados a objetos do Cloud Storage. É possível usar contextos de objeto para classificar dados, rastrear fluxos de trabalho de processamento e ajudar a enriquecer seus objetos com metadados. Esses contextos persistem quando você copia, compõe ou restaura objetos.

Nesta página, descrevemos como anexar e gerenciar contextos em objetos do Cloud Storage.

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:

• Criar objetos com contextos: Criador de objetos do Storage (roles/storage.objectCreator)
• Anexar, atualizar, visualizar e excluir contextos de objetos de repositório de dados e visualizar representações de contexto completas (incluindo dados estendidos): Usuário de objetos do Storage (roles/storage.objectUser)
• Ver chaves e valores de contexto: Leitor de objetos do Storage (roles/storage.objectViewer)
• Remover contextos de objeto durante operações de regravação, cópia e composição: Proprietário de objeto legado do Storage (roles/storage.legacyObjectOwner)

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
• Anexar, atualizar e excluir contextos de objeto:
  • storage.objects.update
  • storage.objects.createContext
  • storage.objects.updateContext
  • storage.objects.deleteContext
• Contextos de soltar objeto: storage.objects.dropContexts
• Ver contextos de objeto:
  • storage.objects.get
  • storage.objects.list
• Confira o contexto completo de um objeto, incluindo dados estendidos (prévia): storage.objects.viewFullContext

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

Requisitos de nomenclatura para pares de chave-valor

As chaves e os valores dos contextos personalizados precisam atender aos seguintes requisitos:

• Precisa ter entre 1 e 256 caracteres, inclusive.

• Precisa começar com um caractere alfanumérico.

• Precisa ser um caractere UTF-8 válido. A maioria dos caracteres UTF-8 é aceita, exceto os seguintes:

  • Aspas simples (')

  • Aspas duplas (")

  • Barra invertida (\)

  • Barra (/)

• As chaves de contexto que começam com o prefixo google: (por exemplo, google:annotation:face-detector-v1) são reservadas para contextos gerados pelo Google. Não é possível criar novos contextos com o prefixo google: nem modificar os valores deles. Se você tentar fazer isso, o Cloud Storage vai retornar um erro INVALID_ARGUMENT. Para remover contextos com o prefixo google:, é necessário descartá-los usando o parâmetro dropContextGroups durante uma operação de reescrita.

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.

Console

1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Faça upload do objeto.

3. Siga as etapas para anexar contextos ao objeto.

Linha de comando

Para anexar contextos ao fazer upload de objetos com o comando gcloud storage cp, use a flag --custom-contexts:

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

Em que:

• OBJECT_LOCATION é o caminho local do objeto. Por exemplo, Desktop/employees.txt.
• 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.

Como alternativa, crie um arquivo JSON que contenha os contextos que você quer anexar aos objetos e use 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 storage rsync, use a flag --custom-contexts ou --custom-contexts-file:

gcloud 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:

• Uploads de várias partes

• Uploads retomáveis

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 atual

É possível anexar novos contextos a objetos ou atualizar contextos em buckets do Cloud Storage.

Somente os serviços do Google, como jobs de enriquecimento de objetos, podem gerar e anexar contextos com dados estendidos, que usam o prefixo de chave reservado google:. Não é possível anexar dados estendidos a contextos definidos pelo usuário nem criar ou modificar chaves de contexto que começam com o prefixo google:. Se você tentar criar ou modificar chaves google:, o Cloud Storage vai retornar um erro INVALID_ARGUMENT.

Se um contexto atual incluir dados estendidos, o Cloud Storage vai manter esse contexto no objeto atualizado durante as operações de atualização e patch. Definir um valor de contexto como null exclui apenas os contextos que não têm dados estendidos. Para conferir dados estendidos, consulte Ver contexto completo do objeto. Para remover um contexto com dados estendidos, incluindo contextos com o prefixo google:, é necessário descartá-lo usando o parâmetro dropContextGroups durante uma operação de reescrita.

Console

1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Na lista de buckets, clique no nome daquele que contém o objeto.

3. Navegue até o objeto e clique em Abrir menu flutuante do objeto.

4. Clique em Editar contextos.

5. No painel Editar contextos, faça o seguinte:

   • Adicione um novo contexto de objeto:

     1. Clique em Adicionar um contexto personalizado.

     2. Nos campos Chave de contexto do objeto e Valor de contexto do objeto, insira um novo par de chave-valor.

     3. Clique em Concluído.

     4. Opcional: para adicionar outros contextos de objeto, clique em Adicionar um contexto personalizado, repita as etapas anteriores e clique em Salvar.

   • Editar um contexto de objeto:

     1. Clique no contexto do objeto.

     2. Atualize os campos Chave de contexto do objeto, Valor de contexto do objeto ou ambos.

     3. Clique em Concluído e depois em Salvar.

   • Excluir um contexto de objeto:

     Clique em Excluir e em Salvar.

Linha de comando

Use o comando gcloud storage objects update:

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

Em que:

• 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 do objeto. Por exemplo, employees.txt.

• CUSTOM_CONTEXTS_FLAG é qualquer uma das seguintes flags:

  • Para substituir todos os contextos, 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, use a flag --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 ou excluir de um objeto. Por exemplo, Human resources.

Se funcionar, a resposta será parecida com esta:

Patching gs://my-bucket/employees.txt#1560574162144861...
  Completed 1

Observação: modificar o contexto de um objeto atualiza o número de metageração e a ETag dele. Adicionar, atualizar ou remover um contexto não cria uma nova versão do objeto.

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);
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::ObjectContexts;
use google_cloud_wkt::FieldMask;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;

    let metageneration = object.metageneration;
    let mut custom = object.contexts.clone().unwrap_or_default().custom;
    custom.entry("example".to_string()).or_default().value = "true".into();

    let updated = client
        .update_object()
        .set_if_metageneration_match(metageneration)
        .set_object(object.set_contexts(ObjectContexts::new().set_custom(custom)))
        .set_update_mask(FieldMask::default().set_paths(["contexts.custom.example"]))
        .send()
        .await?;
    println!(
        "successfully set contexts for object {NAME} in bucket {bucket_id}: {:?}",
        updated.contexts
    );
    Ok(())
}

API JSON

1. Ter a 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, 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, 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.

   Observação: definir uma chave de contexto ou o objeto custom como null só exclui contextos sem dados estendidos. Se um contexto atual incluir dados estendidos, ele será preservado e transferido para o objeto atualizado. Para remover contextos com dados estendidos, use o parâmetro dropContextGroups durante uma operação de reescrita.

3. Use cURL para chamar a API JSON com uma solicitação 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"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo que inclui as informações de contextos de objeto.
   • 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, employees.txt.

Como alternativa, é possível 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

Para conferir os contextos de um objeto, liste os metadados dele ou descreva um objeto específico.

Console

1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.
   

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket que contém o objeto com os contextos que você quer visualizar.

3. Acesse o objeto e clique no nome dele.

   Na página Detalhes do objeto, os pares de chave-valor de todos os contextos anexados são listados na seção Contextos do objeto.

Linha de comando

Use o comando gcloud storage objects describe:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Em que:

• BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my-bucket.
• OBJECT_NAME é o nome do objeto. Por exemplo, employees.txt.

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

bucket: my-bucket
contexts:
  custom:
    Department:
      createTime: '2023-01-01T00:00:00.000000+00:00'
      type: CUSTOM
      updateTime: '2023-01-01T00:00:00.000000+00:00'
      value: Human resources
    google:annotation:face-detector-v1:
      createTime: '2025-09-29T17:20:00.000000+00:00'
      extendedDataTypeUrl: type.googleapis.com/google.protobuf.Struct
      type: CUSTOM
      updateTime: '2025-09-29T17:20:00.000000+00:00'
      value: SUCCESS
name: employees.txt

Observação: para limitar a saída e exibir apenas as chaves e os valores de contexto, use --format=contextsonly.

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());
        }
      }
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;
    println!(
        "The contexts field for object {NAME} in bucket {bucket_id} is: {:?}",
        object.contexts
    );
    Ok(())
}

API JSON

1. Ter a 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 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"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, employees.txt.

   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": "Human resources",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           },
           "google:annotation:face-detector-v1": {
             "value": "SUCCESS",
             "createTime": "2025-09-29T17:20:00.000Z",
             "updateTime": "2025-09-29T17:20:00.000Z",
             "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
           }
         }
       }
     }
     

Ver contexto completo do objeto

Para conferir um único contexto e os dados estendidos dele, use o método viewFullContext (Prévia).

API JSON

Para recuperar um único contexto completo (incluindo dados estendidos) por chave:

1. Ter a 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 GET Ver contexto completo:

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

   Em que:

   • BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, employees.txt.
   • KEY é a chave de contexto específica a ser recuperada. Por exemplo, google:annotation:face-detector-v1.

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

   {
     "kind": "storage#objectFullContext",
     "type": "CUSTOM",
     "key": "google:annotation:face-detector-v1",
     "value": "SUCCESS",
     "createTime": "2025-09-29T17:20:00.000Z",
     "updateTime": "2025-09-29T17:20:00.000Z",
     "extendedData": {
       "@type": "type.googleapis.com/google.protobuf.Struct",
       "value": {
         "modelName": "face-detector",
         "modelVersion": "v1",
         "faceAnnotationGroup": {
           "faceAnnotations": [
             {
               "detectionConfidence": 0.9,
               "landmarkingConfidence": 0.8
             }
           ]
         }
       }
     }
   }

Filtrar objetos por contextos

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

Gerenciar contextos de objetos durante operações de objetos

Por padrão, o Cloud Storage preserva os contextos de objetos quando você copia, reescreve, compõe, move ou restaura objetos.

Copiar objetos

Por padrão, o Cloud Storage preserva os contextos de objeto do objeto de origem durante uma operação de cópia, mesmo que você substitua outros metadados. Para modificar contextos de objeto durante uma operação de cópia, siga estas etapas:

Linha de comando

Os comandos gcloud storage cp, gcloud storage rsync e gcloud 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:

• A flag --custom-contexts para definir novos contextos para o objeto de destino.

• A flag --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 anexá-los ao objeto de destino.

Para definir novos contextos ao copiar um objeto, use o comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, employees.txt.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, employees-backup.txt.
• 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.

Para remover todos os contextos do objeto de origem ao copiar um objeto, use o comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, pets/cat.png.

Para modificar contextos individuais do objeto de origem ao copiar um objeto, use o comando gcloud storage cp com --update-custom-contexts e --remove-custom-contexts:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, pets/cat.png.
• KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor ou chaves separados por vírgulas.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

API JSON

Para substituir contextos ao copiar um objeto, inclua a propriedade contexts.custom no corpo da solicitação:

1. Ter a 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 os contextos a serem anexados ao objeto de destino:

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

   Em que:

   • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department.
   • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

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

   curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo JSON que inclui as informações de contextos de objetos.
   • SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
   • SOURCE_OBJECT_NAME é o nome codificado por URL do objeto a ser copiado. Por exemplo, employees.txt.
   • DESTINATION_BUCKET_NAME é o nome do bucket para o qual o objeto será copiado. Por exemplo, my-destination-bucket.
   • DESTINATION_OBJECT_NAME é o nome codificado por URL do objeto de destino. Por exemplo, employees-backup.txt.

Para descartar contextos de origem durante uma operação de cópia, use o parâmetro de consulta dropContextGroups=custom na solicitação:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Se o corpo da solicitação contiver contextos com o prefixo google:, você poderá manter as chaves e os valores atuais do objeto de origem, mas o Cloud Storage vai rejeitar novas chaves google: ou valores modificados.

Para preservar contextos, omita a propriedade contexts do corpo da solicitação e exclua o parâmetro de consulta dropContextGroups.

Reescrever objetos

Por padrão, o Cloud Storage preserva os contextos de objeto do objeto de origem durante uma operação de substituição, mesmo que você substitua outros metadados. Para modificar contextos de objeto durante uma operação de reescrita, siga estas etapas:

Linha de comando

Os comandos gcloud storage cp, gcloud storage rsync e gcloud storage mv realizam regravações automaticamente quando necessário, por exemplo, ao copiar objetos entre diferentes locais ou classes de armazenamento. gcloud storage cp e gcloud storage rsync resultam em um objeto de origem e de destino, enquanto gcloud storage mv cria o objeto de destino e remove o objeto de origem. Como essas operações criam um novo objeto, também é possível modificar ou anexar contextos como parte do mesmo comando usando qualquer uma das seguintes flags:

• A flag --custom-contexts para definir novos contextos para o objeto de destino.

• A flag --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 anexá-los ao objeto de destino.

Para definir novos contextos ao copiar um objeto, use o comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, employees.txt.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, employees-backup.txt.
• 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.

Para remover todos os contextos do objeto de origem ao copiar um objeto, use o comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, pets/cat.png.

Para modificar contextos individuais do objeto de origem ao copiar um objeto, use o comando gcloud storage cp com --update-custom-contexts e --remove-custom-contexts:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Em que:

• SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser copiado. Por exemplo, my-source-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto a ser copiado. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do bucket para onde o objeto será copiado. Por exemplo, my-destination-bucket.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino. Por exemplo, pets/cat.png.
• KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department. É possível especificar vários pares de chave-valor ou chaves separados por vírgulas.
• VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

API JSON

Para substituir contextos ao reescrever um objeto, inclua a propriedade contexts.custom no corpo da solicitação:

1. Ter a 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 os contextos a serem anexados ao objeto de destino:

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

   Em que:

   • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department.
   • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

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

   curl -X POST --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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo JSON que inclui as informações de contextos de objeto.
   • SOURCE_BUCKET_NAME é o nome do bucket que contém o objeto a ser reescrito. Por exemplo, my-source-bucket.
   • SOURCE_OBJECT_NAME é o nome codificado por URL do objeto a ser reescrito. Por exemplo, employees.txt.
   • DESTINATION_BUCKET_NAME é o nome do bucket em que o objeto será reescrito. Por exemplo, my-destination-bucket.
   • DESTINATION_OBJECT_NAME é o nome codificado por URL do objeto de destino. Por exemplo, employees-backup.txt.

Para descartar contextos de origem durante uma operação de regravação, use o parâmetro de consulta dropContextGroups=custom na solicitação:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Se o corpo da solicitação contiver contextos com o prefixo google:, você poderá manter as chaves e os valores atuais do objeto de origem, mas o Cloud Storage vai rejeitar novas chaves google: ou valores modificados.

Para preservar contextos, omita a propriedade contexts do corpo da solicitação e exclua o parâmetro de consulta dropContextGroups.

Compor objetos

O comando gcloud storage objects compose e o método compose da API JSON mesclam contextos dos objetos de origem e os anexam 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.

Linha de comando

Para especificar novos contextos para o objeto de destino ao compor objetos, use a flag --contexts:

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --contexts=KEY=VALUE,...

Em que:

• BUCKET_NAME é o nome do bucket que contém os objetos de origem e em que o objeto de destino é criado. Por exemplo, my-bucket.
• SOURCE_OBJECT_1 e SOURCE_OBJECT_2 são objetos de origem a serem compostos.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino a ser criado. Por exemplo, my-composite-object.
• 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.

Para evitar que contextos de origem sejam anexados a objetos compostos, use a flag --clear-custom-contexts:

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Em que:

• BUCKET_NAME é o nome do bucket que contém os objetos de origem e em que o objeto de destino é criado. Por exemplo, my-bucket.
• SOURCE_OBJECT_1 e SOURCE_OBJECT_2 são os objetos de origem a serem compostos.
• DESTINATION_OBJECT_NAME é o nome do objeto de destino a ser criado. Por exemplo, my-composite-object.

API JSON

Para especificar novos contextos para o objeto de destino ao compor objetos, inclua contextos na propriedade destination do corpo da solicitação.

1. Ter a 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 o corpo da solicitação:

   {
     "sourceObjects": [
       {"name": "SOURCE_OBJECT_1"},
       {"name": "SOURCE_OBJECT_2"}
     ],
     "destination": {
       "contentType": "text/plain",
       "contexts": {
         "custom": {
           "KEY": {
             "value": "VALUE"
           }
         }
       }
     }
   }

   Em que:

   • SOURCE_OBJECT_1 e SOURCE_OBJECT_2 são objetos de origem para composição.
   • KEY é a chave de contexto a ser anexada a um objeto. Por exemplo, Department.
   • VALUE é o valor a ser associado à chave de contexto. Por exemplo, Human resources.

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

   curl -X POST --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/DESTINATION_OBJECT_NAME/compose"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo JSON que inclui o corpo da solicitação.
   • BUCKET_NAME é o nome do bucket que contém os objetos de origem e em que o objeto de destino é criado. Por exemplo, my-bucket.
   • DESTINATION_OBJECT_NAME é o nome do objeto de destino a ser criado. Por exemplo, my-composite-object.

Para evitar que contextos de origem sejam anexados a objetos compostos, use o parâmetro de consulta dropContextGroups=custom na sua solicitação:

1. Ter a 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 o corpo da solicitação:

   {
     "sourceObjects": [
       {"name": "SOURCE_OBJECT_1"},
       {"name": "SOURCE_OBJECT_2"}
     ],
     "destination": {
       "contentType": "text/plain"
   }
   }

   Em que:

   • SOURCE_OBJECT_1 e SOURCE_OBJECT_2 são objetos de origem a serem compostos.

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

   curl -X POST --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/DESTINATION_OBJECT_NAME/compose?dropContextGroups=custom"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo JSON que inclui o corpo da solicitação.
   • BUCKET_NAME é o nome do bucket que contém os objetos de origem e onde o objeto de destino é criado. Por exemplo, my-bucket.
   • DESTINATION_OBJECT_NAME é o nome do objeto de destino a ser criado. Por exemplo, my-composite-object.

Gerenciar contextos de objetos em massa

Para gerenciar contextos de milhões ou bilhões de objetos com um único job, use as operações em lote do Storage. Para criar um job, especifique os objetos de destino fornecendo um arquivo de manifesto ou usando prefixos de objeto. Depois de especificar os objetos, crie um job de operação em lote para atualizar os contextos de objeto.

Analisar contextos de objetos no BigQuery

Se você tiver uma assinatura ativa do Storage Intelligence, poderá consultar e analisar contextos de objetos no BigQuery. Use a visualização do catálogo de contextos de objetos (object_contexts_catalog_view) para consultar chaves de contexto, valores e payloads extendedData estruturados (como rótulos de imagem, rostos detectados e caixas delimitadoras). A visualização do catálogo é atualizada a cada 24 horas.

Por exemplo, para encontrar todos os objetos em que uma pontuação de anotação específica excede um limite:

SELECT
  t.project,
  t.bucket,
  t.name,
  t.generation,
  label
FROM
  `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t,
  UNNEST(t.contexts) AS context,
  UNNEST(JSON_QUERY_ARRAY(context.extendedData.labelAnnotationGroup.labelAnnotations)) AS label
WHERE
  context.key = "google:annotation:label-detector-v1"
  AND FLOAT64(label.score) > 0.75;

Substitua:

• PROJECT_ID: o ID do projeto que contém o conjunto de dados do Storage Insights.
• INSIGHTS_DATASET: o nome do conjunto de dados do Storage Insights.

Para mais informações sobre o esquema de visualização do catálogo, consulte Esquema do catálogo de contextos de objetos. Para mais exemplos de consultas, consulte Analisar contextos de objetos.

A seguir

• Aprenda Mais sobre as propriedades de contexto de objeto na documentação da API Cloud Storage.