使用虛刪除的物件

總覽設定

本頁說明如何列出、存取及還原已軟刪除的物件。

事前準備

如要取得列出、存取及還原已軟刪除物件所需的權限，請要求管理員在 bucket、受管理資料夾或專案中，授予您「Storage 管理員」(roles/storage.admin) IAM 角色。

這個預先定義的角色具備列出、存取及還原已軟刪除物件所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要列出、存取及還原虛刪除物件，必須具備下列權限：

storage.buckets.get (只有使用 Google Cloud 控制台執行本頁指示時，才需要這項權限)
storage.buckets.list (只有使用 Google Cloud 控制台執行本頁指示時，才需要這項權限)
storage.objects.get (只有使用 Google Cloud 控制台執行本頁指示時，才需要這項權限)
storage.objects.list
storage.objects.restore
storage.objects.create
storage.objects.delete (只有在還原物件時會覆寫現有物件時，才需要這項權限)
storage.buckets.restore (只有在大量還原虛刪除物件時，才需要這項權限)

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

如要管理從軟刪除方法啟動的長期執行的作業，您可能需要其他角色和權限。詳情請參閱「長時間執行的作業的必要角色」。

列出 bucket 中所有虛刪除的物件

如要列出值區中所有已軟刪除的物件，請按照下列操作說明執行：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要查看軟刪除物件的 bucket 名稱。系統會開啟「Bucket details」(值區詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
在「顯示」清單中，選取「僅限虛刪除的物件」。系統會顯示虛刪除的物件清單。

指令列

如要顯示值區中所有已軟刪除的物件清單，請使用 gcloud storage ls 指令，並搭配 --soft-deleted 旗標和 ** 萬用字元。請注意，您可能需要在萬用字元運算式前後加上引號。

  gcloud storage ls gs://BUCKET_NAME/** --soft-deleted

更改下列內容：

BUCKET_NAME：值區名稱。例如：my-bucket。

REST API

JSON API

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

使用 cURL 透過列出物件要求呼叫 JSON API，該要求會使用 ?softDeleted 查詢參數：

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/o?softDeleted=true"

其中 BUCKET_NAME 是相關值區的名稱。例如：my-bucket。

查看物件的所有虛刪除版本

如要查看 bucket 中特定物件的所有軟刪除版本，請按照下列操作說明執行：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要查看軟刪除版本物件的 bucket 名稱。系統會開啟「Bucket details」(值區詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
按一下要查看所有軟刪除版本的物件。系統隨即會顯示「物件詳細資料」頁面。
按一下「版本記錄」分頁標籤。
在「顯示」清單中，選取「僅限虛刪除的物件」。系統會顯示該物件的所有軟刪除版本。

指令列

如要顯示值區中物件的所有軟刪除版本清單，請使用 gcloud storage ls 指令：

  gcloud storage ls gs://BUCKET_NAME/OBJECT_NAME --soft-deleted

更改下列內容：

BUCKET_NAME：值區名稱。例如：my-bucket。
OBJECT_NAME：要查看所有版本的物件名稱。

REST API

JSON API

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

使用 cURL 透過列出物件要求呼叫 JSON API，該要求會使用 ?softDeleted 查詢參數：
```
curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?matchGlob=OBJECT_NAME&softDeleted=true"
```
更改下列內容：
- BUCKET_NAME：值區名稱。例如：my-bucket。
- OBJECT_NAME：要查看所有版本的物件名稱。

還原虛刪除的物件

您可以還原儲存空間中虛刪除物件的特定版本。請注意，您無法還原虛刪除 bucket 中的物件。如要還原虛刪除 bucket 中的物件，請先還原虛刪除 bucket。

如要還原虛刪除的物件，請按照下列操作說明操作：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要還原軟刪除物件的 bucket 名稱。系統會開啟「Bucket details」(值區詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
在「顯示」清單中，選取「僅限虛刪除的物件」。
前往該物件 (可能位於資料夾中)。
按一下虛刪除的物件。系統隨即會顯示「物件詳細資料」頁面。
在「顯示」清單中，選取「僅限虛刪除的物件」。系統會顯示該物件的所有軟刪除版本。
如要還原特定軟刪除的物件版本，請按一下該物件版本旁的「還原」。「還原物件版本」窗格隨即開啟。
按一下「確認」。

指令列

如要還原已軟刪除的物件版本，請使用 gcloud storage restore 指令：

  gcloud storage restore gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

更改下列內容：

BUCKET_NAME：值區名稱。例如：my-bucket。
OBJECT_NAME：要查看所有版本的物件名稱。
GENERATION_NUMBER：要還原的軟刪除物件產生編號。例如：1560468815691234。如未指定生成編號，系統會還原最新版本。

如需大量還原多個物件的其他選項，包括使用 all-versions 旗標還原物件的所有版本，請參閱 gcloud storage restore 參考資料。

REST API

JSON API

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

使用 cURL 透過 POST 物件要求呼叫 JSON API：
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/restore?generation=GENERATION_NUMBER"
```
其中：
- BUCKET_NAME 是相關值區的名稱。例如：my-bucket。
- OBJECT_NAME 是要還原的軟刪除物件名稱。例如：cat.jpeg。
- GENERATION_NUMBER 是要還原的虛刪除物件產生編號。例如：1560468815691234。

大量還原 bucket 中虛刪除的物件

如要還原大量物件，或不知道要還原哪些特定物件，請使用大量還原作業。請注意，大量還原作業會以非同步方式進行，有時可能需要一小時以上才會開始。

大量還原作業會啟動儲存空間的長時間執行作業。您可以使用 Google Cloud CLI 取得及列出長時間執行的作業，以便在大量還原作業進行期間查看詳細資料和狀態。

如要大量還原 bucket 中虛刪除的物件，請按照下列說明操作：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在值區清單中，找出包含要還原物件的值區。
按一下與值區相關聯的「值區溢位」選單 ()，然後選取「建立還原作業」。

「建立還原工作」窗格隨即開啟。
在「選擇要還原的虛刪除物件」部分，選取要還原物件的時間範圍。
選用：如要只還原符合 glob 模式的物件，請選取「依 glob 模式篩選」，然後輸入 glob 模式。
選用：在「還原選項」部分指定其他還原行為。
點選「建立」。

如要追蹤批次還原作業的進度，請按一下 Google Cloud 控制台標頭中的「通知」按鈕 ()。

指令列

如要使用大量還原作業還原值區中的所有物件，請使用 gcloud storage restore 指令。

舉例來說，下列指令會執行大量還原作業，非同步還原在特定時間範圍內刪除的所有值區物件：

  gcloud storage restore gs://BUCKET_NAME/** \
      --async --deleted-after-time=DELETED_AFTER_TIME \
      --deleted-before-time=DELETED_BEFORE_TIME

更改下列內容：

BUCKET_NAME：值區名稱。例如：my-bucket。
DELETED_AFTER_TIME：選用引數，用於指定要還原物件的日期。例如：2022-12-01。
DELETED_BEFORE_TIME：選用引數，可指定要還原物件的日期。例如：2022-12-21。

如要瞭解其他可用來篩選要大量還原物件的選項，請參閱 gcloud storage restore 參考資料。

如果成功，指令會傳回與大量還原作業相關聯的長時間執行作業 ID。您可以取得長時間執行的作業詳細資料，或取消長時間執行的作業，在大量還原作業完成前停止作業。詳情請參閱「使用長時間執行的作業」。

REST API

JSON API

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

使用 cURL 透過 POST 物件要求呼叫 JSON API：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/bulkRestore"

其中 BUCKET_NAME 是相關值區的名稱。例如：my-bucket。

使用長期執行的作業進行大量還原

物件的大量還原作業會啟動長時間執行的作業。您可以取得及列出長時間執行的作業，以便查看大量還原作業的詳細資料和狀態，或刪除長時間執行的作業，以便在大量還原作業進行期間取消作業。

如要瞭解如何使用從 Cloud Storage 作業 (例如大量還原作業) 啟動的長時間執行作業，請參閱「使用長時間執行的作業」。

以下範例顯示從大量還原作業傳回的長時間執行作業：

done: false
{
  "kind": "storage@operation",
  "name": "projects/_/buckets/my-bucket/operations/CiQyODRlMTY0My0wNGExLTQ3MWItOTE2Zi1hZmQ0ZmM4ZDc4MjQQAg",
  "metadata": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsMetadata",
    "commonMetadata": {
      "type": "bulk-restore-objects",
      "createTime": "2023-10-20T21:08:11.289Z",
      "updateTime": "2023-10-20T21:18:37.583Z",
      "endTime": "2023-10-20T21:18:37.583Z",
      "requestedCancellation": false,
      "progressPercent": -1,
    },
    "allow_overwrite": false,
    "matchGlobs": ["*"],
    "succeededCount": "0",
    "failedCount": "0",
    "skippedCount": "0",
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsResponse"
  }
}

後續步驟

進一步瞭解虛刪除。

使用虛刪除的物件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

所需權限

列出 bucket 中所有虛刪除的物件

控制台

指令列

REST API

JSON API

查看物件的所有虛刪除版本

控制台

指令列

REST API

JSON API

還原虛刪除的物件

控制台

指令列

REST API

JSON API

大量還原 bucket 中虛刪除的物件

控制台

指令列

REST API

JSON API

使用長期執行的作業進行大量還原

後續步驟

使用虛刪除的物件