Crea y administra trabajos de operaciones por lotes

En esta página, se describe cómo crear, ver, enumerar, cancelar y borrar trabajos de operaciones por lotes de almacenamiento. También se describe cómo usar los registros de auditoría de Cloud con trabajos de operaciones por lotes de almacenamiento.

Antes de comenzar

Para crear y administrar trabajos de operaciones por lotes de almacenamiento, completa los pasos que se indican en las siguientes secciones.

Configura Storage Intelligence

Para crear y administrar trabajos de operaciones por lotes de almacenamiento, configura Storage Intelligence en el bucket en el que deseas ejecutar el trabajo.

Habilita la API de operaciones de almacenamiento por lotes

Habilita la API de operaciones de almacenamiento por lotes.

gcloud services enable storagebatchoperations.googleapis.com

Crea un manifiesto

Si deseas usar un manifiesto para la selección de objetos, crea un archivo de manifiesto. Usar un manifiesto es una de las formas en que puedes seleccionar objetos para procesar en un trabajo de operaciones por lotes de almacenamiento.

Crea un trabajo de operaciones por lotes de almacenamiento

En esta sección, se describe cómo crear un trabajo de operaciones por lotes de almacenamiento.

Para obtener los permisos que necesitas para crear un trabajo de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket que contiene los objetos en los que deseas realizar operaciones por lotes.

    Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.

  3. Haz clic en Crear operaciones por lotes.
  4. En el panel Seleccionar operación, elige el tipo de operación:
    • Administrar conservaciones de objetos: Selecciona Conservación temporal o Conservación basada en eventos. Para obtener más información, consulta conservaciones de objetos.
    • Actualizar metadatos de objetos: Para agregar metadatos de objetos, haz lo siguiente:
      • Para agregar metadatos personalizados, completa los siguientes pasos:
        1. En el campo Clave, ingresa un nombre de clave.
        2. En el campo Valor, ingresa un valor para esa clave.
        3. Opcional: Haz clic en + Agregar elemento para agregar más pares clave-valor.
      • Para actualizar los metadatos de clave fija, completa los siguientes pasos:
        1. Para expandir la sección Actualiza los metadatos de clave fija, haz clic en la flecha de expansión .
        2. En la lista Seleccionar uno o más metadatos para actualizar, selecciona los elementos de metadatos que deseas editar.
    • Actualizar o rotar la clave de encriptación: Para usar o actualizar la clave de encriptación de los objetos, haz lo siguiente:
      1. En la lista Selecciona una clave de Cloud KMS, elige una clave de encriptación administrada por el cliente (CMEK).
      2. Opcional: Selecciona Cambiar proyecto para elegir una clave de otro proyecto o selecciona Ingresar clave de forma manual para completar los detalles.
    • Borrar objetos: Para borrar objetos, haz lo siguiente:
      1. Verifica si el control de versiones de objetos está habilitado.

      2. Si el control de versiones de objetos está habilitado, elige una de las siguientes opciones de eliminación:

        • Selecciona Borrar todas las versiones de los objetos para quitar las versiones publicadas y las no actuales.
        • Selecciona Borrar versiones publicadas de forma permanente para quitar solo la versión publicada.

        Si el control de versiones de objetos no está habilitado, los objetos seleccionados para su eliminación se borrarán de forma permanente.

  5. Haz clic en Siguiente.
  6. En el panel Nombre de la operación y especificación de objetos, haz lo siguiente:
    1. En el campo Nombre, ingresa un nombre.
    2. Opcional: en el campo Descripción, ingresa una descripción.
    3. En la sección Especifica objetos, define un criterio para procesar objetos del bucket. Elige una de las siguientes opciones:
      • Seleccionar todos los objetos: Incluye todos los objetos del bucket.
      • Seleccionar objetos con filtros de prefijo: Para definir la lista de objetos con filtros de prefijo, haz lo siguiente:
        1. En el campo Ingresa los prefijos de los objetos que se incluirán, ingresa un prefijo.
        2. Opcional: Haz clic en + Agregar prefijo para especificar prefijos adicionales.
      • Subir listas de objetos con archivos CSV de manifiesto: Para usar un archivo de manifiesto para seleccionar objetos, haz lo siguiente:

        1. Sube tu archivo CSV de manifiesto a un bucket. Este archivo debe contener encabezados para Bucket name, Object key y número de generación.
        2. En la lista Selecciona el modo del archivo de manifiesto, elige una de las siguientes opciones:
          • Si seleccionas Seleccionar un archivo de manifiesto de Cloud Storage, haz clic en Explorar en el campo Seleccionar un archivo de manifiesto de Cloud Storage. En el diálogo Select object que aparece, navega hasta tu archivo CSV de manifiesto y, luego, haz clic en Select.
          • Si seleccionas Selecciona varios archivos de manifiesto con comodines, ingresa la ruta de acceso del archivo en el campo Ingresa la ubicación del archivo de manifiesto con comodines. Por ejemplo, bucket-name/folder/manifest_*.
  7. Haz clic en Crear.

Línea de comandos

Para definir la lista de objetos de tu trabajo de operación por lotes, puedes elegir una de las siguientes configuraciones de origen:

  • El proyecto como fuente: Segmenta los objetos para un proyecto con una configuración del conjunto de datos de Storage Insights. En lugar de especificar prefijos o buckets individuales, puedes especificar parámetros de filtro avanzados, como --insights-dataset-config, --target-project, --bucket-filters y --object-filters. Para obtener más información, consulta Crea un trabajo con filtros avanzados.
  • Buckets como fuente: Se segmentan los objetos dentro de buckets específicos. Debes especificar una de las siguientes marcas:
    • --bucket o --bucket-list para definir los buckets de destino.
    • Un archivo CSV de manifiesto (--manifest-location) o prefijos de objetos (--included-object-prefixes) para definir los objetos de destino

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Usa la versión 516.0.0 o posterior de Google Cloud CLI.

  3. Para establecer el proyecto predeterminado, ejecuta el comando gcloud config set project:

    gcloud config set project PROJECT_ID

    En el ejemplo anterior, PROJECT_ID es el ID de tu proyecto.

  4. Opcional: Ejecuta un trabajo de ejecución de prueba. Antes de ejecutar cualquier trabajo, te recomendamos que lo ejecutes en modo de ejecución de prueba para verificar los criterios de selección de objetos y comprobar si hay errores. La ejecución de prueba no modifica ningún objeto.

    En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs create con la marca --dry-run:

    gcloud storage batch-operations jobs create DRY_RUN_JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG \
--dry-run

    Aquí:

    • DRY_RUN_JOB_NAME es el nombre del trabajo de ejecución de prueba de operaciones por lotes de almacenamiento.

    Los demás parámetros son los mismos que para el trabajo real. Para obtener más información, consulta las descripciones de los parámetros.

    Para ver los resultados de la ejecución de prueba, consulta Cómo obtener detalles del trabajo de operaciones por lotes de almacenamiento.

  5. Después de una ejecución de prueba exitosa, ejecuta el comando gcloud storage batch-operations jobs create.

    gcloud storage batch-operations jobs create JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG

    Los parámetros son los siguientes:

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

    • --bucket: BUCKET es el nombre del bucket que contiene los objetos que deseas procesar.

    • --bucket-list: BUCKET_LIST es una lista separada por comas de uno o más nombres de bucket que contienen los objetos que deseas procesar. Puedes especificar hasta 1,000 buckets de cualquier proyecto, siempre y cuando cada bucket esté inscrito en un plan de almacenamiento inteligente.

    • OBJECT_SELECTION_FLAG es una de las siguientes marcas que debes especificar:

      • --included-object-prefixes: Especifica uno o más prefijos de objetos. Por ejemplo:

        • Para hacer coincidir un solo prefijo, usa --included-object-prefixes='prefix1'.
        • Para hacer coincidir varios prefijos, usa una lista de prefijos separados por comas: --included-object-prefixes='prefix1,prefix2'.
        • Para incluir todos los objetos, usa un prefijo vacío: --included-object-prefixes=''.

      • --manifest-location: Especifica la ubicación del manifiesto. Por ejemplo, gs://bucket_name/path/object_name.csv.

    • JOB_TYPE_FLAG es una de las siguientes marcas que debes especificar, según el tipo de trabajo.

      • --delete-object: Borra uno o más objetos.

        • Si el control de versiones de objetos está habilitado para el bucket, los objetos actuales pasan a un estado no actual y se omiten los objetos no actuales.

        • Si el control de versiones de objetos está inhabilitado para el bucket, la operación de borrado borra los objetos de forma permanente y omite los objetos no actuales.

      • --enable-permanent-object-deletion: Borra objetos de forma permanente. Usa esta marca junto con la marca --delete-object para borrar de forma permanente los objetos activos y no actuales de un bucket, independientemente de la configuración del control de versiones de objetos del bucket.

      • --rewrite-object: Actualiza las claves de encriptación administradas por el cliente para uno o más objetos. También puedes usar esta marca para cambiar la clase de almacenamiento del objeto especificando la clave storage-class. Las clases de almacenamiento admitidas incluyen STANDARD, NEARLINE, COLDLINE y ARCHIVE. Por ejemplo, --rewrite-object=storage-class=NEARLINE.

      • --set-object-acls-from-file: Parchea las listas de control de acceso (LCA) de objetos. Proporciona un archivo JSON o YAML con los permisos que se agregarán o actualizarán para entidades como allUsers o allAuthenticatedUsers. Por ejemplo: --set-object-acls-from-file=acl-updates.yaml o --set-object-acls-from-file=acl-updates.json.

        La estructura del archivo YAML para las actualizaciones es la siguiente:

        grants:
  - entity: allAuthenticatedUsers
    role: READER
  remove_entities:
  - allUsers

        La estructura del archivo JSON para las actualizaciones es la siguiente:

        {
"grants": [
  {
    "entity": "allAuthenticatedUsers",
    "role": "READER"
  }
],
"remove_entities": [
  "allUsers"
]
}

      • --put-object-event-based-hold: Habilita las retenciones de objetos basadas en eventos.

      • --no-put-object-event-based-hold: Inhabilita las retenciones de objetos basadas en eventos.

      • --put-object-temporary-hold: Habilita las retenciones de objetos temporales.

      • --no-put-object-temporary-hold: Inhabilita las retenciones de objetos temporales.

        En el siguiente ejemplo, se muestra cómo crear un trabajo para actualizar los metadatos de Content-Language a en para todos los objetos que se enumeran en 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

        En el siguiente ejemplo, se muestra cómo crear un trabajo que segmenta varios buckets para actualizar Content-Language a en-us:

        gcloud storage batch-operations jobs create my-job \
--bucket-list=bucket1,bucket2 \
--included-object-prefixes='' \
--put-metadata=Content-Language=en-us

      • --put-metadata: Actualiza los metadatos del objeto. Especifica el par clave-valor para los metadatos del objeto que deseas modificar. Puedes especificar uno o más pares clave-valor como una lista. También puedes establecer configuraciones de retención de objetos con la marca --put-metadata. Para ello, especifica los parámetros de retención con los campos Retain-Until y Retention-Mode. Por ejemplo:

        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

        Aquí:

        • RETAIN_UNTIL_TIME es la fecha y hora, en formato RFC 3339, hasta la cual se retiene el objeto. Por ejemplo, 2025-10-09T10:30:00Z. Para establecer la configuración de retención en un objeto, deberás habilitar la retención en el bucket que contiene el objeto.

        • RETENTION_MODE es el modo de retención, ya sea Unlocked o Locked.

          Cuando envíes una solicitud para actualizar los campos RETENTION_MODE y RETAIN_UNTIL_TIME, ten en cuenta lo siguiente:

          • Para actualizar la configuración de retención de objetos, debes proporcionar valores no vacíos para los campos RETENTION_MODE y RETAIN_UNTIL_TIME. Si solo estableces uno, se generará un error INVALID_ARGUMENT.
          • Puedes extender el valor de RETAIN_UNTIL_TIME para los objetos en los modos Unlocked o Locked.
          • La retención de objetos debe estar en modo Unlocked si deseas realizar las siguientes acciones:
            • Reduce el valor de RETAIN_UNTIL_TIME.
            • Quita la configuración de retención. Para quitar la configuración, deberás proporcionar valores vacíos para los campos RETENTION_MODE y RETAIN_UNTIL_TIME.
          • Si omites los campos RETENTION_MODE y RETAIN_UNTIL_TIME, la configuración de retención no se modificará.

      • --clear-all-object-custom-contexts: Borra todos los contextos de objetos existentes.

        En el siguiente ejemplo, se muestra cómo crear un trabajo para borrar todos los contextos de objetos que se enumeran en 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: Quita los contextos con claves específicas. También puedes actualizar contextos específicos y quitar claves usando la marca --clear-object-custom-contexts y una de las siguientes marcas:

        • --update-object-custom-contexts: Proporciona un mapa de pares clave-valor.

          En el siguiente ejemplo, se muestra cómo crear un trabajo para quitar el contexto con la clave temp-id y actualizar o insertar el contexto con las claves project-id y cost-center para todos los objetos que se enumeran en 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: Proporciona la ruta de acceso a un archivo JSON o YAML con pares clave-valor.

          En el siguiente ejemplo, se muestra cómo crear un trabajo para procesar objetos definidos en manifest.csv. El trabajo hace lo siguiente:

          • Quita todos los contextos con la clave temp-id.

          • Actualiza los contextos existentes con las claves project-id y cost-center definidas en el archivo /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

          En el ejemplo anterior, /tmp/context_updates.json contiene los siguientes contextos de objeto:

          {
"project-id": {"value": "project-A"},
"cost-center": {"value": "engineering"}
}

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

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

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

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

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

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

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

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

API de JSON

Para definir la lista de objetos de tu trabajo de operación por lotes, puedes elegir una de las siguientes configuraciones de origen:

  • El proyecto como fuente: Segmenta objetos en todo el proyecto con una configuración de projectSource. En lugar de enumerar prefijos o buckets individuales, puedes especificar parámetros de filtros avanzados para consultar los metadatos de estadísticas de almacenamiento de forma dinámica. Para obtener más información, consulta la pestaña de la API de JSON en Crea un trabajo con filtros avanzados.
  • Buckets como fuente: Segmenta objetos dentro de buckets específicos con una configuración bucketList. Debes especificar los buckets de destino y un archivo CSV de manifiesto (manifest_location) o prefijos de objeto (include_object_prefixes).

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Crea un archivo JSON que contenga la configuración del trabajo de operaciones por lotes de almacenamiento. A continuación, se indican las opciones de configuración comunes que puedes incluir:

    {
        "Description": "JOB_DESCRIPTION",
        "BucketList":
        {
        "Buckets":
        [
         {
           "Bucket": "BUCKET_NAME",
           "Manifest": {
              "manifest_location": "MANIFEST_LOCATION"
               }
           "PrefixList": {
              "include_object_prefixes": "OBJECT_PREFIXES"
               }
         }
        ]
        },
        "DeleteObject":
        {
        "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
         }
        "RewriteObject": {
          "kms_key":"KMS_KEY_VALUE",
          "storage_class":"STORAGE_CLASS_VALUE"
          }
        "PutMetadata":{
          "METADATA_KEY": "METADATA_VALUE",
          ...,
          "objectRetention": {
              "retainUntilTime": "RETAIN_UNTIL_TIME",
              "mode": "RETENTION_MODE"
             }
           }
        "PutObjectHold": {
          "temporary_hold": TEMPORARY_HOLD_VALUE,
          "event_based_hold": EVENT_BASED_HOLD_VALUE
        },
        "updateObjectCustomContext": {
           "customContextUpdates": {
              "updates": {
                 "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
              },
              "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
           },
           "clearAll": CLEAR_ALL_VALUE
        },
        "SetObjectAcls": {
           "accessControlsUpdates": {
              "grants": [
                 { "entity": "allUsers", "role": "READER" }
              ],
              "removeEntities": ["allAuthenticatedUsers"]
           }
        },
        "dryRun": DRY_RUN_VALUE
        }
         
    Where:

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

    • JOB_DESCRIPTION es la descripción del trabajo de operaciones por lotes en objetos almacenados.

    • BUCKET_NAME es el nombre del bucket que contiene uno o más objetos que deseas procesar.

    • Para especificar los objetos que deseas procesar, usa cualquiera de los siguientes atributos en el archivo JSON:

      • MANIFEST_LOCATION es la ubicación del manifiesto. Por ejemplo, gs://bucket_name/path/object_name.csv.

      • OBJECT_PREFIXES es la lista separada por comas que contiene uno o más prefijos de objetos. Para que coincida con todos los objetos, usa una lista vacía.

    • Según el trabajo que quieras procesar, especifica una de las siguientes opciones:

      • Borra objetos:

        "DeleteObject":
  {
  "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
  }

        Aquí, OBJECT_DELETION_VALUE es TRUE para borrar objetos.

      • Actualiza la clave de encriptación administrada por el cliente para los objetos:

        "RewriteObject":
  {
  "kms_key": KMS_KEY_VALUE
  }

        Aquí, KMS_KEY_VALUE es el valor de la clave de KMS del objeto que deseas actualizar.

      • Actualiza la clase de almacenamiento de los objetos:

        "RewriteObject":
  {
  "storage_class": STORAGE_CLASS_VALUE
  }

        Donde STORAGE_CLASS_VALUE es la nueva clase de almacenamiento a la que deseas hacer la transición de los objetos. Las clases de almacenamiento admitidas incluyen STANDARD, NEARLINE, COLDLINE y ARCHIVE.

      • Actualiza los metadatos del objeto:

        "PutMetadata": {
     "METADATA_KEY": "METADATA_VALUE",
     ...,
    "objectRetention": {
       "retainUntilTime": "RETAIN_UNTIL_TIME",
       "mode": "RETENTION_MODE"
     }
   }

        Aquí:

        • METADATA_KEY/VALUE es el par clave-valor de los metadatos del objeto. Puedes especificar uno o más pares.
        • RETAIN_UNTIL_TIME es la fecha y hora, en formato RFC 3339, hasta la cual se retiene el objeto. Por ejemplo, 2025-10-09T10:30:00Z Para establecer la configuración de retención en un objeto, deberás habilitar la retención en el bucket que contiene el objeto.
        • RETENTION_MODE es el modo de retención, que puede ser Unlocked o Locked.

          Cuando envíes una solicitud para actualizar los campos RETENTION_MODE y RETAIN_UNTIL_TIME, ten en cuenta lo siguiente:

          • Para actualizar la configuración de retención de objetos, debes proporcionar valores no vacíos para los campos RETENTION_MODE y RETAIN_UNTIL_TIME. Si solo estableces uno, se generará un error INVALID_ARGUMENT.
          • Puedes extender el valor de RETAIN_UNTIL_TIME para los objetos en los modos Unlocked o Locked.
          • La retención de objetos debe estar en modo Unlocked si deseas realizar las siguientes acciones:
            • Reduce el valor de RETAIN_UNTIL_TIME.
            • Quita la configuración de retención. Para quitar la configuración, deberás proporcionar valores vacíos para los campos RETENTION_MODE y RETAIN_UNTIL_TIME.
          • Si omites los campos RETENTION_MODE y RETAIN_UNTIL_TIME, la configuración de retención no se modificará.

        • Actualiza las conservaciones de objetos:

          "PutObjectHold": {
    "temporary_hold": TEMPORARY_HOLD_VALUE,
    "event_based_hold": EVENT_BASED_HOLD_VALUE
  }

          Aquí:

          • TEMPORARY_HOLD_VALUE se usa para habilitar o inhabilitar la conservación temporal del objeto. Un valor de 1 habilita la retención, y un valor de 2 la inhabilita.

          • EVENT_BASED_HOLD_VALUE se usa para habilitar o inhabilitar la conservación de objetos basada en eventos. Un valor de 1 habilita la retención, y un valor de 2 la inhabilita.

        • Actualiza los contextos de objetos:

          "updateObjectCustomContext": {
    "customContextUpdates": {
      "updates": {
        "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
      },
      "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
    },
    "clearAll": CLEAR_ALL_VALUE
  }

          Aquí:

          • CONTEXT_KEY es la clave del contexto del objeto que se insertará o actualizará.
          • CONTEXT_VALUE es el valor del contexto del objeto para la clave.
          • CONTEXT_KEY_TO_CLEAR es la clave que se quitará.
          • CLEAR_ALL_VALUE se establece en true para borrar todos los contextos de objetos existentes.

        • Actualiza las listas de control de acceso (LCA) de objetos:

          "SetObjectAcls": {
    "accessControlsUpdates": {
       "grants": [
          { "entity": "ENTITY_NAME", "role": "ROLE_NAME" }
       ],
       "removeEntities": ["ENTITY_TO_REMOVE"]
    }
  }

          Aquí:

          • ENTITY_NAME es la entidad a la que se agregará o actualizará el acceso. Por ejemplo, allUsers, allAuthenticatedUsers o un usuario o grupo específico.
          • ROLE_NAME es el rol que se otorgará. Por ejemplo: READER, OWNER.
          • ENTITY_TO_REMOVE es la entidad cuyas credenciales deseas quitar.

      • DRY_RUN_VALUE es un valor booleano opcional. Se establece en true para ejecutar el trabajo en modo de ejecución de prueba. El valor predeterminado es false.

      1. Usa curl para llamar a la API de JSON con una solicitud de POSTtrabajo de operaciones por lotes de almacenamiento:

        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"

        Aquí:

        • JSON_FILE_NAME es el nombre del archivo JSON.
        • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project

        • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Obtén detalles del trabajo de operaciones de almacenamiento por lotes

En esta sección, se describe cómo obtener los detalles del trabajo de operaciones por lotes de almacenamiento.

Para obtener los permisos que necesitas para ver un trabajo de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket asociado con la operación.
  3. En la página Detalles del bucket, haz clic en la pestaña Operaciones.
  4. En la lista de operaciones, haz clic en el ID de operación del trabajo que deseas ver.
  5. En la página de detalles, se muestran las métricas de tu trabajo en la pestaña Descripción general, como los objetos descubiertos, los procesados y los errores que se produjeron.
  6. En la tabla Resumen de errores, revisa los detalles de las fallas de ejecución o haz clic en Ver en Cloud Logging para ver los registros.
  7. Para ver la configuración del trabajo, haz clic en la pestaña Configuración.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs describe.

    gcloud storage batch-operations jobs describe JOB_NAME

    Aquí:

    JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

    Cuando ejecutas una ejecución de prueba de un trabajo, el resultado incluye los siguientes campos:

    • totalObjectCount: Muestra la cantidad de objetos que coinciden con los criterios de selección.
    • errorSummaries: Enumera los errores que se encontraron durante la ejecución de prueba, como problemas de permisos o configuraciones no válidas.
    • totalBytesFound: Muestra el tamaño total de los objetos afectados. Este campo solo aparece cuando usas prefijos de objetos para la selección de objetos.

    Si se realiza de forma correcta, la respuesta del trabajo de ejecución de prueba se verá similar al siguiente ejemplo:

      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

    Una respuesta de trabajo exitosa omite el campo dryRun y devuelve las siguientes métricas en el campo counters:

    • Es la cantidad total de objetos encontrados.
    • Cantidad total de bytes encontrados cuando se usan prefijos de objetos.
    • Transformaciones de objetos exitosas.
    • Transformaciones de objetos fallidas, si corresponde
    • Contextos de objetos creados, si corresponde.
    • Se borraron los contextos de objetos, si corresponde.
    • Se actualizaron los contextos de objetos, si corresponde. Este contador hace un seguimiento de las actualizaciones realizadas en las claves de contexto existentes.

    La respuesta para una ejecución de trabajo real se parece al siguiente ejemplo:

      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 cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

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

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

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

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

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

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Usa cURL para llamar a la API de JSON con una solicitud de GETtrabajo de operaciones por lotes de almacenamiento:

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

    Aquí:

    • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project
    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

    Cuando ejecutas una ejecución de prueba de un trabajo, el resultado incluye los siguientes campos:

    • totalObjectCount: Muestra la cantidad de objetos que coinciden con los criterios de selección.
    • errorSummaries: Enumera los errores que se encontraron durante la ejecución de prueba, como problemas de permisos o configuraciones no válidas.
    • totalBytesFound: Muestra el tamaño total de los objetos afectados. Este campo solo aparece cuando usas prefijos de objetos para la selección de objetos.

    Si se realiza de forma correcta, la respuesta de la ejecución de prueba se verá como el siguiente ejemplo:

    {
  "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
}

    Una respuesta de trabajo exitosa omite el campo dryRun y devuelve las siguientes métricas en el campo counters:

    • Es la cantidad total de objetos encontrados.
    • Cantidad total de bytes encontrados cuando se usan prefijos de objetos.
    • Transformaciones de objetos exitosas.
    • Transformaciones de objetos fallidas, si corresponde
    • Contextos de objetos creados, si corresponde.
    • Se borraron los contextos de objetos, si corresponde.

    • Se actualizaron los contextos de objetos, si corresponde. Este contador hace un seguimiento de las actualizaciones realizadas en las claves de contexto existentes.

      La respuesta para una ejecución de trabajo real se parece al siguiente ejemplo:

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

Enumera las operaciones de bucket

En el caso de los trabajos que incluyen varios buckets, puedes ver el progreso y el estado de las operaciones en buckets individuales. Para enumerar las operaciones realizadas en los buckets de un trabajo específico, ejecuta el comando gcloud storage batch-operations bucket-operations list:

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

También puedes filtrar la lista para que muestre buckets específicos con la marca --buckets:

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

En el siguiente ejemplo, se muestra cómo enumerar las operaciones de bucket1 y bucket2 para el trabajo my-job:

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

Aquí:

  • JOB_NAME es el nombre único del trabajo de operaciones por lotes de almacenamiento que creaste. Por ejemplo, my-job
  • BUCKET_NAME_LIST es una lista separada por comas de nombres de bucket, sin espacios entre los nombres. Por ejemplo, bucket1,bucket2

Describe una operación de bucket

Para ver los detalles de una operación de bucket específica, puedes usar cualquiera de los siguientes métodos:

  • Usa el comando gcloud storage batch-operations bucket-operations describe con la marca del nombre del recurso de la operación:

    gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_RESOURCE_NAME

    Aquí:

    • BUCKET_OPERATION_RESOURCE_NAME es la ruta de acceso completa del recurso de la operación del bucket. Por ejemplo, projects/my-project/locations/global/jobs/my-job/bucketOperations/bo-1

  • Usa el comando gcloud storage batch-operations bucket-operations describe con las marcas de ID de operación y de ID de trabajo del bucket de operación:

    gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_ID --job=JOB_NAME

    Aquí:

    • BUCKET_OPERATION_ID es el ID de la operación del bucket.
    • JOB_NAME es el nombre único del trabajo de operaciones por lotes de almacenamiento que creaste. Por ejemplo, my-job

Enumera los trabajos de operaciones de almacenamiento por lotes

En esta sección, se describe cómo enumerar los trabajos de operaciones por lotes de almacenamiento dentro de un proyecto.

Para obtener los permisos que necesitas para enumerar los trabajos de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket asociado con la operación.
  3. En la página Detalles del bucket, haz clic en la pestaña Operaciones. En la página Operaciones, se muestra una lista de las operaciones en ejecución activas.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs list.

    gcloud storage batch-operations jobs list

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

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

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

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

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

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

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Usa cURL para llamar a la API de JSON con una solicitud de LISTtrabajos de operaciones por lotes de almacenamiento:

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

    Aquí:

    PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project

Cancela un trabajo de operaciones de almacenamiento por lotes

En esta sección, se describe cómo cancelar un trabajo de operaciones por lotes de almacenamiento dentro de un proyecto.

Para obtener los permisos que necesitas para cancelar un trabajo de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket asociado con la operación por lotes en objetos almacenados que deseas cancelar.

  3. Haz clic en la pestaña Operaciones. En esta pestaña, se muestra una lista de trabajos de operaciones por lotes. Solo puedes cancelar los trabajos que estén en curso.

  4. En la lista de operaciones, selecciona uno o varios trabajos que quieras cancelar y, luego, haz clic en Cancelar.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs cancel.

    gcloud storage batch-operations jobs cancel JOB_NAME

    Aquí:

    JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

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

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

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

    $storageBatchOperationsClient->cancelJob($request);

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

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Usa cURL para llamar a la API de JSON con una solicitud de CANCEL un trabajo de operaciones por lotes de almacenamiento:

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

    Aquí:

    • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Borra un trabajo de operaciones de almacenamiento por lotes

En esta sección, se describe cómo borrar un trabajo de operaciones por lotes de almacenamiento.

Para obtener los permisos que necesitas para borrar un trabajo de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket asociado con la operación por lotes en objetos almacenados que deseas borrar.

  3. Haz clic en la pestaña Operaciones. En esta pestaña, se muestra una lista de trabajos de operaciones por lotes. Solo puedes borrar los trabajos que no se estén ejecutando, como los que se completaron, fallaron o se cancelaron.

  4. En la lista de operaciones, selecciona uno o varios trabajos que quieras borrar y, luego, haz clic en Borrar.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs delete.

    gcloud storage batch-operations jobs delete JOB_NAME

    Aquí:

    JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente. 

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

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

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

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

    $storageBatchOperationsClient->deleteJob($request);

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

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Usa cURL para llamar a la API de JSON con una solicitud de DELETE un trabajo de operaciones por lotes de almacenamiento:

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

    Aquí:

    • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Crea un trabajo de operaciones por lotes de almacenamiento con conjuntos de datos de Storage Insights

Para ejecutar un trabajo de operaciones por lotes en los objetos que se enumeran en un conjunto de datos, selecciona una de las siguientes opciones:

  • Usar filtros avanzados: Filtra objetos de forma dinámica a nivel del proyecto directamente en el comando de Google Cloud CLI.

    Los conjuntos de datos de Storage Insights se crean a partir de instantáneas periódicas de un momento determinado de los metadatos de tu almacenamiento. Cada instantánea tiene una hora que muestra cuándo se capturaron los metadatos. Cuando ejecutas un trabajo por lotes con filtros avanzados, esta hora de instantánea determina qué objetos y versiones se procesan. De forma predeterminada, las operaciones por lotes de Storage seleccionan automáticamente la hora de la instantánea más reciente. Para evitar operaciones con datos desactualizados, la creación del trabajo falla si la instantánea seleccionada tiene más de dos días de antigüedad. Para obtener información sobre cómo resolver este error, consulta Soluciona problemas de operaciones por lotes de Storage.

  • Usa un archivo de manifiesto: Genera un archivo de manifiesto CSV ejecutando una consulta de BigQuery y, luego, proporciónalo al trabajo.

Los métodos se describen en las siguientes secciones.

Cómo usar filtros avanzados

En lugar de crear un archivo de manifiesto, puedes usar filtros de Common Expression Language (CEL) para seleccionar objetos directamente según los campos de tu conjunto de datos de Storage Insights. Puedes ejecutar trabajos en varios buckets de un proyecto. Cuando usas filtros de conjuntos de datos para la selección de objetos, las operaciones por lotes de almacenamiento se dirigen a los objetos activos y actuales a partir de la instantánea del conjunto de datos seleccionado. Por lo tanto, el trabajo solo incluye objetos que tienen un valor de NULL para softDeleteTime y timeDeleted en el momento de la instantánea.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. Ejecuta el comando gcloud storage batch-operations jobs create:

    gcloud storage batch-operations jobs create JOB_NAME \
{--insights-dataset-config=INSIGHTS_DATASET_CONFIG_RESOURCE_NAME --target-project=TARGET_PROJECT [--bucket-filters=BUCKET_FILTER_CEL] [--object-filters=OBJECT_FILTER_CEL] [--target-locations=TARGET_LOCATIONS] [--target-snapshot-time=TARGET_SNAPSHOT_TIME] | --dry-run-job-id=DRY_RUN_JOB_ID} \
--JOB_TYPE_FLAG

    Aquí:

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.
    • INSIGHTS_DATASET_CONFIG_RESOURCE_NAME: Es el nombre del recurso de la configuración del conjunto de datos. Por ejemplo: projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}. Debes especificar este parámetro antes de usar las marcas --bucket-filters y --object-filters.
    • TARGET_PROJECT: Es el ID del proyecto o número del proyecto asociado a los recursos de destino.
    • BUCKET_FILTER_CEL y OBJECT_FILTER_CEL (opcional): Son las expresiones de filtro de CEL que se usan para seleccionar objetos. A continuación, se muestran algunos ejemplos:
      • --bucket-filters="name in ['bucket-1', 'bucket-2']"
      • --object-filters="size >= 5000 && name.endsWith('.pdf')" Para obtener información sobre los campos, los operadores y las funciones admitidos, consulta la referencia de filtros de CEL.
    • TARGET_LOCATIONS (opcional): Es una lista de ubicaciones de Cloud Storage que se usan para limitar el alcance del trabajo. Por ejemplo: us,us-central1,us-east4. Usa este parámetro para excluir las ubicaciones que experimentan una interrupción del servicio. Si solo se especifica TARGET_LOCATIONS y se omite TARGET_SNAPSHOT_TIME, el trabajo elige automáticamente la marca de tiempo de la instantánea más reciente que se completó correctamente en las vistas de atributos del objeto y del bucket en todas las ubicaciones especificadas.
    • TARGET_SNAPSHOT_TIME (opcional): Es la marca de tiempo UTC de la instantánea del conjunto de datos que se usará, en formato RFC 3339. Por ejemplo, 2026-05-03T16:00:00Z Esta instantánea debe existir en las vistas de atributos de tu bucket y objeto. Si especificas este parámetro, también debes especificar el parámetro TARGET_LOCATIONS.
    • DRY_RUN_JOB_ID: Es el identificador de un trabajo de prueba que se ejecutó anteriormente. Si especificas este parámetro, no puedes especificar ningún otro parámetro de selección de objetos, incluidos --insights-dataset-config, --target-project, --bucket-filters, --object-filters, --target-locations y --target-snapshot-time. El trabajo activo sondea todos los criterios de selección directamente desde el trabajo de simulación.
    • JOB_TYPE_FLAG: Es la marca correspondiente a la operación masiva que deseas realizar, como --put-metadata o --delete-object.

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Crea un archivo de configuración JSON que especifique los filtros del conjunto de datos y la configuración de las operaciones masivas. Por ejemplo:

    {
    "description": "JOB_DESCRIPTION",
    "projectSource": {
        "project": "projects/TARGET_PROJECT",
        "insightsDatasetConfig": "INSIGHTS_DATASET_CONFIG_RESOURCE_NAME",
        "bucketFilters": {
            "expression": "BUCKET_FILTER_CEL"
        },
        "objectFilters": {
            "expression": "OBJECT_FILTER_CEL"
        },
        "snapshotTime": "SNAPSHOT_TIME",
        "targetLocations": {
            "locations": ["LOCATION_1", "LOCATION_2"]
        }
    },
    "deleteObject": {
        "permanentObjectDeletionEnabled": OBJECT_DELETION_VALUE
    }
 }

    Aquí:

    • JOB_DESCRIPTION es la descripción del trabajo.
      • TARGET_PROJECT es el ID o el número del proyecto asociado a los objetos de destino.
    • INSIGHTS_DATASET_CONFIG_RESOURCE_NAME es el nombre del recurso completamente calificado de la configuración del conjunto de datos (por ejemplo, projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}).
    • BUCKET_FILTER_CEL es la expresión de filtro de CEL para los buckets. Por ejemplo, name in ['bucket-1', 'bucket-2'] Para obtener detalles sobre las palabras clave, los campos y los operadores admitidos, consulta la referencia de filtros de CEL.
    • OBJECT_FILTER_CEL es la expresión de filtro de CEL para los objetos. Por ejemplo, size >= 5000 && name.endsWith('.pdf')
    • snapshotTime (opcional): Es una marca de tiempo UTC específica en formato RFC 3339 (por ejemplo, "2026-05-03T16:00:00Z") que especifica qué instantánea del conjunto de datos se debe usar. Esta instantánea debe existir tanto en tu bucket como en las vistas del conjunto de datos de objetos en todas las ubicaciones objetivo. Si especificas este campo, también debes especificar el campo targetLocations.
    • targetLocations (opcional): Es un objeto JSON que especifica una lista de ubicaciones de Cloud Storage (por ejemplo, ["us", "us-central1", "us-east4"]) para filtrar el alcance del trabajo. Si las dependencias experimentan una interrupción en ubicaciones específicas, puedes limitar el trabajo a esas ubicaciones. Si solo se especifica targetLocations y se omite snapshotTime, el trabajo elige automáticamente la marca de tiempo de la instantánea más reciente que se completó correctamente en las vistas de atributos del objeto y del bucket en todas las ubicaciones especificadas.
    • OBJECT_DELETION_VALUE es el valor booleano que activa o desactiva el borrado permanente. Por ejemplo, true o false.

  3. Envía una solicitud POST con cURL para ejecutar el trabajo:

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

    Aquí:

    • JSON_FILE_NAME es el nombre del archivo JSON.
    • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project
    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

Usa un archivo de manifiesto

Para obtener los permisos que necesitas para crear un trabajo de operaciones por lotes de almacenamiento, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea un manifiesto con conjuntos de datos de Storage Insights

Puedes crear el manifiesto para tu trabajo de operaciones por lotes de almacenamiento extrayendo datos de BigQuery. Para ello, deberás consultar el conjunto de datos vinculado, exportar los datos resultantes como un archivo CSV y guardarlos en un bucket de Cloud Storage. Luego, el trabajo de operaciones por lote en objetos almacenados puede usar este archivo CSV como manifiesto.

Ejecutar la siguiente consulta en SQL en BigQuery en una vista del conjunto de datos de Storage Insights recupera los objetos mayores que 1 KiB que se llaman 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

Aquí:

  • URI es el URI del bucket que contiene el manifiesto. Por ejemplo, gs://bucket_name/path_to_csv_file/*.csv Cuando usas el comodín *.csv, BigQuery exporta el resultado a varios archivos CSV.
  • OVERWRITE_VALUE es un valor booleano. Si se configura como true, la operación de exportación reemplaza los archivos existentes en la ubicación especificada.

  • DATASET_VIEW_NAME es el nombre completamente calificado de la vista del conjunto de datos de Storage Insights en formato PROJECT_ID.DATASET_ID.VIEW_NAME. Para encontrar el nombre de tu conjunto de datos, consulta el conjunto de datos vinculado.

    Aquí:

    • PROJECT_ID es el ID o el número del proyecto. Por ejemplo, my-project
    • DATASET_ID es el nombre del conjunto de datos. Por ejemplo, objects-deletion-dataset
    • VIEW_NAME es el nombre de la vista del conjunto de datos. Por ejemplo, bucket_attributes_view

  • BUCKET_NAME es el nombre del depósito. Por ejemplo, my-bucket

  • SNAPSHOT_TIME es la fecha y hora de la instantánea de la vista del conjunto de datos de Storage Insights. Por ejemplo, 2024-09-10T00:00:00Z

Crea un trabajo de operaciones por lotes de almacenamiento con un archivo de manifiesto

Para crear un trabajo de operaciones por lotes de almacenamiento que procese los objetos incluidos en el manifiesto, completa los siguientes pasos:

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket que contiene los objetos en los que deseas realizar operaciones por lotes.

    Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.

  3. Haz clic en Crear operaciones por lotes.
  4. En el panel Seleccionar operación, elige el tipo de operación:
    • Administrar conservaciones de objetos: Selecciona Conservación temporal o Conservación basada en eventos. Para obtener más información, consulta conservaciones de objetos.
    • Actualizar metadatos de objetos: Para agregar metadatos de objetos, haz lo siguiente:
      • Para agregar metadatos personalizados, completa los siguientes pasos:
        1. En el campo Clave, ingresa un nombre de clave.
        2. En el campo Valor, ingresa un valor para esa clave.
        3. Opcional: Haz clic en + Agregar elemento para agregar más pares clave-valor.
      • Para actualizar los metadatos de clave fija, completa los siguientes pasos:
        1. Para expandir la sección Actualiza los metadatos de clave fija, haz clic en la flecha de expansión .
        2. En la lista Seleccionar uno o más metadatos para actualizar, selecciona los elementos de metadatos que deseas editar.
    • Actualizar o rotar la clave de encriptación: Para usar o actualizar la clave de encriptación de los objetos, haz lo siguiente:
      1. En la lista Selecciona una clave de Cloud KMS, elige una clave de encriptación administrada por el cliente (CMEK).
      2. Opcional: Selecciona Cambiar proyecto para elegir una clave de otro proyecto o selecciona Ingresar clave de forma manual para completar los detalles.
    • Borrar objetos: Para borrar objetos, haz lo siguiente:
      1. Verifica si el control de versiones de objetos está habilitado.

      2. Si el control de versiones de objetos está habilitado, elige una de las siguientes opciones de eliminación:

        • Selecciona Borrar todas las versiones de los objetos para quitar las versiones publicadas y las no actuales.
        • Selecciona Borrar versiones publicadas de forma permanente para quitar solo la versión publicada.

        Si el control de versiones de objetos no está habilitado, los objetos seleccionados para su eliminación se borrarán de forma permanente.

  5. Haz clic en Siguiente.
  6. En el panel Nombre de la operación y especificación de objetos, haz lo siguiente:
    1. En el campo Nombre, ingresa un nombre.
    2. Opcional: en el campo Descripción, ingresa una descripción.
    3. En la sección Especificar objetos, selecciona Subir listas de objetos con archivos CSV de manifiesto y, luego, haz lo siguiente:

      1. Sube tu archivo CSV de manifiesto a un bucket. Este archivo debe contener encabezados para Bucket name, Object key y número de generación.
      2. En la lista Selecciona el modo del archivo de manifiesto, elige una de las siguientes opciones:
        • Si seleccionas Seleccionar un archivo de manifiesto de Cloud Storage, haz clic en Explorar en el campo Seleccionar un archivo de manifiesto de Cloud Storage. En el diálogo Select object que aparece, navega hasta tu archivo CSV de manifiesto y, luego, haz clic en Select.
        • Si seleccionas Selecciona varios archivos de manifiesto con comodines, ingresa la ruta de acceso del archivo en el campo Ingresa la ubicación del archivo de manifiesto con comodines. Por ejemplo, bucket-name/folder/manifest_*.
  7. Haz clic en Crear.

Línea de comandos

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. En tu entorno de desarrollo, ejecuta el comando gcloud storage batch-operations jobs create:

    gcloud storage batch-operations jobs create \
JOB_NAME \
{--bucket=SOURCE_BUCKET | --bucket-list=SOURCE_BUCKET_LIST} \
--manifest-location=URI \
JOB_TYPE_FLAG

    Aquí:

    • JOB_NAME es el nombre del trabajo de operaciones por lotes de almacenamiento.

    • SOURCE_BUCKET es el nombre del bucket que contiene los objetos que deseas procesar. Por ejemplo, my-bucket

    • SOURCE_BUCKET_LIST es una lista separada por comas de uno o más nombres de bucket que contienen los objetos que deseas procesar. Por ejemplo, bucket1,bucket2

    • URI es el URI del bucket que contiene el manifiesto. Por ejemplo, gs://bucket_name/path_to_csv_file/*.csv Cuando usas el comodín *.csv, BigQuery exporta el resultado a varios archivos CSV.

    • JOB_TYPE_FLAG es una de las siguientes marcas, según el tipo de trabajo.

      • --delete-object: Borra uno o más objetos.

      • --put-metadata: Actualiza los metadatos del objeto. Los metadatos de los objetos se almacenan como pares clave-valor. Especifica el par clave-valor de los metadatos que deseas modificar. Puedes especificar uno o más pares clave-valor como una lista. También puedes proporcionar configuraciones de retención de objetos con la marca --put-metadata.

      • --rewrite-object: Actualiza las claves de encriptación administradas por el cliente para uno o más objetos. También puedes usar esta marca para cambiar la clase de almacenamiento del objeto especificando la clave storage-class. Las clases de almacenamiento admitidas incluyen STANDARD, NEARLINE, COLDLINE y ARCHIVE. Por ejemplo: --rewrite-object=storage-class=NEARLINE.

      • --set-object-acls-from-file: Parchea las listas de control de acceso (LCA) de objetos. Proporciona la ruta de acceso a un archivo JSON o YAML con los permisos que se agregarán o actualizarán para entidades como allUsers o allAuthenticatedUsers. Por ejemplo: --set-object-acls-from-file=acl-updates.yaml.

      • --put-object-event-based-hold: Habilita las retenciones de objetos basadas en eventos.

      • --no-put-object-event-based-hold: Inhabilita las retenciones de objetos basadas en eventos.

      • --put-object-temporary-hold: Habilita las retenciones de objetos temporales.

      • --no-put-object-temporary-hold: Inhabilita las retenciones de objetos temporales.

      • --clear-all-object-custom-contexts: Borra todos los contextos de objetos existentes.

        En el siguiente ejemplo, se muestra cómo crear un trabajo para borrar todos los contextos de objetos que se enumeran en 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: Quita los contextos con claves específicas. También puedes actualizar contextos específicos y quitar claves usando la marca --clear-object-custom-contexts y una de las siguientes marcas:

        • --update-object-custom-contexts: Proporciona un mapa de pares clave-valor.

          En el siguiente ejemplo, se muestra cómo crear un trabajo para quitar el contexto con la clave temp-id y actualizar o insertar el contexto con las claves project-id y cost-center para todos los objetos que se enumeran en 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: Proporciona la ruta de acceso a un archivo JSON o YAML con pares clave-valor.

          En el siguiente ejemplo, se muestra cómo crear un trabajo para procesar objetos definidos en manifest.csv. El trabajo hace lo siguiente:

          • Quita todos los contextos con la clave temp-id.

          • Actualiza los contextos existentes con las claves project-id y cost-center definidas en el archivo /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

          En el ejemplo anterior, /tmp/context_updates.json contiene los siguientes contextos de objeto:

          {
"project-id": {"value": "project-A"},
"cost-center": {"value": "engineering"}
}

Integración con los Controles del servicio de VPC

Los Controles del servicio de VPC proporcionan una capa adicional de seguridad para los recursos de las operaciones por lotes de almacenamiento. Si colocas proyectos dentro de un perímetro de servicio, ayudarás a proteger los recursos y servicios de las solicitudes que se originan fuera del perímetro. Para obtener más información sobre los detalles del perímetro de servicio de los Controles del servicio de VPC para las operaciones por lotes de almacenamiento, consulta Productos admitidos y limitaciones.

Usa los registros de auditoría de Cloud para los trabajos de operaciones por lotes de almacenamiento

Los trabajos de operaciones por lotes de almacenamiento registran transformaciones en objetos de Cloud Storage en los registros de auditoría de Cloud de Cloud Storage. Usa los Registros de auditoría de Cloud con Cloud Storage para hacer un seguimiento de estas transformaciones. Para obtener detalles sobre cómo habilitar los registros de auditoría, consulta Habilita los registros de auditoría. En la entrada de registro de auditoría, un campo de metadatos callUserAgent con el valor StorageBatchOperations indica que las operaciones por lotes de almacenamiento realizaron la transformación.

Próximos pasos