O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar e gerenciar jobs de operações em lote

Nesta página, descrevemos como criar, visualizar, listar, cancelar e excluir jobs de operações em lote de armazenamento. Também descreve como usar os registros de auditoria do Cloud com trabalhos de operações em lote de armazenamento.

Antes de começar

Para criar e gerenciar jobs de operações em lote de armazenamento, siga as etapas nas seções a seguir.

Configurar o Storage Intelligence

Para criar e gerenciar jobs de operações em lote de armazenamento, configure o Storage Intelligence no bucket em que você quer executar o job.

Ativar a API de operações em lote de armazenamento

Ative a API de operações em lote de armazenamento.

gcloud services enable storagebatchoperations.googleapis.com

Criar um manifesto

Se você quiser usar um manifesto para seleção de objetos, crie um arquivo de manifesto. Usar um manifesto é uma das maneiras de selecionar objetos para processar em um job de operações em lote de armazenamento.

Criar um job de operações em lote de armazenamento

Nesta seção, descrevemos como criar um job de operações em lote de armazenamento.

Para receber as permissões necessárias para criar um job de operações em lote do Storage, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Console

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

Acessar buckets
Na lista de buckets, clique no nome daquele que contém os objetos em que você quer realizar operações em lote.

A página Detalhes do bucket é aberta, com a guia Objetos selecionada.
Clique em Criar operações em lote.
No painel Selecionar operação, escolha o tipo de operação:
- Gerenciar retenções de objetos: selecione Retenção temporária ou Retenção baseada em eventos. Para mais informações, consulte retenções de objetos.
- Atualizar metadados do objeto: para adicionar metadados do objeto, faça o seguinte:
  - Para adicionar metadados personalizados, siga estas etapas:
    1. No campo Chave, insira um nome de chave.
    2. No campo Valor, insira um valor para essa chave.
    3. Opcional: clique em + Adicionar item para incluir mais pares de chave-valor.
  - Para atualizar metadados de chave fixa, siga estas etapas:
    1. Para expandir a seção Atualizar metadados de chave fixa, clique na seta .
    2. Na lista Selecione um ou mais metadados para atualizar, escolha os itens que você quer editar.
- Atualizar/rotacionar chave de criptografia: para usar ou atualizar a chave de criptografia de objetos, faça o seguinte:
  1. Na lista Selecionar uma chave do Cloud KMS, escolha uma chave de criptografia gerenciada pelo cliente (CMEK).
  2. Opcional: selecione Trocar de projeto para escolher uma chave de outro projeto ou selecione Inserir chave manualmente para preencher os detalhes.
- Excluir objetos: para excluir objetos, faça o seguinte:
  1. Verifique se o controle de versão de objeto está ativado.
  2. Se o controle de versões de objetos estiver ativado, escolha uma das seguintes opções de exclusão:
    - Selecione Excluir todas as versões dos objetos para remover as versões ativas e não atuais.
    - Selecione Excluir versões ativas permanentemente para remover apenas a versão ativa.
    Se o controle de versões de objetos não estiver ativado, todos os objetos selecionados para exclusão serão excluídos permanentemente.
  Aviso:a exclusão acidental de objetos acarreta risco de perda de dados. Ative a exclusão reversível para recuperar exclusões acidentais de objetos.
Clique em Próxima.
No painel Nomear a operação e especificar os objetos, faça o seguinte:
1. No campo Nome, digite um nome.
2. Opcional: no campo Descrição, insira uma descrição.
3. Na seção Especificar objetos, defina um critério para processar objetos do bucket. Escolha uma das seguintes opções:
  - Selecionar todos os objetos: inclui todos os objetos no bucket.
  - Selecione objetos usando filtros de prefixo: para definir a lista de objetos usando filtros de prefixo, faça o seguinte:
    1. No campo Insira os prefixos dos objetos que serão incluídos, digite um prefixo.
    2. Opcional: clique em + Adicionar prefixo para especificar outros prefixos.
  - Fazer upload de listas de objetos usando arquivos CSV de manifesto: para usar um arquivo de manifesto para selecionar objetos, faça o seguinte:
    1. Faça upload do arquivo CSV de manifesto para um bucket. Esse arquivo precisa conter cabeçalhos para Nome do bucket, Chave do objeto e Número de geração.
    2. Na lista Selecionar modo do arquivo de manifesto, escolha uma das seguintes opções:
      - Se você selecionar Selecionar um arquivo de manifesto do Cloud Storage, clique em Procurar no campo Selecionar um arquivo de manifesto do Cloud Storage. Na caixa de diálogo Selecionar objeto que aparece, navegue até o arquivo CSV de manifesto e clique em Selecionar.
      - Se você selecionar Selecionar vários arquivos de manifesto usando um caractere curinga, insira o caminho do arquivo no campo Insira o local do arquivo de manifesto usando um caractere curinga. Por exemplo, bucket-name/folder/manifest_*.
Clique em Criar.

Linha de comando

Para definir a lista de objetos do job de operação em lote, escolha uma das seguintes configurações de origem:

Projeto como origem: segmenta objetos de um projeto usando uma configuração de conjunto de dados do Storage Insights. Em vez de especificar buckets ou prefixos individuais, é possível especificar parâmetros de filtro avançados, como --insights-dataset-config, --target-project, --bucket-filters e --object-filters. Para mais detalhes, consulte Criar um job usando filtros avançados.
Buckets como origem: segmenta objetos em buckets específicos. É necessário especificar uma das seguintes flags:
- --bucket ou --bucket-list para definir os intervalos de destino.
- Um arquivo CSV de manifesto (--manifest-location) ou prefixos de objeto (--included-object-prefixes) para definir os objetos de destino.

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Use a Google Cloud CLI versão 516.0.0 ou mais recente.
Para definir o projeto padrão, execute o comando gcloud config set project:
```
gcloud config set project PROJECT_ID
```
em que PROJECT_ID é o ID do projeto.
Opcional: execute um job de simulação. Antes de executar qualquer job, recomendamos que você o execute no modo de teste para verificar os critérios de seleção de objetos e conferir se há erros. A simulação não modifica nenhum objeto.

No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs create com a sinalização --dry-run:
```
gcloud storage batch-operations jobs create DRY_RUN_JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG \
--dry-run
```
Em que:
- DRY_RUN_JOB_NAME é o nome do job de simulação de operações em lote de armazenamento.
Os outros parâmetros são os mesmos do job real. Para mais informações, consulte as descrições de parâmetros.

Para conferir os resultados da simulação, consulte Receber detalhes do job de operações em lote do Storage.
Depois de uma simulação bem-sucedida, execute o comando gcloud storage batch-operations jobs create.
```
gcloud storage batch-operations jobs create JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG
```
Em que os parâmetros são os seguintes:
- JOB_NAME é o nome do job de operações em lote de armazenamento.
  
  Observação: ao criar o job real, especifique um nome exclusivo ou exclua o job de simulação primeiro. A reutilização do nome do job do teste simulado causa uma falha na criação com um erro already exists.
- --bucket: BUCKET é o nome do bucket que contém os objetos que você quer processar.
- --bucket-list: BUCKET_LIST é uma lista separada por vírgulas de um ou mais nomes de buckets que contêm os objetos que você quer processar. É possível especificar até 1.000 buckets de qualquer projeto, desde que cada um deles esteja inscrito em um plano de inteligência de armazenamento.
- OBJECT_SELECTION_FLAG é uma das seguintes flags que você precisa especificar:
  - --included-object-prefixes: especifique um ou mais prefixos de objeto. Exemplo:
    - Para corresponder a um único prefixo, use: --included-object-prefixes='prefix1'.
    - Para corresponder a vários prefixos, use uma lista separada por vírgulas: --included-object-prefixes='prefix1,prefix2'.
    - Para incluir todos os objetos, use um prefixo vazio: --included-object-prefixes=''.
  - --manifest-location: especifique o local do manifesto. Por exemplo, gs://bucket_name/path/object_name.csv.
- JOB_TYPE_FLAG é uma das seguintes flags que você precisa especificar, dependendo do tipo de serviço.
  - --delete-object: exclua um ou mais objetos.
    - Se o controle de versões de objetos estiver ativado para o bucket, os objetos atuais vão passar para um estado não atual, e os objetos não atuais serão ignorados.
    - Se o controle de versões de objetos estiver desativado para o bucket, a operação de exclusão vai excluir permanentemente os objetos e ignorar os objetos não atuais.
  - --enable-permanent-object-deletion: exclui objetos permanentemente. Use essa flag com a --delete-object para excluir permanentemente objetos ativos e não atuais em um bucket, independente da configuração de controle de versões de objetos do bucket.
  - --rewrite-object: atualize as chaves de criptografia gerenciadas pelo cliente de um ou mais objetos. Também é possível usar essa flag para mudar a classe de armazenamento do objeto especificando a chave storage-class. As classes de armazenamento compatíveis incluem STANDARD, NEARLINE, COLDLINE e ARCHIVE. Exemplo: --rewrite-object=storage-class=NEARLINE.
    
    Cuidado: se você mudar a classe de armazenamento de um objeto em um bucket ativado para o Autoclass, a operação não terá efeito. A operação informa sucesso, mas o Cloud Storage redefine a classe de armazenamento do objeto para a classe padrão definida pela Classe automática.
    Observação: mudar a classe de armazenamento de um objeto envolve reescrever os dados dele. Uma reescrita é uma operação de classe A. Essas operações podem gerar cobranças adicionais, dependendo da idade, do local e da classe de armazenamento dos dados. Para mais informações, consulte Preços do Cloud Storage. Se você ativar o Controle de versão de objeto no bucket, o Cloud Storage vai manter o objeto original como uma versão não atual. Essa versão permanece no bucket até que você a exclua explicitamente.
  - --set-object-acls-from-file: adiciona patches às listas de controle de acesso (ACLs) de objetos. Forneça um arquivo JSON ou YAML com as concessões a serem adicionadas ou atualizadas para entidades como allUsers ou allAuthenticatedUsers. Por exemplo, --set-object-acls-from-file=acl-updates.yaml ou --set-object-acls-from-file=acl-updates.json.
    
    A estrutura do arquivo YAML para atualizações é a seguinte:
```
grants:
  - entity: allAuthenticatedUsers
    role: READER
  remove_entities:
  - allUsers
```
    A estrutura do arquivo JSON para atualizações é a seguinte:
```
{
"grants": [
  {
    "entity": "allAuthenticatedUsers",
    "role": "READER"
  }
],
"remove_entities": [
  "allUsers"
]
}
```
  - --put-object-event-based-hold: ative as retenções de objetos com base em eventos.
  - --no-put-object-event-based-hold: desative as retenções de objetos com base em eventos.
  - --put-object-temporary-hold: ativa retenções de objetos temporárias.
  - --no-put-object-temporary-hold: desativa as retenções de objetos temporárias.
    
    O exemplo a seguir mostra como criar um job para atualizar os metadados Content-Language para en em todos os objetos listados em manifest.csv.
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--put-metadata=Content-Language=en
```
    O exemplo a seguir mostra como criar um job segmentado para vários grupos para atualizar Content-Language para en-us:
```
gcloud storage batch-operations jobs create my-job \
--bucket-list=bucket1,bucket2 \
--included-object-prefixes='' \
--put-metadata=Content-Language=en-us
```
  - --put-metadata: atualize os metadados do objeto. Especifique o par de chave-valor dos metadados do objeto que você quer modificar. É possível especificar um ou mais pares de chave-valor como uma lista. Também é possível definir configurações de retenção de objetos usando a flag --put-metadata. Para isso, especifique os parâmetros de retenção usando os campos Retain-Until e Retention-Mode. Por exemplo,
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--put-metadata=Retain-Until=RETAIN_UNTIL_TIME,Retention-Mode=RETENTION_MODE
```
    Em que:
    - RETAIN_UNTIL_TIME é a data e a hora, no formato RFC 3339, até que o objeto seja retido. Por exemplo, 2025-10-09T10:30:00Z. Para definir a configuração de retenção em um objeto, é necessário ativar a retenção no bucket que contém o objeto.
    - RETENTION_MODE é o modo de retenção, Unlocked ou Locked.
      
      Ao enviar uma solicitação para atualizar os campos RETENTION_MODE e RETAIN_UNTIL_TIME, considere o seguinte:
      - Para atualizar a configuração de retenção de objetos, forneça valores não vazios para os campos RETENTION_MODE e RETAIN_UNTIL_TIME. Definir apenas um deles resulta em um erro INVALID_ARGUMENT.
      - É possível estender o valor RETAIN_UNTIL_TIME para objetos nos modos Unlocked ou Locked.
      - A retenção de objetos precisa estar no modo Unlocked se você quiser fazer o seguinte:
        
        Reduza o valor de RETAIN_UNTIL_TIME.
        
        Remova a configuração de retenção. Para remover a configuração, forneça valores vazios para os campos RETENTION_MODE e RETAIN_UNTIL_TIME.
      - Se você omitir os campos RETENTION_MODE e RETAIN_UNTIL_TIME, a configuração de retenção vai permanecer inalterada.
  - --clear-all-object-custom-contexts: exclua todos os contextos de objetos atuais.
    
    O exemplo a seguir mostra como criar uma tarefa para limpar todos os contextos de objetos listados em manifest.csv:
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--clear-all-object-custom-contexts
```
    Atenção: limpar todos os contextos de objeto exclui todos os contextos atuais do objeto. Para preservar os contextos de objetos anteriores, ative o Cloud Logging. Os registros contêm contextos de antes da atualização, que podem ser usados para restaurar valores anteriores.
  - --clear-object-custom-contexts: remove contextos com chaves específicas. Também é possível atualizar contextos específicos e remover chaves usando a flag --clear-object-custom-contexts e uma das seguintes flags:
    - --update-object-custom-contexts: forneça um mapa de pares de chave-valor.
      
      O exemplo a seguir mostra como criar um job para remover o contexto com a chave temp-id e atualizar ou inserir o contexto com as chaves project-id e cost-center para todos os objetos listados em manifest.csv:
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts=project-id=project-A,cost-center=engineering
      Observação: não é possível especificar a mesma chave nas flags --clear-object-custom-contexts e --update-object-custom-contexts. Isso resulta em um erro INVALID_ARGUMENT.
    - --update-object-custom-contexts-file: forneça o caminho para um arquivo JSON ou YAML com pares de chave-valor.
      
      O exemplo a seguir mostra como criar um job para processar objetos definidos em manifest.csv. O job faz o seguinte:
      - Remove todos os contextos com a chave temp-id.
      - Atualiza os contextos atuais com as chaves project-id e cost-center definidas no arquivo /tmp/context_updates.json.
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts-file=/tmp/context_updates.json
      Em que /tmp/context_updates.json contém os seguintes contextos de objeto:
      { "project-id": {"value": "project-A"}, "cost-center": {"value": "engineering"} }

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id,
   std::string const& target_bucket_name, std::string const& object_prefix) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  namespace sbo = google::cloud::storagebatchoperations::v1;
  sbo::Job job;
  sbo::BucketList* bucket_list = job.mutable_bucket_list();
  sbo::BucketList::Bucket* bucket_config = bucket_list->add_buckets();
  bucket_config->set_bucket(target_bucket_name);
  sbo::PrefixList* prefix_list_config = bucket_config->mutable_prefix_list();
  prefix_list_config->add_included_object_prefixes(object_prefix);
  sbo::DeleteObject* delete_object_config = job.mutable_delete_object();
  delete_object_config->set_permanent_object_deletion_enabled(false);
  auto result = client.CreateJob(parent, job, job_id).get();
  if (!result) throw result.status();
  std::cout << "Created job: " << result->name() << "\n";
}

PHP

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CreateJobRequest;
use Google\Cloud\StorageBatchOperations\V1\Job;
use Google\Cloud\StorageBatchOperations\V1\BucketList;
use Google\Cloud\StorageBatchOperations\V1\BucketList\Bucket;
use Google\Cloud\StorageBatchOperations\V1\PrefixList;
use Google\Cloud\StorageBatchOperations\V1\DeleteObject;

/**
 * Create a new batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 * @param string $bucketName The name of your Cloud Storage bucket to operate on.
 *        (e.g. 'my-bucket')
 * @param string $objectPrefix The prefix of objects to include in the operation.
 *        (e.g. 'prefix1')
 */
function create_job(string $projectId, string $jobId, string $bucketName, string $objectPrefix): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $prefixListConfig = new PrefixList(['included_object_prefixes' => [$objectPrefix]]);
    $bucket = new Bucket(['bucket' => $bucketName, 'prefix_list' => $prefixListConfig]);
    $bucketList = new BucketList(['buckets' => [$bucket]]);

    $deleteObject = new DeleteObject(['permanent_object_deletion_enabled' => false]);

    $job = new Job(['bucket_list' => $bucketList, 'delete_object' => $deleteObject]);

    $request = new CreateJobRequest([
        'parent' => $parent,
        'job_id' => $jobId,
        'job' => $job,
    ]);
    $response = $storageBatchOperationsClient->createJob($request);

    printf('Created job: %s', $response->getName());
}

API JSON

Para definir a lista de objetos do job de operação em lote, escolha uma das seguintes configurações de origem:

Projeto como origem: segmenta objetos em todo o projeto usando uma configuração projectSource. Em vez de listar buckets ou prefixos individuais, especifique parâmetros de filtro avançados para consultar metadados de insights de armazenamento de forma dinâmica. Para mais informações, consulte a guia "API JSON" em Criar um job usando filtros avançados.
Buckets como origem: segmenta objetos em buckets específicos usando uma configuração bucketList. É necessário especificar os buckets de destino e um arquivo CSV de manifesto (manifest_location) ou prefixos de objeto (include_object_prefixes).

Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Crie um arquivo JSON com as configurações do job de operações em lote de armazenamento. Veja a seguir configurações comuns a serem incluídas:
```
{
        "Description": "JOB_DESCRIPTION",
        "BucketList":
        {
        "Buckets":
        [
         {
           "Bucket": "BUCKET_NAME",
           "Manifest": {
              "manifest_location": "MANIFEST_LOCATION"
               }
           "PrefixList": {
              "include_object_prefixes": "OBJECT_PREFIXES"
               }
         }
        ]
        },
        "DeleteObject":
        {
        "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
         }
        "RewriteObject": {
          "kms_key":"KMS_KEY_VALUE",
          "storage_class":"STORAGE_CLASS_VALUE"
          }
        "PutMetadata":{
          "METADATA_KEY": "METADATA_VALUE",
          ...,
          "objectRetention": {
              "retainUntilTime": "RETAIN_UNTIL_TIME",
              "mode": "RETENTION_MODE"
             }
           }
        "PutObjectHold": {
          "temporary_hold": TEMPORARY_HOLD_VALUE,
          "event_based_hold": EVENT_BASED_HOLD_VALUE
        },
        "updateObjectCustomContext": {
           "customContextUpdates": {
              "updates": {
                 "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
              },
              "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
           },
           "clearAll": CLEAR_ALL_VALUE
        },
        "SetObjectAcls": {
           "accessControlsUpdates": {
              "grants": [
                 { "entity": "allUsers", "role": "READER" }
              ],
              "removeEntities": ["allAuthenticatedUsers"]
           }
        },
        "dryRun": DRY_RUN_VALUE
        }
         
```
```
Where:
```
- JOB_NAME é o nome do job de operações em lote de armazenamento.
- JOB_DESCRIPTION é a descrição do job de operações em lote de armazenamento.
- BUCKET_NAME é o nome do bucket que contém um ou mais objetos que você quer processar.
- Para especificar os objetos que você quer processar, use um dos seguintes atributos no arquivo JSON:
  - MANIFEST_LOCATION é o local do manifesto. Por exemplo, gs://bucket_name/path/object_name.csv.
  - OBJECT_PREFIXES é a lista separada por vírgulas que contém um ou mais prefixos de objeto. Para corresponder a todos os objetos, use uma lista vazia.
- Dependendo do job que você quer processar, especifique uma das seguintes opções:
  - Excluir objetos:
```
"DeleteObject":
  {
  "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
  }
```
    Em que OBJECT_DELETION_VALUE é TRUE para excluir objetos.
  - Atualize a chave de criptografia gerenciada pelo cliente para objetos:
```
"RewriteObject":
  {
  "kms_key": KMS_KEY_VALUE
  }
```
    Em que KMS_KEY_VALUE é o valor da chave KMS do objeto que você quer atualizar.
  - Atualize a classe de armazenamento dos objetos:
```
"RewriteObject":
  {
  "storage_class": STORAGE_CLASS_VALUE
  }
```
    Em que STORAGE_CLASS_VALUE é a nova classe de armazenamento para a qual você quer fazer a transição dos objetos. As classes de armazenamento compatíveis incluem STANDARD, NEARLINE, COLDLINE e ARCHIVE.
  - Atualize os metadados do objeto:
```
"PutMetadata": {
     "METADATA_KEY": "METADATA_VALUE",
     ...,
    "objectRetention": {
       "retainUntilTime": "RETAIN_UNTIL_TIME",
       "mode": "RETENTION_MODE"
     }
   }
```
    Em que:
    - METADATA_KEY/VALUE é o par de chave-valor dos metadados do objeto. É possível especificar um ou mais pares.
    - RETAIN_UNTIL_TIME é a data e a hora, no formato RFC 3339, até que o objeto seja retido. Por exemplo, 2025-10-09T10:30:00Z. Para definir a configuração de retenção em um objeto, é necessário ativar a retenção no bucket que contém o objeto.
    - RETENTION_MODE é o modo de retenção, Unlocked ou Locked.
      
      Ao enviar uma solicitação para atualizar os campos RETENTION_MODE e RETAIN_UNTIL_TIME, considere o seguinte:
      
      Para atualizar a configuração de retenção de objetos, forneça valores não vazios para os campos RETENTION_MODE e RETAIN_UNTIL_TIME. Definir apenas um deles resulta em um erro INVALID_ARGUMENT.
      
      É possível estender o valor RETAIN_UNTIL_TIME para objetos nos modos Unlocked ou Locked.
      
      A retenção de objetos precisa estar no modo Unlocked se você quiser fazer o seguinte:
      
      Reduza o valor de RETAIN_UNTIL_TIME.
      
      Remova a configuração de retenção. Para remover a configuração, forneça valores vazios para os campos RETENTION_MODE e RETAIN_UNTIL_TIME.
      
      Se você omitir os campos RETENTION_MODE e RETAIN_UNTIL_TIME, a configuração de retenção vai permanecer inalterada.
    - Atualizar retenções de objetos:
      "PutObjectHold": { "temporary_hold": TEMPORARY_HOLD_VALUE, "event_based_hold": EVENT_BASED_HOLD_VALUE }
      Em que:
      - TEMPORARY_HOLD_VALUE é usado para ativar ou desativar a Retenção de objeto temporária. Um valor de 1 ativa a retenção, e um valor de 2 a desativa.
      - EVENT_BASED_HOLD_VALUE é usado para ativar ou desativar a retenção de objeto baseada em eventos. Um valor de 1 ativa a retenção, e um valor de 2 a desativa.
    - Atualize os contextos de objeto:
      "updateObjectCustomContext": { "customContextUpdates": { "updates": { "CONTEXT_KEY": { "value": "CONTEXT_VALUE" } }, "keysToClear": ["CONTEXT_KEY_TO_CLEAR"] }, "clearAll": CLEAR_ALL_VALUE }
      Em que:
      - CONTEXT_KEY é a chave de contexto do objeto a ser inserida ou atualizada.
      - CONTEXT_VALUE é o valor do contexto do objeto para a chave.
      - CONTEXT_KEY_TO_CLEAR é a chave a ser removida.
      - CLEAR_ALL_VALUE é definido como true para excluir todos os contextos de objetos atuais.
    - Atualize as listas de controle de acesso (ACLs) de objetos:
      "SetObjectAcls": { "accessControlsUpdates": { "grants": [ { "entity": "ENTITY_NAME", "role": "ROLE_NAME" } ], "removeEntities": ["ENTITY_TO_REMOVE"] } }
      Em que:
      - ENTITY_NAME é a entidade para adicionar ou atualizar o acesso. Por exemplo, allUsers, allAuthenticatedUsers ou um usuário/grupo específico.
      - ROLE_NAME é o papel a ser concedido. Por exemplo: READER e OWNER.
      - ENTITY_TO_REMOVE é a entidade cujas credenciais você quer remover.
  - DRY_RUN_VALUE é um valor booleano opcional. Defina como true para executar o job no modo de teste. O valor padrão é false.
    
    Importante: recomendamos executar o job no modo de teste antes de executar o job real. A simulação verifica os critérios de seleção de objetos e procura erros sem modificar nenhum objeto.
  1. Use curl para chamar a API JSON com uma solicitação de POST trabalho de operações em lote de armazenamento:
```
curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"
```
    Em que:
    - JSON_FILE_NAME é o nome do arquivo JSON.
    - PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
    - JOB_NAME é o nome do job de operações em lote de armazenamento.
      
      Observação: ao criar o job real após uma simulação, especifique um nome exclusivo, a menos que você exclua explicitamente o job de simulação primeiro. A reutilização do nome do job de teste faz com que a criação do job falhe com um erro already exists.

Receber detalhes do job de operações em lote de armazenamento

Esta seção descreve como conseguir os detalhes do job de operações em lote de armazenamento.

Para receber as permissões necessárias para visualizar um job de operações em lote do Storage, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket associado à operação.
Na página Detalhes do bucket, clique na guia Operações.
Na lista de operações, clique no ID da operação do job que você quer visualizar.
A página de detalhes mostra as métricas do job na guia Visão geral, como objetos descobertos, processados e erros que ocorreram.
Na tabela Resumo de erros, revise os detalhes da falha de execução ou clique em Ver no Cloud Logging para conferir os registros.
Para ver as definições de configuração do job, clique na guia Configuração.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs describe.
```
gcloud storage batch-operations jobs describe JOB_NAME
```
Em que:

JOB_NAME é o nome do job de operações em lote de armazenamento.

Quando você faz uma simulação de um job, a saída inclui os seguintes campos:
- totalObjectCount: mostra o número de objetos que correspondem aos seus critérios de seleção.
- errorSummaries: lista os erros encontrados durante a simulação, como problemas de permissão ou configurações inválidas.
- totalBytesFound: mostra o tamanho total dos objetos afetados. Esse campo só aparece quando você usa prefixos de objeto para selecionar objetos.
Se a operação for bem-sucedida, a resposta do job de simulação será semelhante ao exemplo a seguir:
```
  bucketList:
    buckets:
    - bucket: my-bucket
      manifest:
        manifestLocation: gs://my-bucket/manifest.csv
  completeTime: '2025-10-27T23:56:32Z'
  counters:
    totalObjectCount: '4'
  createTime: '2025-10-27T23:56:22.243528568Z'
  dryRun: true
  name: projects/my-project/locations/global/jobs/my-job
  putMetadata:
    contentLanguage: en
  state: SUCCEEDED
```
Uma resposta de job bem-sucedida omite o campo dryRun e retorna as seguintes métricas no campo counters:
- Total de objetos encontrados.
- Total de bytes encontrados ao usar prefixos de objeto.
- Transformações de objeto bem-sucedidas.
- Transformações de objeto com falha, se aplicável.
- Contextos de objeto criados, se aplicável.
- Contextos de objeto excluídos, se aplicável.
- Contextos de objeto atualizados, se aplicável. Esse contador rastreia as atualizações feitas nas chaves de contexto atuais.
A resposta de uma execução de job real é semelhante ao exemplo a seguir:
```
  bucketList:
    buckets:
    - bucket: my-bucket
      manifest:
        manifestLocation: gs://my-bucket/manifest.csv
  completeTime: '2025-10-31T20:19:42.357826655Z'
  counters:
    succeededObjectCount: '4'
    totalObjectCount: '4'
  createTime: '2025-10-31T20:19:22.016517077Z'
  name: projects/my-project/locations/global/jobs/my-job
  putMetadata:
    contentLanguage: en
  state: SUCCEEDED
  
```
Observação: se os objetos no bucket forem modificados após um teste simulado, o valor totalObjectCount do job real poderá ser diferente dos resultados do teste simulado.

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto job = client.GetJob(name);
  if (!job) throw job.status();
  std::cout << "Got job: " << job->name() << "\n";
}

PHP

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\GetJobRequest;

/**
 * Gets a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function get_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new GetJobRequest([
        'name' => $formattedName,
    ]);

    $response = $storageBatchOperationsClient->getJob($request);

    printf('Got job: %s', $response->getName());
}

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 GET trabalho de operações em lote de armazenamento:
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"
```
Em que:
- PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
- JOB_NAME é o nome do job de operações em lote de armazenamento.
Quando você faz uma simulação de um job, a saída inclui os seguintes campos:
- totalObjectCount: mostra o número de objetos que correspondem aos seus critérios de seleção.
- errorSummaries: lista os erros encontrados durante a simulação, como problemas de permissão ou configurações inválidas.
- totalBytesFound: mostra o tamanho total dos objetos afetados. Esse campo só aparece quando você usa prefixos de objeto para selecionar objetos.
Se a operação for bem-sucedida, a resposta para a simulação vai ser semelhante a este exemplo:
```
{
  "name": "projects/my-project/locations/global/jobs/my-job",
  "description": "dry-run-job",
  "deleteObject": {
    "permanent_object_deletion_enabled": true
     },
  "createTime": "2025-10-28T00:26:53.900882459Z",
  "completeTime": "2025-10-28T00:27:04.101663275Z",
  "counters": {
      "totalObjectCount": "5",
      "totalBytesFound": "203"
    },
  "state": "SUCCEEDED",
  "bucketList": {
    "buckets": [
      {
        "bucket": "my-bucket",
        "prefixList": {
          "includedObjectPrefixes": [
            ""
          ]
        }
      }
    ]
  },
  "dryRun": true
}
```
Uma resposta de job bem-sucedida omite o campo dryRun e retorna as seguintes métricas no campo counters:
- Total de objetos encontrados.
- Total de bytes encontrados ao usar prefixos de objeto.
- Transformações de objeto bem-sucedidas.
- Transformações de objeto com falha, se aplicável.
- Contextos de objeto criados, se aplicável.
- Contextos de objeto excluídos, se aplicável.
- Contextos de objeto atualizados, se aplicável. Esse contador rastreia as atualizações feitas nas chaves de contexto atuais.
  
  A resposta de uma execução de job real é semelhante ao exemplo a seguir:
```
{
"name": "my-job",
"description": "my-delete-objects-job",
"deleteObject": {
  "permanent_object_deletion_enabled": true
},
"createTime": "2025-10-28T00:26:53.900882459Z",
"completeTime": "2025-10-28T00:27:04.101663275Z",
"counters": {
  "succeededObjectCount: "5"
  "totalObjectCount": "5",
  "totalBytesFound": "203"
},
"state": "SUCCEEDED",
"bucketList": {
  "buckets": [
    {
      "bucket": "my-bucket",
      "prefixList": {
        "includedObjectPrefixes": [
          ""
        ]
      }
    }
  ]
}
}
```
Observação: se os objetos no bucket forem modificados após um teste simulado, o valor totalObjectCount do job real poderá ser diferente dos resultados do teste simulado.

Listar operações de bucket

Para jobs que incluem vários buckets, é possível conferir o progresso e o status das operações em buckets individuais. Para listar as operações realizadas em buckets de um job específico, execute o comando gcloud storage batch-operations bucket-operations list:

gcloud storage batch-operations bucket-operations list --job=JOB_NAME

Também é possível filtrar a lista para intervalos específicos usando a flag --buckets:

gcloud storage batch-operations bucket-operations list --job=JOB_NAME --buckets=BUCKET_NAME_LIST

O exemplo a seguir mostra como listar operações para bucket1 e bucket2 no job my-job:

gcloud storage batch-operations bucket-operations list --job=my-job --buckets=bucket1,bucket2

Em que:

JOB_NAME é o nome exclusivo do job de operações em lote de armazenamento que você criou. Por exemplo, my-job.
BUCKET_NAME_LIST é uma lista separada por vírgulas de nomes de buckets, sem espaços entre nomes. Por exemplo, bucket1,bucket2.

Descrever uma operação de bucket

Para conferir detalhes de uma operação de bucket específica, use um dos seguintes métodos:

Use o comando gcloud storage batch-operations bucket-operations describe com a flag do nome do recurso de operação:
```
gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_RESOURCE_NAME
```
Em que:
- BUCKET_OPERATION_RESOURCE_NAME é o caminho completo do recurso da operação de bucket. Por exemplo, projects/my-project/locations/global/jobs/my-job/bucketOperations/bo-1.
Use o comando gcloud storage batch-operations bucket-operations describe com as flags de ID da operação do bucket e ID do job:
```
gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_ID --job=JOB_NAME
```
Em que:
- BUCKET_OPERATION_ID é o ID da operação do bucket.
- JOB_NAME é o nome exclusivo do job de operações em lote de armazenamento que você criou. Por exemplo, my-job.

Listar jobs de operações em lote do Storage

Nesta seção, descrevemos como listar os jobs de operações em lote de armazenamento em um projeto.

Para receber as permissões necessárias para listar trabalhos de operações em lote do Storage, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket associado à operação.
Na página Detalhes do bucket, clique na guia Operações. A página Operações mostra uma lista de operações ativas em execução.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs list.
```
gcloud storage batch-operations jobs list
```

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  for (auto const& job : client.ListJobs(parent)) {
    if (!job) throw job.status();
    std::cout << job->name() << "\n";
  }
}

PHP

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\ListJobsRequest;

/**
 * List Jobs in a given project.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 */
function list_jobs(string $projectId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $request = new ListJobsRequest([
        'parent' => $parent,
    ]);

    $jobs = $storageBatchOperationsClient->listJobs($request);

    foreach ($jobs as $job) {
        printf('Job name: %s' . PHP_EOL, $job->getName());
    }
}

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 LIST trabalhos de operações em lote do Storage:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs"

Em que:

PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.

Cancelar um job de operações em lote de armazenamento

Nesta seção, descrevemos como cancelar um job de operações em lote de armazenamento em um projeto.

Para receber as permissões necessárias para cancelar um trabalho de operações em lote de armazenamento, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket associado à operação em lote do Storage que você quer cancelar.
Clique na guia Operações. Essa guia mostra uma lista de jobs de operações em lote. Só é possível cancelar jobs em andamento.
Na lista de operações, selecione um ou vários jobs que você quer cancelar e clique em Cancelar.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs cancel.
```
gcloud storage batch-operations jobs cancel JOB_NAME
```
Em que:

JOB_NAME é o nome do job de operações em lote de armazenamento.

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto response = client.CancelJob(name);
  if (!response) throw response.status();
  std::cout << "Cancelled job: " << name << "\n";
}

PHP

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CancelJobRequest;

/**
 * Cancel a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function cancel_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new CancelJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->cancelJob($request);

    printf('Cancelled job: %s', $formattedName);
}

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 CANCEL um trabalho de operações em lote de armazenamento:
```
curl -X CANCEL \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"
```
Em que:
- PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
- JOB_NAME é o nome do job de operações em lote de armazenamento.

Excluir um job de operações em lote de armazenamento

Nesta seção, descrevemos como excluir um job de operações em lote de armazenamento.

Para receber as permissões necessárias para excluir um job de operações em lote do Storage, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket associado à operação em lote do Storage que você quer excluir.
Clique na guia Operações. Essa guia mostra uma lista de jobs de operações em lote. Só é possível excluir jobs que não estão em execução, como jobs concluídos, com falha ou cancelados.
Na lista de operações, selecione um ou vários jobs que você quer excluir e clique em Excluir.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs delete.
```
gcloud storage batch-operations jobs delete JOB_NAME
```
Em que:

JOB_NAME é o nome do job de operações em lote de armazenamento.

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto status = client.DeleteJob(name);
  if (!status.ok()) throw status;
  std::cout << "Deleted job: " << name << "\n";
}

PHP

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\DeleteJobRequest;

/**
 * Delete a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function delete_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new DeleteJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->deleteJob($request);

    printf('Deleted job: %s', $formattedName);
}

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 DELETE um trabalho de operações em lote de armazenamento:
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"
```
Em que:
- PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
- JOB_NAME é o nome do job de operações em lote de armazenamento.

Criar um job de operações em lote de armazenamento usando conjuntos de dados do Storage Insights

Para executar um job de operações em lote nos objetos listados em um conjunto de dados, selecione uma das seguintes opções:

Usar filtros avançados: filtre objetos de forma dinâmica no nível do projeto diretamente no comando da Google Cloud CLI.

Os conjuntos de dados do Storage Insights são criados com base em snapshots periódicos e pontuais dos metadados de armazenamento. Cada um tem um horário que mostra quando os metadados foram capturados. Quando você executa um job em lote usando filtros avançados, esse horário de instantâneo determina quais objetos e versões são processados. Por padrão, as operações em lote do Storage selecionam automaticamente o horário do snapshot mais recente. Para evitar operações em dados desatualizados, a criação de jobs falha se o snapshot selecionado tiver mais de dois dias. Para saber como resolver essa falha, consulte Resolver problemas com operações em lote do Storage.
Usar um arquivo de manifesto: gere um arquivo de manifesto CSV executando uma consulta do BigQuery e forneça-o ao job.

Os métodos são descritos nas seções a seguir.

Usar filtros avançados

Em vez de criar um arquivo de manifesto, use filtros da Common Expression Language (CEL) para selecionar objetos diretamente com base nos campos do conjunto de dados do Storage Insights. É possível executar jobs em vários buckets em um projeto. Quando você usa filtros de conjunto de dados para seleção de objetos, as operações em lote de armazenamento têm como destino objetos ativos e atuais no momento do snapshot do conjunto de dados selecionado. Consequentemente, o trabalho inclui apenas objetos que têm um valor NULL para softDeleteTime e timeDeleted no momento do snapshot.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
Execute o comando gcloud storage batch-operations jobs create:
```
gcloud storage batch-operations jobs create JOB_NAME \
{--insights-dataset-config=INSIGHTS_DATASET_CONFIG_RESOURCE_NAME --target-project=TARGET_PROJECT [--bucket-filters=BUCKET_FILTER_CEL] [--object-filters=OBJECT_FILTER_CEL] [--target-locations=TARGET_LOCATIONS] [--target-snapshot-time=TARGET_SNAPSHOT_TIME] | --dry-run-job-id=DRY_RUN_JOB_ID} \
--JOB_TYPE_FLAG
```
Em que:
- JOB_NAME é o nome do job de operações em lote de armazenamento.
- INSIGHTS_DATASET_CONFIG_RESOURCE_NAME: o nome do recurso da configuração do conjunto de dados. Por exemplo, projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}. É necessário especificar esse parâmetro antes de usar as flags --bucket-filters e --object-filters.
- TARGET_PROJECT: o ID do projeto ou número do projeto associado aos recursos de destino.
- BUCKET_FILTER_CEL e OBJECT_FILTER_CEL (opcional): as expressões de filtro da CEL usadas para selecionar objetos. Confira alguns exemplos:
  - --bucket-filters="name in ['bucket-1', 'bucket-2']"
  - --object-filters="size >= 5000 && name.endsWith('.pdf')" Para informações sobre campos, operadores e funções compatíveis, consulte a referência de filtros da CEL.
- TARGET_LOCATIONS (opcional): uma lista de locais do Cloud Storage usados para restringir o escopo do job. Por exemplo, us,us-central1,us-east4. Use esse parâmetro para excluir locais que estão passando por uma interrupção do serviço. Se apenas TARGET_LOCATIONS for especificado e TARGET_SNAPSHOT_TIME for omitido, o job vai escolher automaticamente o carimbo de data/hora do snapshot mais recente que foi preenchido com êxito nas visualizações de atributos de objeto e bucket em todos os locais especificados.
- TARGET_SNAPSHOT_TIME (opcional): o carimbo de data/hora UTC do snapshot do conjunto de dados a ser usado, no formato RFC 3339. Por exemplo, 2026-05-03T16:00:00Z. Esse snapshot precisa existir em todas as visualizações de atributos de bucket e objeto. Se você especificar esse parâmetro, também precisará especificar o parâmetro TARGET_LOCATIONS.
- DRY_RUN_JOB_ID: o identificador de um job de simulação executado anteriormente. Se você especificar esse parâmetro, não poderá especificar nenhum outro parâmetro de seleção de objeto, incluindo --insights-dataset-config, --target-project, --bucket-filters, --object-filters, --target-locations e --target-snapshot-time. O job ativo pesquisa todos os critérios de seleção diretamente no job de simulação.
- JOB_TYPE_FLAG: a flag correspondente à operação em massa que você quer realizar, como --put-metadata ou --delete-object.

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 de configuração JSON que especifique os filtros de conjunto de dados e as configurações de operações em massa. Exemplo:
```
{
    "description": "JOB_DESCRIPTION",
    "projectSource": {
        "project": "projects/TARGET_PROJECT",
        "insightsDatasetConfig": "INSIGHTS_DATASET_CONFIG_RESOURCE_NAME",
        "bucketFilters": {
            "expression": "BUCKET_FILTER_CEL"
        },
        "objectFilters": {
            "expression": "OBJECT_FILTER_CEL"
        },
        "snapshotTime": "SNAPSHOT_TIME",
        "targetLocations": {
            "locations": ["LOCATION_1", "LOCATION_2"]
        }
    },
    "deleteObject": {
        "permanentObjectDeletionEnabled": OBJECT_DELETION_VALUE
    }
 }
```
Em que:
- JOB_DESCRIPTION é a descrição do job.
  - TARGET_PROJECT é o ID do projeto ou o número do projeto associado aos objetos de destino.
- INSIGHTS_DATASET_CONFIG_RESOURCE_NAME é o nome totalmente qualificado da configuração do conjunto de dados (por exemplo, projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}).
- BUCKET_FILTER_CEL é a expressão de filtro CEL para intervalos. Por exemplo, name in ['bucket-1', 'bucket-2']. Para detalhes sobre palavras-chave, campos e operadores compatíveis, consulte a referência de filtros da CEL.
- OBJECT_FILTER_CEL é a expressão de filtro CEL para objetos. Por exemplo, size >= 5000 && name.endsWith('.pdf').
- snapshotTime (opcional): um carimbo de data/hora UTC específico no formato RFC 3339 (por exemplo, "2026-05-03T16:00:00Z") que especifica qual snapshot do conjunto de dados usar. Esse snapshot precisa estar presente nas visualizações de bucket e de conjunto de dados de objetos em todos os locais de destino. Se você especificar esse campo, também precisará especificar o campo targetLocations.
- targetLocations (opcional): um objeto JSON que especifica uma lista de locais do Cloud Storage (por exemplo, ["us", "us-central1", "us-east4"]) para filtrar o escopo do job. Se as dependências estiverem passando por uma interrupção em locais específicos, você poderá restringir o job a esses locais. Se apenas targetLocations for especificado e snapshotTime for omitido, o job vai escolher automaticamente o carimbo de data/hora do snapshot mais recente que foi preenchido com êxito nas visualizações de atributos de objeto e bucket em todos os locais especificados.
- OBJECT_DELETION_VALUE é o booleano que alterna a exclusão permanente. Por exemplo, true ou false.

Envie uma solicitação POST usando cURL para executar o job:

curl -X POST \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "Content-Type: application/json" \
     -d @JSON_FILE_NAME \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"

Em que:

JSON_FILE_NAME é o nome do arquivo JSON.
PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
JOB_NAME é o nome do job de operações em lote de armazenamento.

Usar um arquivo de manifesto

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar um manifesto usando conjuntos de dados do Storage Insights

É possível criar o manifesto para seu job de operações em lote de armazenamento extraindo dados do BigQuery. Para fazer isso, consulte o conjunto de dados vinculado, exporte os dados resultantes como um arquivo CSV e salve em um bucket do Cloud Storage. O job de operações em lote do Storage pode usar esse arquivo CSV como manifesto.

Executar a seguinte consulta SQL no BigQuery em uma visualização de conjunto de dados do Storage Insights recupera objetos maiores que 1 KiB chamados Temp_Training:

  EXPORT DATA OPTIONS(
   uri=`URI`,
   format=`CSV`,
   overwrite=OVERWRITE_VALUE,
   field_delimiter=',') AS
  SELECT bucket, name, generation
  FROM DATASET_VIEW_NAME
  WHERE bucket = BUCKET_NAME
  AND name LIKE (`Temp_Training%`)
  AND size > 1024 * 1024
  AND snapshotTime = SNAPSHOT_TIME

Em que:

URI é o URI do bucket que contém o manifesto. Por exemplo, gs://bucket_name/path_to_csv_file/*.csv. Quando você usa o caractere curinga *.csv, o BigQuery exporta o resultado para vários arquivos CSV.
OVERWRITE_VALUE é um valor booleano. Se definido como true, a operação de exportação vai substituir os arquivos existentes no local especificado.
DATASET_VIEW_NAME é o nome totalmente qualificado da visualização do conjunto de dados do Storage Insights no formato PROJECT_ID.DATASET_ID.VIEW_NAME. Para encontrar o nome do seu conjunto de dados, confira o conjunto de dados vinculado.

Em que:
- PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
- DATASET_ID é o nome do conjunto de dados. Por exemplo, objects-deletion-dataset.
- VIEW_NAME é o nome da visualização do conjunto de dados. Por exemplo, bucket_attributes_view.
BUCKET_NAME é o nome do bucket. Por exemplo, my-bucket.
SNAPSHOT_TIME é o horário do snapshot da visualização do conjunto de dados do Storage Insights. Por exemplo, 2024-09-10T00:00:00Z.

Criar um job de operações em lote de armazenamento usando um arquivo de manifesto

Para criar um job de operações em lote de armazenamento e processar objetos contidos no manifesto, siga estas etapas:

Console

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

Acessar buckets
Na lista de buckets, clique no nome daquele que contém os objetos em que você quer realizar operações em lote.

A página Detalhes do bucket é aberta, com a guia Objetos selecionada.
Clique em Criar operações em lote.
No painel Selecionar operação, escolha o tipo de operação:
- Gerenciar retenções de objetos: selecione Retenção temporária ou Retenção baseada em eventos. Para mais informações, consulte retenções de objetos.
- Atualizar metadados do objeto: para adicionar metadados do objeto, faça o seguinte:
  - Para adicionar metadados personalizados, siga estas etapas:
    1. No campo Chave, insira um nome de chave.
    2. No campo Valor, insira um valor para essa chave.
    3. Opcional: clique em + Adicionar item para incluir mais pares de chave-valor.
  - Para atualizar metadados de chave fixa, siga estas etapas:
    1. Para expandir a seção Atualizar metadados de chave fixa, clique na seta .
    2. Na lista Selecione um ou mais metadados para atualizar, escolha os itens que você quer editar.
- Atualizar/rotacionar chave de criptografia: para usar ou atualizar a chave de criptografia de objetos, faça o seguinte:
  1. Na lista Selecionar uma chave do Cloud KMS, escolha uma chave de criptografia gerenciada pelo cliente (CMEK).
  2. Opcional: selecione Trocar de projeto para escolher uma chave de outro projeto ou selecione Inserir chave manualmente para preencher os detalhes.
- Excluir objetos: para excluir objetos, faça o seguinte:
  1. Verifique se o controle de versão de objeto está ativado.
  2. Se o controle de versões de objetos estiver ativado, escolha uma das seguintes opções de exclusão:
    - Selecione Excluir todas as versões dos objetos para remover as versões ativas e não atuais.
    - Selecione Excluir versões ativas permanentemente para remover apenas a versão ativa.
    Se o controle de versões de objetos não estiver ativado, todos os objetos selecionados para exclusão serão excluídos permanentemente.
  Aviso:a exclusão acidental de objetos acarreta risco de perda de dados. Ative a exclusão reversível para recuperar exclusões acidentais de objetos.
Clique em Próxima.
No painel Nomear a operação e especificar os objetos, faça o seguinte:
1. No campo Nome, digite um nome.
2. Opcional: no campo Descrição, insira uma descrição.
3. Na seção Especificar objetos, selecione Fazer upload de listas de objetos usando arquivos CSV de manifesto e faça o seguinte:
  1. Faça upload do arquivo CSV de manifesto para um bucket. Esse arquivo precisa conter cabeçalhos para Nome do bucket, Chave do objeto e Número de geração.
  2. Na lista Selecionar modo do arquivo de manifesto, escolha uma das seguintes opções:
    - Se você selecionar Selecionar um arquivo de manifesto do Cloud Storage, clique em Procurar no campo Selecionar um arquivo de manifesto do Cloud Storage. Na caixa de diálogo Selecionar objeto que aparece, navegue até o arquivo CSV de manifesto e clique em Selecionar.
    - Se você selecionar Selecionar vários arquivos de manifesto usando um caractere curinga, insira o caminho do arquivo no campo Insira o local do arquivo de manifesto usando um caractere curinga. Por exemplo, bucket-name/folder/manifest_*.
Clique em Criar.

Linha de comando

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
No ambiente para desenvolvedores, execute o comando gcloud storage batch-operations jobs create:
```
gcloud storage batch-operations jobs create \
JOB_NAME \
{--bucket=SOURCE_BUCKET | --bucket-list=SOURCE_BUCKET_LIST} \
--manifest-location=URI \
JOB_TYPE_FLAG
```
Em que:
- JOB_NAME é o nome do job de operações em lote de armazenamento.
- SOURCE_BUCKET é o nome do bucket que contém os objetos que você quer processar. Por exemplo, my-bucket.
- SOURCE_BUCKET_LIST é uma lista separada por vírgulas de um ou mais nomes de buckets que contêm os objetos que você quer processar. Por exemplo, bucket1,bucket2.
- URI é o URI do bucket que contém o manifesto. Por exemplo, gs://bucket_name/path_to_csv_file/*.csv. Quando você usa o caractere curinga *.csv, o BigQuery exporta o resultado para vários arquivos CSV.
- JOB_TYPE_FLAG é uma das seguintes flags, dependendo do tipo de serviço.
  - --delete-object: exclua um ou mais objetos.
  - --put-metadata: atualize os metadados do objeto. Os metadados do objeto são armazenados como pares de chave-valor. Especifique o par de chave-valor dos metadados que você quer modificar. É possível especificar um ou mais pares de chave-valor como uma lista. Também é possível fornecer configurações de retenção de objetos usando a flag --put-metadata.
  - --rewrite-object: atualize as chaves de criptografia gerenciadas pelo cliente de um ou mais objetos. Também é possível usar essa flag para mudar a classe de armazenamento do objeto especificando a chave storage-class. As classes de armazenamento compatíveis incluem STANDARD, NEARLINE, COLDLINE e ARCHIVE. Por exemplo, --rewrite-object=storage-class=NEARLINE.
  - --set-object-acls-from-file: adiciona patches às listas de controle de acesso (ACLs) de objetos. Forneça o caminho para um arquivo JSON ou YAML com concessões a serem adicionadas ou atualizadas para entidades como allUsers ou allAuthenticatedUsers. Exemplo: --set-object-acls-from-file=acl-updates.yaml.
  - --put-object-event-based-hold: ative as retenções de objetos com base em eventos.
  - --no-put-object-event-based-hold: desative as retenções de objetos com base em eventos.
  - --put-object-temporary-hold: ativa retenções de objetos temporárias.
  - --no-put-object-temporary-hold: desativa as retenções de objetos temporárias.
  - --clear-all-object-custom-contexts: exclua todos os contextos de objetos atuais.
    
    O exemplo a seguir mostra como criar uma tarefa para limpar todos os contextos de objetos listados em manifest.csv:
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--clear-all-object-custom-contexts
```
    Atenção: limpar todos os contextos de objeto exclui todos os contextos atuais do objeto. Para preservar os contextos de objetos anteriores, ative o Cloud Logging. Os registros contêm contextos de antes da atualização, que podem ser usados para restaurar valores anteriores.
  - --clear-object-custom-contexts: remove contextos com chaves específicas. Também é possível atualizar contextos específicos e remover chaves usando a flag --clear-object-custom-contexts e uma das seguintes flags:
    - --update-object-custom-contexts: forneça um mapa de pares de chave-valor.
      
      O exemplo a seguir mostra como criar um job para remover o contexto com a chave temp-id e atualizar ou inserir o contexto com as chaves project-id e cost-center para todos os objetos listados em manifest.csv:
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts=project-id=project-A,cost-center=engineering
      Observação: não é possível especificar a mesma chave nas flags --clear-object-custom-contexts e --update-object-custom-contexts. Isso resulta em um erro INVALID_ARGUMENT.
    - --update-object-custom-contexts-file: forneça o caminho para um arquivo JSON ou YAML com pares de chave-valor.
      
      O exemplo a seguir mostra como criar um job para processar objetos definidos em manifest.csv. O job faz o seguinte:
      - Remove todos os contextos com a chave temp-id.
      - Atualiza os contextos atuais com as chaves project-id e cost-center definidas no arquivo /tmp/context_updates.json.
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts-file=/tmp/context_updates.json
      Em que /tmp/context_updates.json contém os seguintes contextos de objeto:
      { "project-id": {"value": "project-A"}, "cost-center": {"value": "engineering"} }

Integração com o VPC Service Controls

O VPC Service Controls oferece uma camada extra de segurança para recursos de operações em lote de armazenamento. Ao colocar projetos em um perímetro de serviço, você ajuda a proteger recursos e serviços contra solicitações que vêm de fora do perímetro. Para saber mais sobre os detalhes do perímetro de serviço do VPC Service Controls para operações em lote de armazenamento, consulte Produtos e limitações compatíveis.

Usar os Registros de auditoria do Cloud para jobs de operações em lote de armazenamento

Os jobs de operações em lote do Storage registram transformações em objetos do Cloud Storage nos registros de auditoria do Cloud para o Cloud Storage. Use os Registros de auditoria do Cloud com o Cloud Storage para rastrear essas transformações. Para detalhes sobre como ativar os registros de auditoria, consulte Ativar registros de auditoria. Na entrada de registro de auditoria, um campo de metadados callUserAgent com o valor StorageBatchOperations indica que a transformação foi realizada por operações em lote de armazenamento.

Próximas etapas

Saiba mais sobre os conjuntos de dados do Storage Insights

Criar e gerenciar jobs de operações em lote Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Configurar o Storage Intelligence

Ativar a API de operações em lote de armazenamento

Criar um manifesto

Criar um job de operações em lote de armazenamento

Console

Linha de comando

Bibliotecas de cliente

C++

PHP

API JSON

Receber detalhes do job de operações em lote de armazenamento

Console

Linha de comando

Bibliotecas de cliente

C++

PHP

API JSON

Listar operações de bucket

Descrever uma operação de bucket

Listar jobs de operações em lote do Storage

Console

Linha de comando

Bibliotecas de cliente

C++

PHP

API JSON

Cancelar um job de operações em lote de armazenamento

Console

Linha de comando

Bibliotecas de cliente

C++

PHP

API JSON

Excluir um job de operações em lote de armazenamento

Console

Linha de comando

Bibliotecas de cliente

C++

PHP

API JSON

Criar um job de operações em lote de armazenamento usando conjuntos de dados do Storage Insights

Usar filtros avançados

Linha de comando

API JSON

Usar um arquivo de manifesto

Criar um manifesto usando conjuntos de dados do Storage Insights

Criar um job de operações em lote de armazenamento usando um arquivo de manifesto

Console

Linha de comando

Integração com o VPC Service Controls

Usar os Registros de auditoria do Cloud para jobs de operações em lote de armazenamento

Próximas etapas

Criar e gerenciar jobs de operações em lote