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 e 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: Usuário do objeto de armazenamento (roles/storage.objectUser)
Para ver as chaves e os valores de contexto anexados aos objetos: Leitor de objetos do Storage (roles/storage.objectViewer)
Descartar contextos de objetos 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
Anexe, atualize e exclua contextos de objetos:
- 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

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 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.

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 storage rsync, use a sinalização --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:

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 a um objeto existente

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

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 para o qual você quer editar o contexto. 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 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 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

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

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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.

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.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 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, employees.txt.

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 objeto

É 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 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 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, employees.txt

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: Human resources
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

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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.googleapis.com/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, 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"
        }
      }
    }
  }

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 com eficiência. 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ê os copia, reescreve, compõe, move ou restaura.

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 objetos 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 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 separadas 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:

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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.

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 onde 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 remover todos os contextos de origem sem fornecer uma substituição, use o parâmetro de consulta dropContextGroups=custom na sua 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"

Para preservar os contextos, omita a propriedade contexts.custom do corpo da solicitação e exclua dropContextGroups=custom nos parâmetros de consulta:

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"

Para informações sobre como os contextos se comportam durante operações de cópia, consulte o parâmetro de consulta dropContextGroups.

Reescrever objetos

Por padrão, o Cloud Storage preserva os contextos de objetos do objeto de origem durante uma operação de substituição, mesmo que você substitua outros metadados. Para modificar contextos de objetos 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 reescritas automaticamente quando necessário, por exemplo, ao copiar objetos entre locais ou classes de armazenamento diferentes. gcloud storage cp e gcloud storage rsync resultam em um objeto de origem e 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 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 separadas 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:

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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.

Use cURL para chamar a API JSON com uma solicitação de objeto de reescrita 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 contexto do 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 remover todos os contextos de origem sem fornecer uma substituição, use o parâmetro de consulta dropContextGroups=custom na sua 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"

Para preservar contextos, omita a propriedade contexts.custom do corpo da solicitação e exclua dropContextGroups=custom nos parâmetros de consulta:

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"

Para informações sobre como os contextos se comportam durante operações de reescrita, consulte 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 do 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 onde o objeto de destino é criado. Por exemplo, my-bucket.
SOURCE_OBJECT_1 e SOURCE_OBJECT_2 são objetos de origem para composição.
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 impedir 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 onde 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.

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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.

Use cURL para chamar a API JSON com uma solicitação de objeto POST de composição:
```
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 onde o objeto de destino será 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:

Ter a CLI gcloud instalada e inicializada , o que permite gerar um token de acesso para o cabeçalho Authorization.

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 para composição.

Use cURL para chamar a API JSON com uma solicitação de objeto POST de composição:
```
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 será criado. Por exemplo, my-bucket.
- DESTINATION_OBJECT_NAME é o nome do objeto de destino a ser criado. Por exemplo, my-composite-object.

A seguir

Saiba mais sobre as propriedades de contexto de objeto na documentação da API Cloud Storage.

Usar contextos de objeto Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Ter os papéis necessários

Permissões necessárias

Anexar contextos a novos objetos

Linha de comando

API JSON

Anexar ou modificar contextos a um objeto existente

Linha de comando

Bibliotecas de cliente

Java

API JSON

Ver contextos de objeto

Linha de comando

Bibliotecas de cliente

Java

API JSON

Filtrar objetos por contextos

Gerenciar contextos de objetos durante operações de objetos

Copiar objetos

Linha de comando

API JSON

Reescrever objetos

Linha de comando

API JSON

Compor objetos

Linha de comando

API JSON

A seguir

Usar contextos de objeto