Cloud Storage で長時間実行オペレーションを使用する

このページでは、Cloud Storage のメソッド呼び出しで開始する長時間実行オペレーションの使用方法について説明します。特定のメソッド呼び出しから返される長時間実行オペレーションのセマンティクスの詳細については、機能固有のドキュメントをご覧ください。

必要なロールを取得する

Cloud Storage で長時間実行オペレーションを管理するために必要な権限を取得するには、バケットまたは基盤となるオペレーションの実行に使用されるプロジェクトに対するストレージ管理者（roles/storage.admin）ロールまたはストレージのレガシーバケットオーナー（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。この ID は、呼び出したメソッドのレスポンスとして返されます。たとえば、gcloud storage restore の呼び出しから次のレスポンスが返された場合、長時間実行オペレーション ID は BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP です。
```
Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP
```

REST API

JSON API

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。

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

バケット内の長時間実行オペレーションを一覧表示する

コマンドライン

バケット内の長時間実行オペレーションを一覧表示するには、gcloud storage operations list コマンドを使用します。

gcloud storage operations list gs://BUCKET_NAME

次のように置き換えます。

BUCKET_NAME: 長時間実行オペレーションを含むバケットの名前。例: my-bucket

REST API

JSON API

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。

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。この ID は、呼び出したメソッドのレスポンスとして返されます。たとえば、gcloud storage restore の呼び出しから次のレスポンスが返された場合、長時間実行オペレーション ID は BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP です。
```
Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP
```

REST API

JSON API

gcloud CLI のインストールと初期化を行います。これにより、Authorization ヘッダーのアクセストークンを生成できます。

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 呼び出しに対するレスポンスは、長時間実行オペレーションが最終的に失敗した場合でも成功を示すことがあります。レスポンスヘッダーで返されるステータスコードに依存するのではなく、レスポンスの本文にある長時間実行オペレーションメタデータを解析して、API 呼び出しが成功したかどうかを判断する必要があります。

たとえば、削除（復元可能）の一括復元リクエストを行うと、オペレーション中にエラーが発生しても、成功した HTTP ステータスコード（200 OK）が返されます。一括復元オペレーションが成功したかどうかを確認するには、長時間実行オペレーションのステータスを取得します。

長時間実行オペレーション API（Get、List、Cancel）は同期であり、通常のエラーを返します。