재시도 전략

이 페이지에서는 Cloud Storage에 대한 실패한 요청의 잘린 지수 백오프와 같은 재시도 전략을 설명합니다.

개요

Cloud Storage에 실패한 요청을 재시도할지 여부를 결정하려면 요청 유형과 작업이 재시도해도 안전한지 여부를 결정하는 멱등성을 사용하는 것이 좋습니다. 일반적으로 다음과 같은 유형의 요청을 재시도하려면 잘린 지수 백오프를 사용해야 합니다.

  • 데이터 또는 메타데이터의 업로드 및 다운로드를 비롯하여, HTTP 5xx429 응답 코드를 반환하는 모든 Cloud Storage 대상 요청

  • HTTP 408 응답 코드를 반환하는 재개 가능한 업로드

  • 소켓 시간 초과 및 TCP 연결 해제

자세한 내용은 JSONXML의 상태 및 오류 코드를 참조하세요.

지수 백오프 알고리즘

잘린 지수 백오프는 요청 간 지연 증가와 함께 클라이언트가 주기적으로 실패한 요청을 재시도하는 네트워크 애플리케이션의 표준 오류 처리 전략입니다.

지수 백오프 알고리즘이 재시도 간 대기 시간을 최대 백오프 시간까지 늘려서 기하급수적으로 요청을 재시도합니다. 예를 들면 다음과 같습니다.

  1. Cloud Storage에 요청합니다.

  2. 요청이 실패하면 1초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.

  3. 요청이 실패하면 2초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.

  4. 요청이 실패하면 4초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.

  5. maximum_backoff 시간까지 이를 반복합니다.

  6. 최대 시간(deadline)까지 계속 대기하고 재시도합니다. 그러나 재시도 간 maximum_backoff 대기 시간을 늘리지 않습니다.

각 항목의 의미는 다음과 같습니다.

  • 대기 시간은 min((2^n, random_number_milliseconds), maximum_backoff)입니다. 여기서 n은 반복(요청)마다 1씩 증가합니다.

  • random_number_milliseconds는 1,000밀리초 이하의 임의 숫자입니다. 이렇게 하면 많은 클라이언트가 동기화되고 한 번에 모두 재시도하여 동기화된 웨이브에서 요청을 보내는 것을 방지할 수 있습니다. random_number_milliseconds 값은 각 재시도 요청 후 다시 계산합니다.

  • maximum_backoff는 일반적으로 32 또는 64초입니다. 적절한 값은 사용 사례에 따라 다릅니다.

maximum_backoff 시간에 도달한 후에는 계속 재시도할 수 있지만, 애플리케이션이 응답하지 않는 경우 일정 시간 안에 요청이 실패하도록 하는 것이 좋습니다. 예를 들어 클라이언트가 maximum_backoff 시간으로 64초를 사용하는 경우 이 값에 도달한 후 클라이언트는 64초마다 재시도할 수 있습니다. 그런 다음 클라이언트는 deadline 600초 후 재시도를 중지합니다.

클라이언트가 재시도 사이에 얼마나 오래 대기해야 하는지와 몇 번 재시도해야 하는지는 사용 사례와 네트워크 상태에 따라 다릅니다. 예를 들어 애플리케이션의 모바일 클라이언트는 동일한 애플리케이션의 데스크톱 클라이언트보다 더 자주, 더 긴 간격으로 재시도해야 할 수 있습니다.

maximum_backoff와 재시도할 수 있는 추가 시간이 지난 후 재시도 요청이 실패하면 지원 및 도움말에 나열된 방법 중 하나로 오류를 신고하거나 로깅합니다.

멱등성

Cloud Storage에 실패한 요청을 재시도하는 것이 안전한지 확인하려면 요청이 멱등성인지 여부를 확인합니다. 멱동성은 동일한 작업을 여러 번 적용하면 타겟 리소스의 상태에 동일한 영향을 미친다는 것을 의미합니다. 멱등성은 일반적으로 재시도해도 안전합니다.

다음은 멱등성을 충족하는 조건의 예시입니다.

  • 이 작업은 지속적으로 요청된 경우에도 대상 리소스에 동일한 관찰 가능한 효과가 적용됩니다.

  • 작업은 한 번만 성공합니다.

  • 작업은 대상 리소스 상태에 관찰 가능한 영향을 미치지 않습니다.

예를 들어 버킷 나열 요청은 요청이 여러 번 성공하더라도 동일한 효과가 나타납니다. 반면 새 Pub/Sub 알림을 만드는 작업은 요청이 성공할 때마다 새 알림 ID를 만들기 때문에 멱등적이지 않습니다.

조건부 멱등성

요청의 하위 집합은 조건부 등적이며, 이는 특정 선택적 인수가 포함된 경우에만 멱등성을 가집니다. 조건적으로 안전한 작업은 조건 케이스가 통과한 경우에만 기본적으로 재시도해야 합니다. Cloud Storage는 요청의 조건 사례로 전제조건 및 ETag를 허용합니다.

Cloud Storage 도구별 재시도 전략

아래의 탭을 클릭하여 각 Cloud Storage 도구의 재시도 전략 권장사항을 확인하세요.

Console

Cloud Console이 사용자 대신 Cloud Storage에 요청을 보내고 필요한 백오프를 처리합니다.

gsutil

gsutil의 재시도 전략을 보려면 재시도 처리 전략을 참조하세요.

클라이언트 라이브러리

C++

C++ 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

C#

C# 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

Go

Go 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

자바

자바 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

Node.js

Node.js는 자동으로 백오프 전략을 사용하여 autoRetry 매개변수로 요청을 재시도할 수 있습니다.

PHP

PHP 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

Python

재시도 전략의 경우 Python 클라이언트 라이브러리는 미디어 작업과 비미디어 작업을 구분합니다.

  • 미디어 작업에는 페이로드 데이터를 객체로 가져오거나 전송하는 모든 작업이 포함됩니다. 예를 들어 여기에는 '업로드' 또는 '다운로드'로 시작하는 Blob의 모든 메서드와 Client.download_blob_to_file이 포함됩니다.

  • 비미디어 작업은 객체 메타데이터만 처리하는 작업입니다.

기본적으로 미디어 및 비미디어 작업은 다음 오류 코드에 대한 재시도를 지원합니다.

  • 연결 오류:
    • requests.exceptions.ConnectionError
    • requests.exceptions.ChunkedEncodingError(미디어 API 호출만 해당)
  • HTTP 코드:
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
    • 508 Resource Limit Exceeded

Python을 통한 작업은 지수 백오프에 다음과 같은 기본 설정을 사용합니다.

기본 설정 미디어 호출 비미디어 호출
초기 대기 시간(초) 1 1
반복당 대기 시간 배율(초) 2 2
최대 대기 시간(초) 64 60
기본 기한(초) 600 120
지터가 구현됨 아니요

미디어 및 비미디어 작업의 하위 집합은 특정 선택적 인수를 포함하는 경우에만 멱등성을 가집니다. 조건부로 안전하게 복구 가능한 작업은 조건 case가 통과한 경우에만 기본적으로 재시도됩니다. 현재 이러한 조건에는 다음이 포함됩니다.

  • DEFAULT_RETRY_IF_GENERATION_SPECIFIED

    • if generation 또는 if_generation_match의 안전한 시도는 메서드에 인수로 전달되었습니다. 메서드가 이러한 두 매개변수 중 하나만 허용합니다.
  • DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED

    • if_metageneration_match가 메서드의 인수로 전달되면 안전하게 재시도할 수 있습니다.
  • DEFAULT_RETRY_IF_ETAG_IN_JSON

    • 메서드가 JSON 요청 본문에 etag을 삽입하면 안전하게 재시도할 수 있습니다. HMACKeyMetadata.update()의 경우 etag를 HMACKeyMetadata 객체 자체에서 설정해야 합니다. 다른 클래스의 set_iam_policy() 메서드의 경우 메서드에 전달되는 '정책' 인수에서 etag를 설정해야 합니다.

미디어 작업 재시도 정책

미디어 작업의 경우 업로드 메서드의 num_retries 인수를 구성하여 업로드 재시도 횟수를 지정할 수 있습니다. 기본적으로 if_metageneration_match 조건을 사용한 업로드만 멱등성을 보장합니다. num_retries 인수를 설정하면 기본 동작이 재정의되고 if_metageneration_match 조건 없이도 재시도가 보장됩니다.

비미디어 작업 재시도 정책

안전하게 실행되거나 안전한 비미디어 작업에서는 retry 매개변수가 메서드 서명에 추가됩니다. 이러한 매개변수의 기본값은 다음 중 하나입니다.

  • DEFAULT_RETRY
  • DEFAULT_RETRY_IF_GENERATION_SPECIFIED
  • DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
  • DEFAULT_RETRY_IF_ETAG_IN_JSON

기본 재시도 동작을 수정하려면 with_XXX 메서드를 호출하여 google.cloud.storage.retry.DEFAULT_RETRY 객체의 복사본을 만듭니다. 예를 들어 기본 기한을 30초로 수정하려면 retry=DEFAULT_RETRY.with_deadline(30)를 전달합니다. 속성을 하나씩 수정하는 것이 좋습니다. 자세한 내용은 google-api-core Retry 참조를 확인하세요.

나만의 조건부 재시도를 구성하려면 ConditionalRetryPolicy 객체를 만들고 커스텀 Retry 객체를 DEFAULT_RETRY_IF_GENERATION_SPECIFIED, DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED, 또는 DEFAULT_RETRY_IF_ETAG_IN_JSON로 래핑합니다.

다음은 맞춤설정된 조건부 재시도의 예입니다.

  • blob.reload()는 기본적으로 DEFAULT_RETRY를 사용합니다. 이 메서드를 재정의하여 함수가 전혀 재시도되지 않도록 하려면 blob.reload(retry=None)로 호출합니다.

  • bucket.update()는 기본적으로 DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED를 사용합니다. 메타 세대 번호가 지정되지 않아도 함수가 재시도되도록 이를 재정의하려면 다음과 같이 호출합니다.

    from google.cloud.storage.retry import DEFAULT_RETRY
    bucket.update(retry=DEFAULT_RETRY)
  • bucket.list_blobs()는 기본적으로 DEFAULT_RETRY를 사용합니다. 이를 재정의하여 API 호출이 기본값인 120초 대신 20초로 재시도되도록 하려면 다음과 같이 호출합니다.

    from google.cloud.storage.retry import DEFAULT_RETRY
    modified_retry = DEFAULT_RETRY.with_deadline(20)
    bucket.list_blobs(retry=modified_retry)

Ruby

Ruby 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.

REST API

JSON 또는 XML API를 직접 호출할 때는 지수 백오프 알고리즘을 사용하여 직접 재시도 전략을 구현해야 합니다.

작업의 멱등성

다음 표에는 각 범주에 해당하는 Cloud Storage 작업이 나와 있습니다.

멱등성 운영
항상 멱등
  • 모든 get 및 list 요청
  • 버킷 삽입 또는 삭제
  • 테스트 버킷 IAM 정책 및 권한
  • 보관 정책 잠그기
  • HMAC 키 또는 Pub/Sub 알림 삭제
조건부 멱등
  • IfMetagenerationMatch 또는 ETag를 HTTP 전제조건으로 하여 버킷에 대한 업데이트/패치 요청
  • IfMetagenerationMatch 또는 ETag를 HTTP 전제조건으로 포함하는 객체의 업데이트/패치 요청
  • ETag를 HTTP 전제조건 또는 리소스 본문으로 버킷 IAM 정책 설정
  • ETag를 HTTP 전제조건 또는 리소스 본문으로 사용하여 HMAC 키 업데이트
  • ifGenerationMatch을 사용하여 객체를 삽입, 복사, 구성, 재작성
  • ifGenerationMatch(또는 객체 버전의 세대 번호)로 객체 삭제
멱등 불가
  • HMAC 키 만들기
  • Pub/Sub 알림 만들기
  • 버킷 및 객체 ACL 또는 기본 객체 ACL에 대한 패치/업데이트 요청 생성, 삭제, 전송

다음 단계