Excluir objetos

Nesta página, você aprenderá como excluir objetos em buckets do Cloud Storage. Para uma visão geral dos métodos de exclusão de objetos, consulte Sobre a exclusão de objetos.

Funções exigidas

Para receber as permissões necessárias para excluir objetos, peça ao administrador que conceda a você os seguintes papéis do IAM no bucket que contém os objetos que você quer excluir:

  • Exclua objetos usando a Google Cloud CLI ou as APIs REST: Usuário de objetos do Storage (roles/storage.objectUser)
  • Exclua objetos usando o console Google Cloud : Administrador do Storage (roles/storage.admin)
  • Outra opção é excluir objetos usando o console Google Cloud : Leitor (roles/viewer) e Usuário de objetos do Storage (roles/storage.objectUser)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para excluir objetos. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para excluir objetos:

  • Excluir objetos: storage.objects.delete
  • Liste objetos usando o console Google Cloud ou a flag --recursive ou caracteres curinga na Google Cloud CLI: storage.objects.list
  • Liste os buckets usando o console do Google Cloud : storage.buckets.list

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

Excluir um único objeto

Esta seção mostra como excluir um objeto por vez.

Siga estas etapas para excluir um único objeto:

Console

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

    Acessar buckets

  2. Na lista de buckets, clique no nome daquele que contém os objetos que você quer excluir.

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

  3. Navegue até o objeto, que pode estar localizado em uma pasta.

  4. Marque a caixa de seleção do objeto que você quer excluir.

  5. Clique em Excluir e, em seguida, clique em Excluir na caixa de diálogo exibida.

Linha de comando

Use o comando gcloud storage rm da Google Cloud CLI:

gcloud storage rm gs://BUCKET_NAME/OBJECT_NAME

Em que:

  • BUCKET_NAME é o nome do bucket que contém o objeto que você quer excluir. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto que você quer excluir. Por exemplo, pets/dog.png.

Se a operação for bem-sucedida, a resposta será semelhante a esta:

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

Bibliotecas de cliente

C++

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

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

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#

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

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


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

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de 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

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de 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

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de 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

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

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

use Google\Cloud\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

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de 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

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de 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(())
}

APIs REST

API JSON

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

  2. Use curl para chamar a API JSON com uma solicitação DELETE:

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    Em que:

    • BUCKET_NAME é o nome do bucket que contém o objeto que você quer excluir. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto que você quer excluir. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.

API XML

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

  2. Use curl (em inglês) para chamar a API XML com uma solicitação DELETE Object:

    curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Em que:

    • BUCKET_NAME é o nome do bucket que contém o objeto que você quer excluir. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto que você quer excluir. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.

Excluir objetos em massa

Esta seção mostra como excluir objetos em massa selecionando-os no consoleGoogle Cloud , excluindo objetos com um prefixo comum usando ferramentas de linha de comando ou especificando uma lista de objetos em solicitações de API ou biblioteca de cliente.

Console

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

    Acessar buckets

  2. Na lista de buckets, clique no nome daquele que contém os objetos que você quer excluir.

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

  3. Navegue até o objeto, que pode estar localizado em uma pasta.

  4. Marque a caixa de seleção de cada objeto que você quer excluir.

    Você pode marcar a caixa de seleção de uma pasta, o que exclui todos os objetos contidos nela.

  5. Clique em Excluir e, em seguida, clique em Excluir na caixa de diálogo exibida.

Se você excluir muitos objetos de uma vez, poderá acompanhar o progresso da exclusão clicando no ícone Notificações no console do Google Cloud . O consoleGoogle Cloud pode excluir em massa até vários milhões de objetos e faz isso em segundo plano.

Para saber como acessar informações detalhadas de erro sobre operações do Cloud Storage com falha no Google Cloud console, consulte Solução de problemas.

Linha de comando

CLI do Google Cloud

Para excluir grupos de objetos que possuem o mesmo prefixo, como objetos cujos nomesimitar uma estrutura de pastas, use o--recursive bandeira comgcloud storage rm:

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

Em que:

  • BUCKET_NAME é o nome do bucket. Por exemplo, my-bucket.
  • PREFIX é um prefixo comum dos objetos que você deseja excluir. Por exemplo, pets/.

CLI do Amazon S3

Para excluir vários objetos no Cloud Storage usando a CLI do Amazon S3, use o comando aws s3api delete-objects. Você precisará redirecionar a solicitação para a API XML de exclusão de vários objetos do Cloud Storage definindo o sinalizador --endpoint-url para storage.googleapis.com. Para ver definições detalhadas de parâmetros e o comportamento da API delete-objects, consulte a documentação de referência do comando delete-objects da CLI do Amazon S3.

Bibliotecas de cliente

O Cloud Storage suporta a API XML de exclusão de múltiplos objetos por meio de sua interface compatível com o Amazon S3. Para usar bibliotecas de cliente compatíveis com o Amazon S3 para exclusão em massa de objetos, direcione sua solicitação para o endpoint Google Cloud definindo o URL do endpoint como https://storage.googleapis.com na configuração do cliente. Essa abordagem pode ser útil se você estiver realizando uma das seguintes tarefas:

  • Aproveitar bases de código ou ferramentas já existentes, desenvolvidas para o Amazon S3.
  • Manter a consistência em ambientes multicloud que incluem o Amazon S3 e o Cloud Storage.

O exemplo a seguir mostra como inicializar um cliente usando uma biblioteca Boto3 para interagir com o 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 ver assinaturas de métodos e definições de parâmetros específicos, consulte a documentação do delete_objects Boto3.

API XML

Para excluir até 1.000 objetos em uma única solicitação usando a API XML, siga estas etapas:

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

  2. Crie um documento XML que especifique os objetos a serem excluídos.

    Para obter uma lista completa de configurações, consulte Excluir vários objetos na documentação de referência da API XML. As configurações comuns a serem incluídas no arquivo XML são as seguintes:

    <Delete>
    <Object>
      <Key>OBJECT_NAME</Key>
      <VersionId>VERSION_ID</VersionId>
    </Object>
    ...
    <Quiet>QUIET_RESPONSE_BOOLEAN</Quiet>
  </Delete>

    Em que:

    • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png. É possível especificar até 1.000 objetos no arquivo XML.
    • VERSION_ID é o ID da versão do objeto. Por exemplo, 11111.
    • QUIET_RESPONSE_BOOLEAN controla o nível de detalhamento da resposta da API:
      • Defina como False para uma resposta detalhada. A resposta inclui detalhes de todos os objetos, sejam eles excluídos ou não. A operação de exclusão de vários objetos usando a API XML não é atômica. Se uma solicitação resultar em falhas parciais, alguns objetos poderão ser excluídos, mas outros não. Por isso, recomendamos usar a resposta detalhada para identificar todas as exclusões de objetos. Se você tiver os registros de auditoria de acesso a dados ativados, também poderá analisar os registros de auditoria para ver detalhes de falha.
      • Defina como True para uma resposta silenciosa. O corpo da resposta não inclui informações sobre os objetos que foram excluídos.

  3. Usarcurl para enviar umPOST balde pedido aoAPI XML com o?delete parâmetro de consulta e seu arquivo XML:

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

    Em que:

    • XML_FILE_NAME é o nome do arquivo XML que você criou.

    • BUCKET_NAME é o nome do bucket que contém os objetos a serem excluídos.

      Se o modo Quiet estiver desativado, uma resposta detalhada poderá ser semelhante a esta:

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

      Se o modo Quiet estiver ativado, a resposta vai listar apenas os objetos que não foram excluídos. Se todos os objetos forem excluídos, uma tag <DeleteResult/> vazia será retornada. Segue abaixo um exemplo de uma resposta silenciosa onde ocorreu um erro:

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

Excluir até bilhões de objetos

Para excluir milhões ou bilhões de objetos com um único job de exclusão, use as operações em lote do Storage. Para criar um job, especifique os objetos a serem excluídos, fornecendo uma lista de objetos em um arquivo de manifesto ou usando prefixos de objeto. Depois de especificar a lista de objetos, crie um job de operação em lote para excluir os objetos.

Excluir objetos automaticamente usando regras de ciclo de vida de objetos

Se você quiser que os objetos sejam excluídos automaticamente quando atenderem aos critérios especificados, como idade ou classe de armazenamento, use o Gerenciamento do ciclo de vida de objetos. Por exemplo, é possível definir uma regra de ciclo de vida para excluir registros com mais de 30 dias.

Solicitações de exclusão de objetos em lote com a API JSON

Para reduzir o número de conexões HTTP necessárias ao excluir muitos objetos com a API JSON, use solicitações em lote da API JSON. É possível agrupar até 100 chamadas de API em uma única solicitação HTTP para reduzir a sobrecarga da rede.

A seguir