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.

Configurar a Google Cloud CLI

É necessário usar a versão 516.0.0 ou mais recente da Google Cloud CLI.

Definir o projeto padrão

Defina o projeto em que você quer criar o job de operações em lote de armazenamento.

gcloud config set project PROJECT_ID

onde PROJECT_ID é o código de seu projeto.

Ativar API

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

gcloud services enable storagebatchoperations.googleapis.com

Criar um manifesto

Para usar um manifesto para seleção de objetos, crie um manifesto.

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.

Esse papel predefinido contém as permissões necessárias para criar um job de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar um job de operações em lote de armazenamento:

  • Crie um job de operações em lote de armazenamento: storagebatchoperations.jobs.create
  • Execute o job de operações em lote de exclusão de objetos: storage.objects.delete
  • Execute o trabalho de operações em lote para atualizar metadados do objeto, atualizar a chave de criptografia gerenciada pelo cliente do objeto, atualizar o contexto do objeto ou atualizar a retenção de objeto do armazenamento: storage.objects.update

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

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. (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_NAME OBJECT_SELECTION_FLAG JOB_TYPE_FLAG\
--dry-run

    O teste usa os mesmos parâmetros do job real. Para mais detalhes, consulte as descrições de parâmetros.

    Para conferir os resultados do teste, consulte Receber detalhes do job de operações em lote do Storage.

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

Esse papel predefinido contém as permissões necessárias para visualizar um job de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para visualizar um job de operações em lote de armazenamento:

  • Ver um job de operações em lote do Storage: storagebatchoperations.jobs.get, storagebatchoperations.operations.get

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

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 um teste 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 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

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 um teste 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 o teste 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": [
          ""
        ]
      }
    }
  ]
}
}

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.

Esse papel predefinido contém as permissões necessárias para listar jobs de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para listar jobs de operações em lote de armazenamento:

  • Listar jobs de operações em lote de armazenamento: storagebatchoperations.jobs.list, storagebatchoperations.operations.list

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

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.

Esse papel predefinido contém as permissões necessárias para cancelar um job de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para cancelar um job de operações em lote de armazenamento:

  • Cancelar um job de operações em lote de armazenamento: storagebatchoperations.jobs.cancel, storagebatchoperations.operations.cancel

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

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

Esse papel predefinido contém as permissões necessárias para excluir um job de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para excluir um job de operações em lote de armazenamento:

  • Excluir um job de operações em lote de armazenamento: storagebatchoperations.jobs.delete

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

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.

Esse papel predefinido contém as permissões necessárias para criar um job de operações em lote de armazenamento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar um job de operações em lote de armazenamento:

  • Crie um job de operações em lote de armazenamento: storagebatchoperations.jobs.create
  • Execute o job de operações em lote de exclusão de objetos: storage.objects.delete
  • Execute o trabalho de operações em lote para atualizar metadados do objeto, atualizar a chave de criptografia gerenciada pelo cliente do objeto, atualizar o contexto do objeto ou atualizar a retenção de objeto do armazenamento: storage.objects.update

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

Criar um manifesto usando conjuntos de dados do Storage Insights

Para criar o manifesto do job de operações em lote de armazenamento, extraia dados do BigQuery. Para 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

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

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