Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

停用虛刪除功能

本頁面說明如何為組織中的新舊 bucket 停用虛刪除功能。

新值區預設會啟用虛刪除功能，以免資料遺失。如有需要，您可以修改虛刪除政策，為現有 bucket 停用虛刪除功能，也可以設定全機構預設標記，為新 bucket 預設停用虛刪除功能。請注意，停用虛刪除功能後，刪除的資料就無法復原，包括誤刪或惡意刪除的資料。

必要的角色

如要取得停用虛刪除功能所需的權限，請要求管理員在組織層級授予您下列 IAM 角色：

儲存空間管理員 (roles/storage.admin)
標記管理員 (roles/resourcemanager.tagAdmin)
機構檢視者 (roles/resourcemanager.organizationViewer)

這些預先定義的角色具備停用虛刪除功能所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

必須具備下列權限，才能停用虛刪除功能：

storage.buckets.get
storage.buckets.update
storage.buckets.list (只有在您打算使用 Google Cloud 控制台執行本頁的操作說明時，才需要這項權限)
如要瞭解標記管理員(roles/resourcemanager.tagAdmin) 角色包含哪些必要權限，請參閱「管理標記所需的權限」。

如要瞭解如何授予角色，請參閱「在 bucket 上設定及管理 IAM 政策」或「管理專案存取權」。

停用特定 bucket 的虛刪除功能

開始之前，請考量下列事項：

如果停用值區的虛刪除政策，且值區在停用期間含有虛刪除物件，則現有的虛刪除物件會保留至先前套用的保留期限到期為止。
停用 bucket 的虛刪除政策後，Cloud Storage 不會保留新刪除的物件。
由於中繼資料快取，在 bucket 上停用虛刪除政策後，Cloud Storage 不會立即反映這項變更。因此，停用軟刪除政策後，建議等待至少 30 秒，再啟動任何其他刪除作業，例如大量刪除。這樣可以確保資料永久刪除，而非虛刪除。如要進一步瞭解 Cloud Storage 作業的一致性，請參閱「Cloud Storage 一致性」。

如要為特定 bucket 停用軟刪除功能，請按照下列操作說明進行：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要停用軟刪除政策的 bucket 名稱。
按一下「保護」分頁標籤。
在「Soft delete policy」(虛刪除政策) 專區，按一下「Disable」(停用)，停用虛刪除政策。
按一下「確認」。

如要瞭解如何在 Google Cloud 控制台中取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

執行 gcloud storage buckets update 指令，並加上 --clear-soft-delete 旗標：

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

其中：

BUCKET_NAME 是 bucket 的名稱。例如：my-bucket。

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立包含下列資訊的 JSON 檔案：

{
  "softDeletePolicy": {
    "retentionDurationSeconds": "0"
  }
}

使用 cURL 來透過 PATCH 值區要求呼叫 JSON API：

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"

其中：

JSON_FILE_NAME 是您在步驟 2 建立的 JSON 檔案路徑。
BUCKET_NAME 是相關 bucket 的名稱。例如：my-bucket。

停用專案中 100 個最大 bucket 的虛刪除功能

使用 Google Cloud 控制台時，您最多可以一次停用 100 個 bucket 的虛刪除功能，並依虛刪除的位元組數或虛刪除的位元組數與現有位元組數的比例排序 bucket，方便您管理對虛刪除費用影響最大的 bucket。

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在「雲端儲存空間」頁面中，按一下「設定」。
按一下「虛刪除」分頁標籤。
從「Top buckets by deleted bytes」(依刪除位元組數排序的前幾名 bucket) 清單中，選取要停用虛刪除功能的 bucket。
按一下「停用虛刪除功能」。

您選取的 bucket 已停用虛刪除功能。

停用專案中多個或所有 bucket 的虛刪除功能

使用 Google Cloud CLI 執行 gcloud storage buckets update 指令，並加上 --project 旗標和萬用字元 *，即可大量停用專案中多個或所有 bucket 的虛刪除功能：

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

其中：

PROJECT_ID 是專案 ID。例如：my-project。

停用資料夾中所有 bucket 的虛刪除功能

使用 Google Cloud CLI 執行 gcloud projects list 和 gcloud storage buckets update 指令，停用指定資料夾中所有專案 bucket 的虛刪除功能。

執行 gcloud projects list 和 gcloud storage buckets update 指令，列出指定資料夾下的所有 bucket，然後停用資料夾中所有 bucket 的軟刪除功能：

gcloud projects list --filter="parent.id: FOLDER_ID" --format="value(projectId)" | while read project
do
  gcloud storage buckets update --project=$project --clear-soft-delete gs://*
done

其中：

FOLDER_ID 是資料夾名稱。例如：123456。

在組織層級停用虛刪除功能

使用 Google Cloud CLI 執行 gcloud storage buckets update 指令，並加上 --clear-soft-delete 旗標和萬用字元 *，在組織層級停用虛刪除功能：

執行 gcloud storage buckets update 指令，並搭配 --clear-soft-delete 旗標和 * 萬用字元，停用組織內所有 bucket 的虛刪除功能：

gcloud projects list --format="value(projectId)" | while read project
do
  gcloud storage buckets update --project=$project --clear-soft-delete gs://*
done

Cloud Storage 會停用現有 bucket 的虛刪除功能。已虛刪除的物件會保留在 bucket 中，直到虛刪除保留期限屆滿，才會永久刪除。

停用新值區的虛刪除功能

雖然新值區預設會啟用虛刪除功能，但您可以使用標記，防止系統預設啟用虛刪除功能。標記會使用 storage.defaultSoftDeletePolicy 鍵，在組織層級套用 0d (零天) 虛刪除政策，停用這項功能，並防止日後保留已刪除的資料。

請按照下列操作說明，在建立新 bucket 時預設停用虛刪除功能。請注意，下列操作說明與設定強制執行特定虛刪除政策的組織政策不同，也就是說，您仍可視需要指定政策，在特定 bucket 啟用虛刪除功能。

使用 Google Cloud CLI 建立 storage.defaultSoftDeletePolicy 標記，用於變更新 bucket 的預設軟刪除保留時間。請注意，只有 storage.defaultSoftDeletePolicy 標記名稱會更新預設虛刪除保留時間長度。

使用 gcloud resource-manager tags keys create 指令建立標記鍵：
```
gcloud resource-manager tags keys create storage.defaultSoftDeletePolicy \
 --parent=organizations/ORGANIZATION_ID \
 --description="Configures the default softDeletePolicy for new Storage buckets."
```
其中：
- ORGANIZATION_ID 是要設定預設虛刪除保留時間的機構數字 ID。例如，12345678901。如要瞭解如何找出組織 ID，請參閱「取得組織資源 ID」。
使用 gcloud resource-manager tags values create 指令，為 0d (零天) 建立標記值，根據預設停用新 bucket 的虛刪除保留期限：
```
gcloud resource-manager tags values create 0d \
  --parent=ORGANIZATION_ID/storage.defaultSoftDeletePolicy \
  --description="Disables soft delete for new Storage buckets."
```
其中：
- ORGANIZATION_ID 是要設定預設虛刪除保留時間長度的組織數字 ID。例如：12345678901。
注意： 如果先前已建立 storage.defaultSoftDeletePolicy 標記，這項指令會失敗。如要為 0d 建立標記值並停用虛刪除功能，您必須更新現有的 storage.defaultSoftDeletePolicy 標記，改用 0d 標記值。如要進一步瞭解如何更新標記，請參閱「更新現有標記」。
使用 gcloud resource-manager tags bindings create 指令將標記附加至資源：
```
gcloud resource-manager tags bindings create \
 --tag-value=ORGANIZATION_ID/storage.defaultSoftDeletePolicy/0d \
 --parent=RESOURCE_ID
```
其中：
- ORGANIZATION_ID 是建立代碼的機構的數字 ID。例如：12345678901。
- RESOURCE_ID 是要建立標記繫結的組織全名。舉例來說，如要將標記附加至 organizations/7890123456，請輸入 //cloudresourcemanager.googleapis.com/organizations/7890123456。

為超過指定費用門檻的 bucket 停用虛刪除功能

您可以使用 Python 適用的 Cloud 用戶端程式庫，透過 Python 用戶端程式庫範例，針對超過指定相對成本門檻的 bucket 停用軟刪除功能。範例會執行下列作業：

計算各儲存空間級別的相對儲存費用。
評估 bucket 累積的虛刪除費用。
設定虛刪除功能的使用費用門檻，並列出超過門檻的 bucket，讓您為超過門檻的 bucket 停用虛刪除功能。

如要進一步瞭解如何設定 Python 用戶端程式庫及使用範例，請參閱 Cloud Storage 虛刪除費用分析工具 README.md 頁面。

以下範例會針對超過指定費用門檻的 bucket 停用虛刪除功能：

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

後續步驟

重新啟用軟刪除功能前，請先詳閱注意事項。
瞭解虛刪除功能如何與其他 Cloud Storage 功能互動。