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입니다. 예를 들어 gcloud storage restore를 호출하면 다음과 같은 응답이 반환되고 장기 실행 작업 ID는 BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP입니다.

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

REST API

JSON API

  1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

    또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고 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입니다. 예를 들어 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

  1. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

    또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고 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. Authorization 헤더에 대한 액세스 토큰을 생성하려면 gcloud CLI가 설치 및 초기화되어 있어야 합니다.

    또는 OAuth 2.0 Playground를 사용하여 액세스 토큰을 만들고 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입니다. 예를 들어 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)는 동기식이며 일반적인 오류를 반환합니다.