在 Cloud Storage 中使用長時間執行的作業

本頁說明如何使用從 Cloud Storage 方法呼叫啟動的長時間執行作業。如要詳細瞭解從特定方法呼叫傳回的長時間執行作業語意，請參閱功能專屬說明文件。

取得必要角色

如要取得管理 Cloud Storage 中長時間執行作業所需的權限，請要求管理員在用於執行基礎作業的值區或專案中，授予您「Storage 管理員」(roles/storage.admin) 角色或「Storage Legacy Bucket Owner」(roles/storage.legacyBucketOwner) 角色。

這些預先定義的角色包含下列權限，可管理 Cloud Storage 中的長時間執行作業：

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list

如要瞭解如何授予值區角色，請參閱「搭配值區使用 IAM」。如要瞭解如何授予專案角色，請參閱「管理存取權」。

取得長時間執行的作業詳細資料

指令列

如要取得長時間執行的作業詳細資料或查看狀態，請使用 gcloud storage operations describe 指令：

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

取代：

  • BUCKET_NAME，並將其替換為包含長時間執行作業的值區名稱。例如：my-bucket。

  • OPERATION_ID，並提供您呼叫方法時，在回應中傳回的長時間執行作業 ID。舉例來說，呼叫 gcloud storage restore 會傳回下列回應，而長時間執行的作業 ID 為 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

REST API

JSON API

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

  2. 使用 cURL 透過 operations.get 要求呼叫 JSON API：

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

    取代：

    • 將 BUCKET_NAME 替換為與長時間執行的作業相關聯的值區名稱。

    • OPERATION_ID，其中包含長時間執行作業的 ID，該 ID 會在您呼叫的方法回應中傳回。舉例來說，呼叫 gcloud storage restore 後，系統會傳回下列回應，而長時間執行的作業 ID 為 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

如果要求成功，系統會傳回 operations 資源：

{
  "kind": "storage#operation",
  "name": "projects/_/buckets/bucket/operations/operation_id",
  "metadata": {
    "@type": OperationMetadataType*,
    metadata OperationMetadata*
  },
  "done": boolean,
  "response": {
    "@type": ResponseResourceType*,
    response ResponseResource*
  }
}

列出值區中長時間執行的作業

指令列

如要列出 bucket 中長時間執行的作業，請使用 gcloud storage operations list 指令：

gcloud storage operations list gs://BUCKET_NAME

取代：

  • BUCKET_NAME，其中包含長時間執行的作業。例如：my-bucket。

REST API

JSON API

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

  2. 使用 cURL 透過 operations.get 要求呼叫 JSON API：

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

    取代：

    • BUCKET_NAME，並將其替換為與要列出的長時間執行作業相關聯的值區名稱。

如果要求成功，您會收到類似以下的回應：

{
  "kind": "storage#operations",
  "nextPageToken": string,
  "operations": [
    operations Resource
  ]
}

取消長時間執行的作業

指令列

如要取消長時間執行的作業，請使用 gcloud storage operations cancel 指令：

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

取代：

  • BUCKET_NAME，並將其替換為包含長時間執行作業的值區名稱。例如：my-bucket。

  • OPERATION_ID，並提供您呼叫方法時，在回應中傳回的長時間執行作業 ID。舉例來說，呼叫 gcloud storage restore 會傳回下列回應，而長時間執行的作業 ID 為 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

REST API

JSON API

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

  2. 使用 cURL 透過 operations.post 要求呼叫 JSON API：

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

    取代：

    • BUCKET_NAME，並將其替換為與要取消的長時間執行作業相關聯的值區名稱。

    • OPERATION_ID，其中包含長時間執行作業的 ID，該 ID 會在您呼叫的方法回應中傳回。舉例來說，呼叫 gcloud storage restore 後，系統會傳回下列回應，而長時間執行的作業 ID 為 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP：

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

中繼資料

長時間執行的作業會與中繼資料相關聯。下列中繼資料可識別長時間執行的作業屬性：

  • 建立時間：建立長時間執行作業的時間。

  • 結束時間：長時間執行的作業完成執行的時間。

  • 更新時間：上次修改長時間執行作業的時間。

  • 類型：叫用的長時間執行作業類型。

  • 要求取消：指出使用者是否要求取消長時間執行的作業。

  • 進度百分比：長時間執行作業的預估進度，以百分比表示。如果值為 -1，表示進度不明。

處理錯誤

長時間執行的作業是從非同步 API 啟動，且需要與同步 API 不同的錯誤處理做法。與同步 API 不同，非同步 API 呼叫的回應可能會指出作業成功，即使長時間執行的作業最終失敗也一樣。您應剖析回應主體中長時間執行的作業中繼資料，判斷 API 呼叫是否成功，而不是依據回應標頭中傳回的狀態碼。

舉例來說，如果您提出大量還原軟刪除項目的要求，即使作業期間發生錯誤，系統仍會傳回成功的 HTTP 狀態碼 (200 OK)。如要確認大量還原作業是否成功，請取得長時間執行作業的狀態。

請注意，長時間執行的作業 API (Get、List、Cancel) 是同步作業，會傳回一般錯誤。