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 API

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

gcloud services enable storagebatchoperations.googleapis.com

Criar um manifesto

Se 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 trabalho 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

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

    Acessar buckets

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

    A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

  3. Clique em Criar operações em lote.
  4. 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.

  5. Clique em Próxima.
  6. 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.
      • Selecionar 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 Inserir o local do arquivo de manifesto usando um caractere curinga. Por exemplo, bucket-name/folder/manifest_*.
  7. Clique em Criar.

Linha de comando

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

  2. Use a Google Cloud CLI versão 516.0.0 ou mais recente.

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

  4. Opcional: execute um job de teste. 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_NAME OBJECT_SELECTION_FLAG JOB_TYPE_FLAG \
--dry-run

    A simulação usa os mesmos parâmetros do job real. Para mais detalhes, 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.

  5. 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_NAME OBJECT_SELECTION_FLAG JOB_TYPE_FLAG

    Em que os parâmetros são os seguintes:

    • DRY_RUN_JOB_NAME é o nome do job de simulação de operações em lote de armazenamento.

    • JOB_NAME é o nome 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.

    • 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: exclua objetos permanentemente. Use essa flag junto 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.

      • --put-object-event-based-hold: ative as retenções de objetos com base em eventos.

      • --no-put-object-event-based-hold: desativa 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

      • --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 um job 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

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

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

Saiba mais na documentação de referência PHP da API Cloud Storage.

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

APIs REST

API JSON

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

  2. Crie um arquivo JSON com as configurações do job de operações em lote do Storage. 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"
      }
    "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
    },
    "dryRun": DRY_RUN_VALUE
    }

    Em que:

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

      • DRY_RUN_VALUE é um valor booleano opcional. Defina como true para executar o job no modo de teste. O valor padrão é false.

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

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

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

    Acessar buckets

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

Linha de comando

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

  2. No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs describe.

    gcloud storage batch-operations jobs describe JOB_ID

    Em que:

    JOB_ID é 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: se você usar prefixos de objeto para a seleção de objetos, o job também vai mostrar o tamanho total dos objetos que serão afetados.

    Se a operação for bem-sucedida, a resposta do job de simulação será semelhante a este exemplo:

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

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

Saiba mais na documentação de referência PHP da API Cloud Storage.

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

APIs REST

API JSON

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

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

    Em que:

    • PROJECT_ID é o ID ou o número do projeto. Por exemplo, my-project.
    • JOB_ID é 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: se você usar prefixos de objeto para a seleção de objetos, o job também vai mostrar o tamanho total dos objetos que serão afetados.

    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 objetos 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": [
          ""
        ]
      }
    }
  ]
}
}

Listar jobs de operações em lote de armazenamento

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

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado à operação.
  3. 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

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

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

Saiba mais na documentação de referência PHP da API Cloud Storage.

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

APIs REST

API JSON

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

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

    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

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado à operação em lote de armazenamento que você quer cancelar.

  3. Clique na guia Operações. Essa guia mostra uma lista de jobs de operação em lote. Só é possível cancelar jobs em andamento.

  4. Na lista de operações, selecione um ou vários jobs que você quer cancelar e clique em Cancelar.

Linha de comando

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

  2. No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs cancel.

    gcloud storage batch-operations jobs cancel JOB_ID

    Em que:

    JOB_ID é 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

Saiba mais na documentação de referência PHP da API Cloud Storage.

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

APIs REST

API JSON

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

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

    Em que:

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

    • JOB_ID é 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

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado à operação em lote de armazenamento que você quer excluir.

  3. Clique na guia Operações. Essa guia mostra uma lista de jobs de operação em lote. Só é possível excluir jobs que não estão em execução, como jobs concluídos, com falha ou cancelados.

  4. Na lista de operações, selecione um ou vários jobs que você quer excluir e clique em Excluir.

Linha de comando

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

  2. No ambiente de desenvolvimento, execute o comando gcloud storage batch-operations jobs delete.

    gcloud storage batch-operations jobs delete JOB_ID

    Em que:

    JOB_ID é 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

Saiba mais na documentação de referência PHP da API Cloud Storage.

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

APIs REST

API JSON

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

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

    Em que:

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

    • JOB_ID é 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 criar um job de operações em lote de armazenamento usando conjuntos de dados do Storage Insights, siga as etapas nas seções abaixo.

Para receber as permissões necessárias para criar um trabalho 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.

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-os em um bucket do Cloud Storage. O job de operações em lote de armazenamento 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 os objetos contidos no manifesto, siga estas etapas:

Console

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

    Acessar buckets

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

    A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

  3. Clique em Criar operações em lote.
  4. 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.

  5. Clique em Próxima.
  6. 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 Inserir o local do arquivo de manifesto usando um caractere curinga. Por exemplo, bucket-name/folder/manifest_*.
  7. Clique em Criar.

Linha de comando

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

  2. No ambiente para desenvolvedores, execute o comando gcloud storage batch-operations jobs create:

    gcloud storage batch-operations jobs create \
JOB_ID \
--bucket=SOURCE_BUCKET_NAME \
--manifest-location=URI \
JOB_TYPE_FLAG

    Em que:

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

    • SOURCE_BUCKET_NAME é o bucket que contém um ou mais objetos que você quer processar. Por exemplo, my-bucket.

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

      • --clear-all-object-custom-contexts: exclua todos os contextos de objetos atuais.

        O exemplo a seguir mostra como criar um job 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

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

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

É possível fornecer uma camada extra de segurança aos recursos de operações em lote de armazenamento usando o VPC Service Controls. Ao usar o VPC Service Controls, você adiciona projetos a perímetros de serviço que protegem recursos e serviços contra solicitações originadas 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 de armazenamento registram transformações em objetos do Cloud Storage nos registros de auditoria do Cloud Storage. Use os registros de auditoria do Cloud com o Cloud Storage para rastrear as transformações de objetos realizadas pelos jobs de operações em lote de armazenamento. Para informações sobre como ativar registros de auditoria, consulte Ativar registros de auditoria. Na entrada de registro de auditoria, o campo de metadados callUserAgent com o valor StorageBatchOperations indica uma transformação de operações em lote de armazenamento.

Próximas etapas