Borrar objetos

En esta página, se muestra cómo borrar objetos de tus buckets en Cloud Storage. Para obtener una descripción general de los métodos de borrado de objetos, consulta Acerca del borrado de objetos.

Roles obligatorios

Para obtener los permisos que necesitas para borrar objetos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el bucket que contiene los objetos que deseas borrar:

Borra objetos con Google Cloud CLI o las APIs de REST: Usuario de objetos de Storage (roles/storage.objectUser)
Borra objetos con la consola de Google Cloud : Administrador de Storage (roles/storage.admin)
Como alternativa, para borrar objetos con la consola de Google Cloud , haz lo siguiente: Visualizador (roles/viewer) y Usuario de objetos de Storage (roles/storage.objectUser)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para borrar objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para borrar objetos:

Borra objetos: storage.objects.delete
Enumera los objetos con la consola de Google Cloud o con la marca --recursive o comodines en Google Cloud CLI: storage.objects.list
Enumera los buckets con la consola de Google Cloud : storage.buckets.list

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Cómo borrar un solo objeto

En esta sección, se muestra cómo borrar un objeto a la vez.

Sigue estos pasos para borrar un solo objeto:

Console

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

Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto que deseas borrar.

Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.
Navega hasta el objeto, que puede estar en una carpeta.
Selecciona la casilla de verificación del objeto que deseas borrar.
Haz clic en Borrar y, luego, en Borrar en el diálogo que aparece.

Línea de comandos

Usa el comando gcloud storage rm de Google Cloud CLI:

gcloud storage rm gs://BUCKET_NAME/OBJECT_NAME

Aquí:

BUCKET_NAME es el nombre del bucket que contiene el objeto que deseas borrar. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre del objeto que deseas borrar. Por ejemplo, pets/dog.png.

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

Removing objects:
Removing gs://example-bucket/file.txt...
  Completed 1/1

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.

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  google::cloud::Status status =
      client.DeleteObject(bucket_name, object_name);

  if (!status.ok()) throw std::runtime_error(status.message());
  std::cout << "Deleted " << object_name << " in bucket " << bucket_name
            << "\n";
}

C#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage de 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.


using Google.Cloud.Storage.V1;
using System;

public class DeleteFileSample
{
    public void DeleteFile(
        string bucketName = "your-unique-bucket-name",
        string objectName = "your-object-name")
    {
        var storage = StorageClient.Create();
        storage.DeleteObject(bucketName, objectName);
        Console.WriteLine($"Deleted {objectName}.");
    }
}

Go

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

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.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// deleteFile removes specified object.
func deleteFile(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)

	// Optional: set a generation-match precondition to avoid potential race
	// conditions and data corruptions. The request to delete the file is aborted
	// if the object's generation number does not match your precondition.
	attrs, err := o.Attrs(ctx)
	if err != nil {
		return fmt.Errorf("object.Attrs: %w", err)
	}
	o = o.If(storage.Conditions{GenerationMatch: attrs.Generation})

	if err := o.Delete(ctx); err != nil {
		return fmt.Errorf("Object(%q).Delete: %w", object, err)
	}
	fmt.Fprintf(w, "Blob %v deleted.\n", object)
	return nil
}

Java

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

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.

import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DeleteObject {
  public static void deleteObject(String projectId, String bucketName, String objectName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Blob blob = storage.get(bucketName, objectName);
    if (blob == null) {
      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
      return;
    }
    BlobId idWithGeneration = blob.getBlobId();
    // Deletes the blob specified by its id. When the generation is present and non-null it will be
    // specified in the request.
    // If versioning is enabled on the bucket and the generation is present in the delete request,
    // only the version of the object with the matching generation will be deleted.
    // If instead you want to delete the current version, the generation should be dropped by
    // performing the following.
    // BlobId idWithoutGeneration =
    //    BlobId.of(idWithGeneration.getBucket(), idWithGeneration.getName());
    // storage.delete(idWithoutGeneration);
    storage.delete(idWithGeneration);

    System.out.println("Object " + objectName + " was permanently deleted from " + bucketName);
  }
}

Node.js

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

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.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Optional:
// Set a generation-match precondition to avoid potential race conditions
// and data corruptions. The request to delete is aborted if the object's
// generation number does not match your precondition. For a destination
// object that does not yet exist, set the ifGenerationMatch precondition to 0
// If the destination object already exists in your bucket, set instead a
// generation-match precondition using its generation number.
const deleteOptions = {
  ifGenerationMatch: generationMatchPrecondition,
};
async function deleteFile() {
  await storage.bucket(bucketName).file(fileName).delete(deleteOptions);

  console.log(`gs://${bucketName}/${fileName} deleted`);
}

deleteFile().catch(console.error);

PHP

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage de 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\Storage\StorageClient;

/**
 * Delete an object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 */
function delete_object(string $bucketName, string $objectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->delete();
    printf('Deleted gs://%s/%s' . PHP_EOL, $bucketName, $objectName);
}

Python

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

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.

from google.cloud import storage


def delete_blob(bucket_name, blob_name):
    """Deletes a blob from the bucket."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    generation_match_precondition = None

    # Optional: set a generation-match precondition to avoid potential race conditions
    # and data corruptions. The request to delete is aborted if the object's
    # generation number does not match your precondition.
    blob.reload()  # Fetch blob metadata to use in generation_match_precondition.
    generation_match_precondition = blob.generation

    blob.delete(if_generation_match=generation_match_precondition)

    print(f"Blob {blob_name} deleted.")

Ruby

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

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.

def delete_file bucket_name:, file_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name, skip_lookup: true
  file    = bucket.file file_name

  file.delete

  puts "Deleted #{file.name}"
end

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "deleted-object-name";
    client
        .delete_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        // Consider .set_generation() to make request idempotent
        .send()
        .await?;
    println!("successfully deleted object {NAME} in bucket {bucket_id}");
    Ok(())
}

API de REST

API de JSON

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

Usa curl para llamar a la API de JSON con una solicitud de DELETE:
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
```
Aquí:
- BUCKET_NAME es el nombre del bucket que contiene el objeto que deseas borrar. Por ejemplo, my-bucket
- OBJECT_NAME es el nombre codificado como URL del objeto que deseas borrar. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

API de XML

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

Usa curl para llamar a la API de XML con una solicitud DELETE Object:
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
Aquí:
- BUCKET_NAME es el nombre del bucket que contiene el objeto que deseas borrar. Por ejemplo, my-bucket
- OBJECT_NAME es el nombre codificado como URL del objeto que deseas borrar. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

Borra objetos de forma masiva

En esta sección, se muestra cómo borrar objetos de forma masiva seleccionándolos en la consola deGoogle Cloud , borrando objetos con un prefijo común con herramientas de línea de comandos o especificando una lista de objetos en solicitudes de API o bibliotecas cliente.

Console

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

Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto que deseas borrar.

Se abrirá la página Detalles del bucket y se seleccionará la pestaña Objetos.
Navega hasta los objetos, que pueden estar en una carpeta.
Selecciona la casilla de verificación de cada objeto que deseas borrar.

Puedes seleccionar la casilla de verificación de una carpeta, lo que borrará todos los objetos que contiene esa carpeta.
Haz clic en Borrar y, luego, en Borrar en el diálogo que aparece.

Si borras muchos objetos a la vez, puedes realizar un seguimiento del progreso de eliminación; para ello, haz clic en el ícono Notificaciones en la Google Cloud consola. La consola deGoogle Cloud puede borrar de forma masiva y en segundo plano varios millones de objetos.

Para obtener información sobre cómo ver detalles de errores acerca de operaciones fallidas de Cloud Storage en la Google Cloud consola, consulta Solución de problemas.

Línea de comandos

Google Cloud CLI

Para borrar grupos de objetos que tienen el mismo prefijo, como los objetos cuyos nombres imitan una estructura de carpeta, usa la marca --recursive con gcloud storage rm:

gcloud storage rm --recursive gs://BUCKET_NAME/PREFIX

Aquí:

BUCKET_NAME es el nombre del depósito. Por ejemplo, my-bucket
PREFIX es el prefijo común de los objetos que deseas borrar. Por ejemplo, pets/

CLI de Amazon S3

Para borrar varios objetos en Cloud Storage con la CLI de Amazon S3, usa el comando aws s3api delete-objects. Deberás redireccionar la solicitud a la API de XML de eliminación de varios objetos de Cloud Storage configurando la marca --endpoint-url en storage.googleapis.com. Para obtener definiciones detalladas de los parámetros y el comportamiento de la API de delete-objects, consulta la documentación de referencia de delete-objects de la CLI de Amazon S3.

Bibliotecas cliente

Cloud Storage admite la API de XML de eliminación de varios objetos a través de su interfaz compatible con Amazon S3. Para usar bibliotecas cliente compatibles con Amazon S3 para el borrado masivo de objetos, dirige tu solicitud al extremo Google Cloud . Para ello, establece la URL del extremo en https://storage.googleapis.com en la configuración del cliente. Este enfoque puede ser beneficioso si realizas alguna de las siguientes tareas:

Aprovechar las bases de código o las herramientas existentes ya creadas para Amazon S3
Mantener la coherencia en entornos de varias nubes que incluyen Amazon S3 y Cloud Storage

En el siguiente ejemplo, se muestra cómo inicializar un cliente con una biblioteca Boto3 para interactuar con Cloud Storage:

  import boto3
  def main():
  # Initialize the S3 client to point to the Google Cloud Storage endpoint
    client = boto3.client(
        service_name='s3',
        endpoint_url='https://storage.googleapis.com',
        aws_access_key_id='YOUR_ACCESS_ID',
        aws_secret_access_key='YOUR_SECRET',
    )
  # Perform delete operations as defined in the library's documentation
  # response = client.delete_objects(Bucket='BUCKET_NAME', Delete={'Objects': [...]})

Para obtener firmas de métodos y definiciones de parámetros específicos, consulta la documentación de delete_objects Boto3.

API de XML

Para borrar hasta 1,000 objetos en una sola solicitud con la API de XML, completa los siguientes pasos:

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

Crea un documento XML que especifique los objetos que se borrarán.

Para obtener una lista completa de los parámetros de configuración, consulta Cómo borrar varios objetos en la documentación de referencia de la API de XML. A continuación, se indican los parámetros de configuración comunes que puedes incluir en tu archivo XML:
```
<Delete>
    <Object>
      <Key>OBJECT_NAME</Key>
      <VersionId>VERSION_ID</VersionId>
    </Object>
    ...
    <Quiet>QUIET_RESPONSE_BOOLEAN</Quiet>
  </Delete>
```
Aquí:
- OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png. Puedes especificar hasta 1,000 objetos en el archivo XML.
- VERSION_ID es el ID de versión del objeto. Por ejemplo, 11111.
- QUIET_RESPONSE_BOOLEAN controla la verbosidad de la respuesta de la API:
  - Se establece en False para obtener una respuesta detallada. La respuesta incluye detalles de cada objeto, ya sea que se haya borrado correctamente o no. La operación de borrado de varios objetos con la API de XML no es atómica. Si una solicitud genera errores parciales, es posible que algunos objetos se borren correctamente, pero otros no. Por lo tanto, te recomendamos que uses la respuesta detallada para identificar todos los objetos que se borraron. Si tienes habilitados los registros de auditoría de acceso a los datos, también puedes revisar los registros de auditoría para obtener detalles sobre las fallas.
  - Se establece en True para una respuesta silenciosa. El cuerpo de la respuesta no incluye información sobre los objetos que se borraron correctamente.

Usa curl para enviar una solicitud de POST bucket a la API de XML con el parámetro de consulta ?delete y tu archivo XML:

curl -X POST --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?delete"

Aquí:

XML_FILE_NAME es el nombre del archivo XML que creaste.

BUCKET_NAME es el nombre del bucket que contiene los objetos que se borrarán.

Si el modo Quiet está inhabilitado, una respuesta detallada podría ser similar a la siguiente:

<DeleteResult>
<Deleted>
  <Key>images/photo1.jpg</Key>
  <VersionId>11111</VersionId>
</Deleted>
<Deleted>
  <Key>documents/report.pdf</Key>
  <VersionId>22222</VersionId>
</Deleted>
<Error>
  <Code>AccessDenied</Code>
  <Key>private/financial_data.xlsx</Key>
  <Message>Access Denied. You don't have permission to delete this object.</Message>
  <VersionId>33333</VersionId>
</Error>
</DeleteResult>

Si el modo Quiet está habilitado, la respuesta solo enumera los objetos que no se pudieron borrar. Si todos los objetos se borran correctamente, se devuelve una etiqueta <DeleteResult/> vacía. A continuación, se muestra un ejemplo de una respuesta silenciosa en la que se produjo un error:

<DeleteResult>
<Error>
  <Code>AccessDenied</Code>
  <Key>private/financial_data.xlsx</Key>
  <Message>Access Denied. You don't have permission to delete this object.</Message>
  <VersionId>33333</VersionId>
</Error>
</DeleteResult>

Borra hasta miles de millones de objetos

Para borrar millones o miles de millones de objetos con un solo trabajo de eliminación de objetos, usa las operaciones por lotes de Storage. Para crear un trabajo, especifica los objetos que se borrarán. Para ello, proporciona una lista de objetos en un archivo de manifiesto o usa prefijos de objetos. Después de especificar la lista de objetos, crea un trabajo de operación por lotes para borrar los objetos.

Borra objetos automáticamente con reglas de ciclo de vida de objetos

Si deseas que los objetos se borren automáticamente cuando cumplan con los criterios que especifiques, como la antigüedad o la clase de almacenamiento, usa la Administración del ciclo de vida de los objetos. Por ejemplo, puedes establecer una regla de ciclo de vida para borrar los registros que tengan más de 30 días.

Solicitudes de eliminación de objetos por lotes con la API de JSON

Para reducir la cantidad de conexiones HTTP necesarias cuando se borran muchos objetos con la API de JSON, usa las solicitudes por lotes de la API de JSON. Puedes agrupar hasta 100 llamadas a la API en una sola solicitud HTTP para ayudar a reducir la sobrecarga de la red.

¿Qué sigue?

Obtén más información para restablecer objetos borrados de forma no definitiva si borraste un objeto por accidente.
Si usas el control de versiones de objetos, ten en cuenta que borrar un objeto puede hacer que se vuelva no actual en lugar de borrarlo de forma permanente. Obtén más información para administrar o borrar de forma definitiva las versiones no actuales.
Configura la Administración del ciclo de vida de los objetos para automatizar las futuras eliminaciones de objetos.
Borra un bucket si ya no lo necesitas.

Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.

Última actualización: 2026-04-09 (UTC)