Usar a exclusão reversível

Visão geral Uso

Nesta página, descrevemos como ativar, desativar, atualizar e verificar o status da política de exclusão reversível em um bucket. Para saber como listar e restaurar os objetos excluídos de forma reversível, consulte Usar objetos excluídos de forma reversível. Para mais informações sobre a exclusão reversível, consulte a Visão geral. Para desativar o recurso, consulte Desativar a exclusão reversível.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar políticas de exclusão reversível, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket ou no projeto que o contém.

Esse papel predefinido contém as permissões necessárias para criar e gerenciar políticas de exclusão reversível. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar e gerenciar políticas de exclusão reversível:

storage.buckets.get
storage.buckets.update
storage.buckets.list (essa permissão é necessária se você planeja usar o console do Google Cloud para executar as instruções desta página)

Para informações sobre como conceder papéis, consulte Usar o IAM com buckets ou Gerenciar o acesso a projetos.

Editar a política de exclusão reversível de um bucket

Para ativar, desativar ou atualizar a política de exclusão reversível de um bucket:

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket com a política de exclusão reversível que você quer gerenciar.
Clique na guia Proteção.
Na seção política de exclusão reversível, execute uma das seguintes ações:
- Se o bucket não tiver uma política de exclusão reversível, clique em Editar, escolha uma unidade e um período para a duração da retenção e clique em Salvar.
- Se o bucket tiver uma política de exclusão reversível, clique em Editar para mudar a unidade e o período da duração da retenção.

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

Linha de comando

Para adicionar ou modificar a política de exclusão reversível em um bucket, use o comando gcloud storage buckets update com a sinalização --soft-delete-duration:

  gcloud storage buckets update gs://BUCKET_NAME --soft-delete-duration=SOFT_DELETE_DURATION

Em que:

BUCKET_NAME é o nome do bucket. Por exemplo, my-bucket.
SOFT_DELETE_DURATION especifica a duração para manter objetos excluídos de forma reversível. Por exemplo, 2w1d é duas semanas e um dia. Para mais informações, consulte Duração da retenção da exclusão reversível.

APIs REST

API JSON

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

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Crie um arquivo JSON com as informações a seguir:
```
{
  "softDeletePolicy": {
    "retentionDurationSeconds": "TIME_IN_SECONDS"
  }
}
```
Em que TIME_IN_SECONDS é o período de tempo em segundos pelo qual você quer reter objetos excluídos de forma reversível. Por exemplo, 2678400. Para mais informações, consulte Duração da retenção da exclusão reversível.

Use cURL para chamar a API JSON com uma solicitação bucket PATCH:

curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"

Em que:

JSON_FILE_NAME é o caminho para o arquivo JSON criado na Etapa 2.
BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Excluir a política de exclusão reversível de um bucket

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket com a política de exclusão reversível que você quer excluir.
Clique na guia Proteção.
Na seção Política de exclusão reversível, clique em Desativar para remover a política de exclusão reversível do bucket.
Clique em Confirmar.

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

Linha de comando

Para remover a política de exclusão reversível de um bucket, use o comando gcloud storage buckets update com a sinalização --clear-soft-delete:

  gcloud storage buckets update gs://BUCKET_NAME --clear-soft-delete

Em que:

BUCKET_NAME é o nome do bucket. Por exemplo, my-bucket.

APIs REST

API JSON

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

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Crie um arquivo JSON com as informações a seguir:
```
{
  "softDeletePolicy": {
    "retentionDurationSeconds": "TIME_IN_SECONDS"
  }
}
```
Para desativar a política de exclusão reversível de um bucket, use o valor 0 no lugar de TIME_IN_SECONDS.

Use cURL para chamar a API JSON com uma solicitação bucket PATCH:

curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"

Em que:

JSON_FILE_NAME é o caminho para o arquivo JSON criado na Etapa 2.
BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Verificar se a política de exclusão reversível está ativada em um bucket

Console

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

Acessar buckets
Na lista de buckets, clique no nome do bucket com a política de exclusão reversível que você quer verificar.
Clique na guia Proteção.

O status é mostrado na seção Política de exclusão reversível (para recuperação de dados).

Também é possível usar a guia Proteção para verificar se há uma política de exclusão reversível no bucket.

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

Linha de comando

Para verificar o status da política de exclusão reversível de um bucket, use o comando gcloud storage buckets describe:

  gcloud storage buckets describe gs://BUCKET_NAME \
      --format="default(soft_delete_policy)"

Em que:

BUCKET_NAME é o nome do bucket. Por exemplo, my-bucket.

APIs REST

API JSON

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

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

Use cURL para chamar a API JSON com uma solicitação bucket GET:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=softDeletePolicy"

Em que BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Desativar a exclusão reversível para vários buckets ou todos os buckets em um projeto

As instruções a seguir descrevem como desativar a exclusão reversível de vários ou todos os buckets em um projeto. Se você quiser desativar a exclusão reversível no nível da organização, consulte Desativar a exclusão reversível.

Console

O console do Google Cloud permite desativar a exclusão reversível para buckets classificados pelos bytes com mais exclusões reversíveis ou pela maior proporção de bytes com exclusão reversível em relação aos bytes ativos. Assim, é possível reduzir os custos gerados pelo uso da exclusão reversível.

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

Acessar buckets
Na página do Cloud Storage, clique em Configurações.
Clique na guia Fazer a exclusão reversível.
Na lista Buckets principais por bytes excluídos, selecione os buckets para os quais você quer desativar a exclusão reversível.
Clique em Desativar a exclusão reversível.

A exclusão reversível foi desativada nos buckets selecionados.

Linha de comando

Para desativar a exclusão reversível em todos os buckets de um projeto, execute o comando gcloud storage buckets update com a flag --clear-soft-delete:

gcloud storage buckets update --clear-soft-delete gs://*

Bibliotecas de cliente

Python

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

from __future__ import annotations

import argparse
import json
import google.cloud.monitoring_v3 as monitoring_client


def get_relative_cost(storage_class: str) -> float:
    """Retrieves the relative cost for a given storage class and location.

    Args:
        storage_class: The storage class (e.g., 'standard', 'nearline').

    Returns:
        The price per GB from the https://cloud.google.com/storage/pricing,
        divided by the standard storage class.
    """
    relative_cost = {
        "STANDARD": 0.023 / 0.023,
        "NEARLINE": 0.013 / 0.023,
        "COLDLINE": 0.007 / 0.023,
        "ARCHIVE": 0.0025 / 0.023,
    }

    return relative_cost.get(storage_class, 1.0)


def get_soft_delete_cost(
    project_name: str,
    soft_delete_window: float,
    agg_days: int,
    lookback_days: int,
) -> dict[str, list[dict[str, float]]]:
    """Calculates soft delete costs for buckets in a Google Cloud project.

    Args:
        project_name: The name of the Google Cloud project.
        soft_delete_window: The time window in seconds for considering
          soft-deleted objects (default is 7 days).
        agg_days: Aggregate results over a time period, defaults to 30-day period
        lookback_days: Look back up to upto days, defaults to 360 days

    Returns:
        A dictionary with bucket names as keys and cost data for each bucket,
        broken down by storage class.
    """

    query_client = monitoring_client.QueryServiceClient()

    # Step 1: Get storage class ratios for each bucket.
    storage_ratios_by_bucket = get_storage_class_ratio(
        project_name, query_client, agg_days, lookback_days
    )

    # Step 2: Fetch soft-deleted bytes and calculate costs using Monitoring API.
    soft_deleted_costs = calculate_soft_delete_costs(
        project_name,
        query_client,
        soft_delete_window,
        storage_ratios_by_bucket,
        agg_days,
        lookback_days,
    )

    return soft_deleted_costs


def calculate_soft_delete_costs(
    project_name: str,
    query_client: monitoring_client.QueryServiceClient,
    soft_delete_window: float,
    storage_ratios_by_bucket: dict[str, float],
    agg_days: int,
    lookback_days: int,
) -> dict[str, list[dict[str, float]]]:
    """Calculates the relative cost of enabling soft delete for each bucket in a
       project for certain time frame in secs.

    Args:
        project_name: The name of the Google Cloud project.
        query_client: A Monitoring API query client.
        soft_delete_window: The time window in seconds for considering
          soft-deleted objects (default is 7 days).
        storage_ratios_by_bucket: A dictionary of storage class ratios per bucket.
        agg_days: Aggregate results over a time period, defaults to 30-day period
        lookback_days: Look back up to upto days, defaults to 360 days

    Returns:
        A dictionary with bucket names as keys and a list of cost data
        dictionaries
        for each bucket, broken down by storage class.
    """
    soft_deleted_bytes_time = query_client.query_time_series(
        monitoring_client.QueryTimeSeriesRequest(
            name=f"projects/{project_name}",
            query=f"""
                    {{  # Fetch 1: Soft-deleted (bytes seconds)
                        fetch gcs_bucket :: storage.googleapis.com/storage/v2/deleted_bytes
                        | value val(0) * {soft_delete_window}\'s\'  # Multiply by soft delete window
                        | group_by [resource.bucket_name, metric.storage_class], window(), .sum;

                        # Fetch 2: Total byte-seconds (active objects)
                        fetch gcs_bucket :: storage.googleapis.com/storage/v2/total_byte_seconds
                        | filter metric.type != 'soft-deleted-object'
                        | group_by [resource.bucket_name, metric.storage_class], window(1d), .mean  # Daily average
                        | group_by [resource.bucket_name, metric.storage_class], window(), .sum  # Total over window

                    }}  # End query definition
                    | every {agg_days}d  # Aggregate over larger time intervals
                    | within {lookback_days}d  # Limit data range for analysis
                    | ratio  # Calculate ratio (soft-deleted (bytes seconds)/ total (bytes seconds))
                    """,
        )
    )

    buckets: dict[str, list[dict[str, float]]] = {}
    missing_distribution_storage_class = []
    for data_point in soft_deleted_bytes_time.time_series_data:
        bucket_name = data_point.label_values[0].string_value
        storage_class = data_point.label_values[1].string_value
        # To include location-based cost analysis:
        # 1. Uncomment the line below:
        # location = data_point.label_values[2].string_value
        # 2. Update how you calculate 'relative_storage_class_cost' to factor in location
        soft_delete_ratio = data_point.point_data[0].values[0].double_value
        distribution_storage_class = bucket_name + " - " + storage_class
        storage_class_ratio = storage_ratios_by_bucket.get(
            distribution_storage_class
        )
        if storage_class_ratio is None:
            missing_distribution_storage_class.append(
                distribution_storage_class)
        buckets.setdefault(bucket_name, []).append({
            # Include storage class and location data for additional plotting dimensions.
            # "storage_class": storage_class,
            # 'location': location,
            "soft_delete_ratio": soft_delete_ratio,
            "storage_class_ratio": storage_class_ratio,
            "relative_storage_class_cost": get_relative_cost(storage_class),
        })

    if missing_distribution_storage_class:
        print(
            "Missing storage class for following buckets:",
            missing_distribution_storage_class,
        )
        raise ValueError("Cannot proceed with missing storage class ratios.")

    return buckets


def get_storage_class_ratio(
    project_name: str,
    query_client: monitoring_client.QueryServiceClient,
    agg_days: int,
    lookback_days: int,
) -> dict[str, float]:
    """Calculates storage class ratios for each bucket in a project.

    This information helps determine the relative cost contribution of each
    storage class to the overall soft-delete cost.

    Args:
        project_name: The Google Cloud project name.
        query_client: Google Cloud's Monitoring Client's QueryServiceClient.
        agg_days: Aggregate results over a time period, defaults to 30-day period
        lookback_days: Look back up to upto days, defaults to 360 days

    Returns:
        Ratio of Storage classes within a bucket.
    """
    request = monitoring_client.QueryTimeSeriesRequest(
        name=f"projects/{project_name}",
        query=f"""
            {{
            # Fetch total byte-seconds for each bucket and storage class
            fetch gcs_bucket :: storage.googleapis.com/storage/v2/total_byte_seconds
            | group_by [resource.bucket_name, metric.storage_class], window(), .sum;
            # Fetch total byte-seconds for each bucket (regardless of class)
            fetch gcs_bucket :: storage.googleapis.com/storage/v2/total_byte_seconds
            | group_by [resource.bucket_name], window(), .sum
            }}
            | ratio  # Calculate ratios of storage class size to total size
            | every {agg_days}d
            | within {lookback_days}d
            """,
    )

    storage_class_ratio = query_client.query_time_series(request)

    storage_ratios_by_bucket = {}
    for time_series in storage_class_ratio.time_series_data:
        bucket_name = time_series.label_values[0].string_value
        storage_class = time_series.label_values[1].string_value
        ratio = time_series.point_data[0].values[0].double_value

        # Create a descriptive key for the dictionary
        key = f"{bucket_name} - {storage_class}"
        storage_ratios_by_bucket[key] = ratio

    return storage_ratios_by_bucket


def soft_delete_relative_cost_analyzer(
    project_name: str,
    cost_threshold: float = 0.0,
    soft_delete_window: float = 604800,
    agg_days: int = 30,
    lookback_days: int = 360,
    list_buckets: bool = False,
    ) -> str | dict[str, float]: # Note potential string output
    """Identifies buckets exceeding the relative cost threshold for enabling soft delete.

    Args:
        project_name: The Google Cloud project name.
        cost_threshold: Threshold above which to consider removing soft delete.
        soft_delete_window: Time window for calculating soft-delete costs (in
          seconds).
        agg_days: Aggregate results over this time period (in days).
        lookback_days: Look back up to this many days.
        list_buckets: Return a list of bucket names (True) or JSON (False,
          default).

    Returns:
        JSON formatted results of buckets exceeding the threshold and costs
        *or* a space-separated string of bucket names.
    """

    buckets: dict[str, float] = {}
    for bucket_name, storage_sources in get_soft_delete_cost(
        project_name, soft_delete_window, agg_days, lookback_days
    ).items():
        bucket_cost = 0.0
        for storage_source in storage_sources:
            bucket_cost += (
                storage_source["soft_delete_ratio"]
                * storage_source["storage_class_ratio"]
                * storage_source["relative_storage_class_cost"]
            )
        if bucket_cost > cost_threshold:
            buckets[bucket_name] = round(bucket_cost, 4)

    if list_buckets:
        return " ".join(buckets.keys())  # Space-separated bucket names
    else:
        return json.dumps(buckets, indent=2)  # JSON output


def soft_delete_relative_cost_analyzer_main() -> None:
    # Sample run: python storage_soft_delete_relative_cost_analyzer.py <Project Name>
    parser = argparse.ArgumentParser(
        description="Analyze and manage Google Cloud Storage soft-delete costs."
    )
    parser.add_argument(
        "project_name", help="The name of the Google Cloud project to analyze."
    )
    parser.add_argument(
        "--cost_threshold",
        type=float,
        default=0.0,
        help="Relative Cost threshold.",
    )
    parser.add_argument(
        "--soft_delete_window",
        type=float,
        default=604800.0,
        help="Time window (in seconds) for considering soft-deleted objects.",
    )
    parser.add_argument(
        "--agg_days",
        type=int,
        default=30,
        help=(
            "Time window (in days) for aggregating results over a time period,"
            " defaults to 30-day period"
        ),
    )
    parser.add_argument(
        "--lookback_days",
        type=int,
        default=360,
        help=(
            "Time window (in days) for considering the how old the bucket to be."
        ),
    )
    parser.add_argument(
        "--list",
        type=bool,
        default=False,
        help="Return the list of bucketnames seperated by space.",
    )

    args = parser.parse_args()

    response = soft_delete_relative_cost_analyzer(
        args.project_name,
        args.cost_threshold,
        args.soft_delete_window,
        args.agg_days,
        args.lookback_days,
        args.list,
    )
    if not args.list:
        print(
            "To remove soft-delete policy from the listed buckets run:\n"
            # Capture output
            "python storage_soft_delete_relative_cost_analyzer.py"
            " [your-project-name] --[OTHER_OPTIONS] --list > list_of_buckets.txt \n"
            "cat list_of_buckets.txt | gcloud storage buckets update -I "
            "--clear-soft-delete",
            response,
        )
        return
    print(response)


if __name__ == "__main__":
    soft_delete_relative_cost_analyzer_main()

A seguir

Saiba como usar objetos excluídos de maneira reversível.
Saiba como desativar a exclusão reversível.