이 페이지에서는 Cloud Storage 도구가 실패한 요청을 재시도하는 방법과 재시도 동작을 맞춤설정하는 방법을 설명합니다. 또한 재시도 요청에 대한 고려사항도 설명합니다.
개요
요청을 재시도해도 안전한지 여부를 결정하는 두 가지 요소는 다음과 같습니다.
- 요청에서 수신된 응답.
- 요청의 멱등성
응답
요청에서 수신된 응답에 요청을 재시도하는 것이 유용한지 여부가 표시됩니다. 일시적인 문제와 관련된 응답은 일반적으로 재시도 가능합니다. 반면에 영구적인 오류와 관련된 응답에는 승인 또는 구성 변경과 같이 항목을 변경한 후에야 요청을 다시 시도하는 것이 유용한 것으로 표시됩니다. 다음 응답은 재시도하는 것이 유용한 일시적인 문제를 보여줍니다.
- HTTP
408
,429
,5xx
응답 코드 - 소켓 시간 초과 및 TCP 연결 해제
자세한 내용은 JSON 및 XML 상태 및 오류 코드를 참조하세요.
멱등성
멱등성 요청은 반복적으로 수행될 수 있으며 항상 대상 리소스를 동일한 종료 상태로 유지합니다. 예를 들어 나열 요청은 리소스를 수정하지 않으므로 항상 나열 요청이 멱등성을 갖습니다. 반면 새로운 Pub/Sub 알림 만들기는 요청이 성공할 때마다 새 알림 ID를 만들기 때문에 멱등적이지 않습니다.
다음은 작업을 멱등적으로 만드는 조건의 예시입니다.
이 작업은 지속적으로 요청하더라도 대상 리소스에 동일하게 관찰 가능한 영향을 미칩니다.
이 작업은 한 번만 성공합니다.
작업은 대상 리소스 상태에 관찰 가능한 영향을 미치지 않습니다.
재시도할 수 있는 응답을 받으면 요청의 멱등성을 고려해야 합니다. 멱등성이 아닌 요청을 재시도하면 경합 상태 및 기타 충돌이 발생할 수 있기 때문입니다.
조건부 멱등성
요청의 하위 집합은 조건부 멱등성을 가집니다. 즉, 특정 선택적 인수를 포함하는 경우에만 멱등성을 가집니다. 조건부로 재시도해도 안전한 작업은 기본적으로 조건 케이스가 통과된 경우에만 재시도해야 합니다. Cloud Storage는 요청의 조건 케이스로 전제조건 및 ETag를 허용합니다.
작업의 멱등성
다음 표에는 각 멱등성 카테고리에 속하는 Cloud Storage 작업이 나와 있습니다.
멱등성 | 운영 |
---|---|
항상 멱등 |
|
조건부 멱등 |
|
멱등 불가 |
|
1이 필드는 JSON API에서 사용할 수 있습니다. 클라이언트 라이브러리에서 사용할 수 있는 필드는 관련 클라이언트 라이브러리 문서를 참조하세요.
Cloud Storage 도구로 재시도 전략을 구현하는 방법
콘솔
Google Cloud Console이 사용자를 대신하여 Cloud Storage에 요청을 보내고 필요한 백오프를 처리합니다.
명령줄
gcloud storage
명령어는 사용자가 추가로 조치를 취할 필요 없이 응답 섹션에 나열된 오류를 재시도합니다.
다음과 같은 다른 오류에 대해 조치를 취해야 할 수 있습니다.
사용자 인증 정보가 잘못되었거나 권한이 부족합니다.
프록시 구성에 문제가 있어 네트워크에 연결할 수 없습니다.
재시도 가능한 오류의 경우 gcloud CLI가 잘린 바이너리 지수 백오프 전략을 사용해서 요청을 재시도합니다. 최대 재시도 기본 횟수는 gcloud CLI의 경우 32회입니다.
클라이언트 라이브러리
C++
기본적으로 작업은 연결이 끊어지거나 성공적으로 설정되지 않았음을 나타내는 소켓 오류와 함께 다음 HTTP 오류 코드에 대한 재시도를 지원합니다.
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
C++ 라이브러리의 모든 지수 백오프 및 재시도 설정은 구성 가능합니다. 라이브러리에 구현된 알고리즘이 요구사항에 맞지 않는 경우 커스텀 코드를 제공하여 자체 전략을 구현할 수 있습니다.
설정 | 기본값 |
---|---|
자동으로 다시 시도 | True |
최대 요청 재시도 시간 | 15분 |
초기 대기(백오프) 시간 | 1초 |
반복당 대기 시간 배율 | 2 |
최대 대기 시간 | 5분 |
기본적으로 C++ 라이브러리는 멱등성이 없으며 반복적으로 성공하는 경우 여러 리소스를 삭제하거나 만들 수 있는 작업을 포함하여 재시도 가능한 오류가 있는 모든 작업을 다시 시도합니다. 멱등성 작업만 재시도하려면 google::cloud::storage::StrictIdempotencyPolicy
클래스를 사용합니다.
C#
C# 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.
Go
기본적으로 작업은 다음 오류에 대한 재시도를 지원합니다.
- 연결 오류:
io.ErrUnexpectedEOF
: 일시적인 네트워크 문제로 인해 발생할 수 있습니다.connection refused
가 포함된url.Error
: 일시적인 네트워크 문제로 인해 발생할 수 있습니다.connection reset by peer
가 포함된url.Error
: Google Cloud에서 연결이 재설정되었습니다.net.ErrClosed
: Google Cloud가 연결을 닫았음을 의미합니다.
- HTTP 코드:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Temporary()
인터페이스를 구현하고err.Temporary() == true
값을 제공하는 오류- Go 1.13 오류 래핑을 사용하여 래핑된 위 오류 중 하나
Go 라이브러리에서 모든 지수 백오프 설정을 구성할 수 있습니다. 기본적으로 Go를 통한 작업에는 지수 백오프에 대한 다음 설정이 사용됩니다. 기본값은 gax에서 가져옵니다.
설정 | 기본값(초) |
---|---|
자동으로 다시 시도 | 멱등성이면 True |
최대 시도 수 | 제한 없음 |
초기 재시도 지연 | 1초 |
재시도 지연 배수 | 2.0 |
최대 재시도 지연 | 30초 |
총 제한 시간(재개 가능한 업로드 청크) | 32초 |
총 제한 시간(다른 모든 작업) | 제한 없음 |
일반적으로 제어 컨텍스트가 취소되거나 클라이언트가 종료되거나 일시적이지 않은 오류가 수신되지 않으면 재시도는 무한 계속됩니다. 재시도를 중지하려면 컨텍스트 제한 시간이나 취소를 사용합니다. 이 동작에 대한 유일한 예외는 데이터 여러 요청을 필요로 할 만큼 충분히 큰 작성자를 사용하여 재개 가능한 업로드를 수행하는 경우입니다. 이 시나리오에서는 각 청크가 타임아웃되고 기본적으로 32초 후에 재시도를 중지합니다. Writer.ChunkRetryDeadline
을 변경하여 기본 제한 시간을 조정할 수 있습니다.
조건부 멱등성(조건부 재시도 안전)인 Go 작업의 하위 집합이 있습니다. 이러한 작업은 특정 조건이 충족되는 경우에만 재시도됩니다.
GenerationMatch
또는Generation
GenerationMatch
전제조건이 호출에 적용되었거나ObjectHandle.Generation
이 설정된 경우에는 재시도해도 안전합니다.
MetagenerationMatch
MetagenerationMatch
전제조건이 호출에 적용된 경우 재시도해도 안전합니다.
Etag
- 메서드가 JSON 요청 본문에
etag
를 삽입하면 재시도해도 안전합니다.HmacKeyMetadata.Etag
가 설정된 경우에만HMACKeyHandle.Update
에 사용됩니다.
- 메서드가 JSON 요청 본문에
RetryPolicy
는 기본적으로 RetryPolicy.RetryIdempotent
로 설정됩니다. 기본 재시도 동작을 수정하는 방법에 대한 예시는 재시도 맞춤설정을 참조하세요.
자바
기본적으로 작업은 다음 오류에 대한 재시도를 지원합니다.
- 연결 오류:
Connection reset by peer
: Google Cloud에서 연결을 재설정했음을 의미합니다.Unexpected connection closure
: Google Cloud에서 연결을 종료했다는 의미입니다.
- HTTP 코드:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
자바 라이브러리에서 모든 지수 백오프 설정을 구성할 수 있습니다. 기본적으로 자바를 통한 작업에는 지수 백오프에 대한 다음 설정이 사용됩니다.
설정 | 기본값(초) |
---|---|
자동으로 다시 시도 | 멱등성이면 True |
최대 시도 수 | 6 |
초기 재시도 지연 | 1초 |
재시도 지연 배수 | 2.0 |
최대 재시도 지연 | 32초 |
총 제한 시간 | 50초 |
초기 RPC 제한 시간 | 50초 |
RPC 제한 시간 배율 | 1.0 |
최대 RPC 제한 시간 | 50초 |
연결 시간 초과 | 20초 |
읽기 제한 시간 | 20초 |
설정에 대한 자세한 내용은 RetrySettings.Builder
및 HttpTransportOptions.Builder
에 대한 Java 참고 문서를 참조하세요.
조건부 멱등성에 해당하는 자바 작업의 하위 집합이 있습니다(조건부로 재시도에 안전). 이러한 작업은 특정 인수를 포함하는 경우에만 재시도됩니다.
ifGenerationMatch
또는generation
ifGenerationMatch
또는generation
가 메서드에 옵션으로 전달되면 재시도해도 안전합니다.
ifMetagenerationMatch
ifMetagenerationMatch
가 옵션으로 전달되면 재시도해도 안전합니다.
StorageOptions.setStorageRetryStrategy
는 기본적으로 StorageRetryStrategy#getDefaultStorageRetryStrategy
로 설정됩니다.
기본 재시도 동작을 수정하는 방법에 대한 예시는 재시도 맞춤설정을 참조하세요.
Node.js
기본적으로 작업은 다음 오류 코드에 대한 재시도를 지원합니다.
- 연결 오류:
EAI_again
: DNS 조회 오류입니다. 자세한 내용은getaddrinfo
문서를 참조하세요.Connection reset by peer
: Google Cloud에서 연결을 재설정했음을 의미합니다.Unexpected connection closure
: Google Cloud에서 연결을 종료했다는 의미입니다.
- HTTP 코드:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Node.js 라이브러리에서 모든 지수 백오프 설정을 구성할 수 있습니다. 기본적으로 Node.js를 통한 작업에는 지수 백오프에 대한 다음 설정이 사용됩니다.
설정 | 기본값(초) |
---|---|
자동으로 다시 시도 | 멱등성이면 True |
최대 재시도 횟수 | 3 |
초기 대기 시간 | 1초 |
반복당 대기 시간 배율 | 2 |
최대 대기 시간 | 64초 |
기본 기한 | 600초 |
조건부 멱등성(조건부 재시도 안전)인 Node.js 작업의 하위 집합이 있습니다. 이러한 작업은 특정 인수를 포함하는 경우에만 재시도됩니다.
ifGenerationMatch
또는generation
ifGenerationMatch
또는generation
가 메서드에 옵션으로 전달되면 재시도해도 안전합니다. 메서드가 이러한 두 매개변수 중 하나만 허용합니다.
ifMetagenerationMatch
ifMetagenerationMatch
가 옵션으로 전달되면 재시도해도 안전합니다.
retryOptions.idempotencyStrategy
는 기본적으로 IdempotencyStrategy.RetryConditional
로 설정됩니다. 기본 재시도 동작을 수정하는 방법에 대한 예시는 재시도 맞춤설정을 참조하세요.
PHP
PHP 클라이언트 라이브러리는 기본적으로 지수 백오프를 사용합니다.
Python
기본적으로 작업은 다음 오류 코드에 대한 재시도를 지원합니다.
- 연결 오류:
requests.exceptions.ConnectionError
requests.exceptions.ChunkedEncodingError
(업로드 및 다운로드와 같은 페이로드 데이터를 객체로 가져오거나 전송하는 작업에만 해당)ConnectionError
- HTTP 코드:
408 Request Timeout
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
Python을 통한 작업은 지수 백오프에 다음과 같은 기본 설정을 사용합니다.
설정 | 기본값(초) |
---|---|
자동으로 다시 시도 | 멱등성이면 True |
초기 대기 시간 | 1 |
반복당 대기 시간 배율 | 2 |
최대 대기 시간 | 60 |
기본 기한 | 120 |
특정 인수가 포함될 때 조건부 멱등성(조건부로 재시도 안전)인 Python 작업 하위 집합이 있습니다. 이러한 작업은 조건 사례가 통과한 경우에만 재시도합니다.
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
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를 메서드로 전달되는 'policy' 인수에서 설정해야 합니다.
- 메서드가 JSON 요청 본문에
Ruby
기본적으로 작업은 다음 오류 코드에 대한 재시도를 지원합니다.
- 연결 오류:
SocketError
HTTPClient::TimeoutError
Errno::ECONNREFUSED
HTTPClient::KeepAliveDisconnected
- HTTP 코드:
408 Request Timeout
429 Too Many Requests
5xx Server Error
Ruby 클라이언트 라이브러리에서 모든 지수 백오프 설정을 구성할 수 있습니다. 기본적으로 Ruby 클라이언트 라이브러리를 통한 작업은 지수 백오프에 다음과 같은 설정을 사용합니다.
설정 | 기본값 |
---|---|
자동으로 다시 시도 | True |
최대 재시도 수 | 3 |
초기 대기 시간 | 1초 |
반복당 대기 시간 배율 | 2 |
최대 대기 시간 | 60초 |
기본 기한 | 900초 |
다음과 같은 특정 인수가 포함될 때 조건부 멱등성(조건부로 재시도 안전)인 Ruby 작업 하위 집합이 있습니다.
if_generation_match
또는generation
generation
또는if_generation_match
매개변수가 메서드에 인수로 전달되면 재시도해도 안전합니다. 메서드가 이러한 두 매개변수 중 하나만 허용합니다.
if_metageneration_match
if_metageneration_match
매개변수가 옵션으로 전달되면 재시도해도 안전합니다.
기본적으로 멱등성 작업은 모두 재시도되며 조건부 멱등성 작업은 조건 케이스가 통과한 경우에만 재시도됩니다. 멱등성이 없는 작업은 재시도되지 않습니다. 기본 재시도 동작을 수정하는 방법에 대한 예시는 재시도 맞춤설정을 참조하세요.
REST API
JSON 또는 XML API를 직접 호출할 때는 지수 백오프 알고리즘을 사용하여 자체 재시도 전략을 구현해야 합니다.
재시도 맞춤설정
콘솔
Google Cloud 콘솔을 사용하여 재시도 동작을 맞춤설정할 수 없습니다.
명령줄
gcloud storage
명령어의 경우 이름이 지정된 구성을 만들고 다음 속성 중 일부 또는 전체를 설정하여 재시도 전략을 제어할 수 있습니다.
base_retry_delay
exponential_sleep_multiplier
max_retries
max_retry_delay
그런 다음 --configuration
project-wide 플래그를 사용하여 명령별로 정의된 구성을 적용하거나 gcloud config set
명령어를 사용하여 모든 gcloud 명령어에 대해 정의된 구성을 적용합니다.
클라이언트 라이브러리
C++
재시도 동작을 맞춤설정하려면 google::cloud::storage::Client
객체를 초기화할 때 다음 옵션에 대해 값을 제공합니다.
google::cloud::storage::RetryPolicyOption
: 이 라이브러리는google::cloud::storage::LimitedErrorCountRetryPolicy
및google::cloud::storage::LimitedTimeRetryPolicy
클래스를 제공합니다.google::cloud::RetryPolicy
인터페이스를 구현해야 하는 자체 클래스를 제공할 수 있습니다.google::cloud::storage::BackoffPolicyOption
: 이 라이브러리는google::cloud::storage::ExponentialBackoffPolicy
클래스를 제공합니다.google::cloud::storage::BackoffPolicy
인터페이스를 구현해야 하는 자체 클래스를 제공할 수 있습니다.google::cloud::storage::IdempotencyPolicyOption
: 이 라이브러리는google::cloud::storage::StrictIdempotencyPolicy
및google::cloud::storage::AlwaysRetryIdempotencyPolicy
클래스를 제공합니다.google::cloud::storage::IdempotencyPolicy
인터페이스를 구현해야 하는 자체 클래스를 제공할 수 있습니다.
자세한 내용은 C++ 클라이언트 라이브러리 참고 문서를 확인하세요.
C#
C# 클라이언트 라이브러리에서 사용하는 기본 재시도 전략은 맞춤설정할 수 없습니다.
Go
스토리지 클라이언트를 초기화하면 기본 재시도 구성이 설정됩니다. 재정의되지 않는 한 구성의 옵션은 기본값으로 설정됩니다. 사용자는 단일 라이브러리 호출에 대해(BucketHandle.Retryer 및 ObjectHandle.Retryer 사용) 또는 클라이언트에서 수행된 모든 호출에 대해(Client.SetRetry 사용) 기본값이 아닌 재시도 동작을 구성할 수 있습니다. 재시도 동작을 수정하려면 관련 RetryOptions를 다음 메서드 중 하나에 전달합니다.
재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.
자바
Storage
를 초기화하면 RetrySettings
의 인스턴스도 함께 초기화됩니다. 재정의되지 않는 한 RetrySettings
의 옵션은 기본값으로 설정됩니다. 기본 자동 재시도 동작을 수정하려면 Storage
인스턴스 생성을 위해 사용된 StorageOptions
에 커스텀 StorageRetryStrategy
를 전달합니다. 다른 스칼라 매개변수를 수정하려면 Storage
인스턴스 생성을 위해 사용된 StorageOptions
에 커스텀 RetrySettings
를 전달합니다.
재시도 동작을 맞춤설정하는 방법은 다음 예시를 참조하세요.
Node.js
Cloud Storage를 초기화하면 retryOptions 구성 파일도 함께 초기화됩니다. 재정의되지 않는 한 구성의 옵션은 기본값으로 설정됩니다. 기본 재시도 동작을 수정하려면 초기화할 때 커스텀 재시도 구성 retryOptions
를 스토리지 생성자로 전달합니다.
Node.js 클라이언트 라이브러리는 자동으로 백오프 전략을 사용하여 autoRetry
매개변수로 요청을 재시도할 수 있습니다.
재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.
PHP
PHP 클라이언트 라이브러리에서 사용하는 기본 재시도 전략은 맞춤설정할 수 없습니다.
Python
기본 재시도 동작을 수정하려면 with_XXX
메서드로 google.cloud.storage.retry.DEFAULT_RETRY
객체를 호출하여 이 객체의 복사본을 만듭니다. DEFAULT_RETRY
매개변수가 포함되어 있는 경우 Python 클라이언트 라이브러리는 자동으로 백오프 전략을 사용하여 요청을 재시도합니다.
with_predicate
는 업로드 및 다운로드와 같이 페이로드 데이터를 가져오거나 객체로 전송하는 작업에 지원되지 않습니다. 속성을 하나씩 수정하는 것이 좋습니다. 자세한 내용은 google-api-core 재시도 참조를 확인하세요.
나만의 조건부 재시도를 구성하려면 ConditionalRetryPolicy
객체를 만들고 커스텀 Retry
객체를 DEFAULT_RETRY_IF_GENERATION_SPECIFIED
, DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
, 또는 DEFAULT_RETRY_IF_ETAG_IN_JSON
로 래핑합니다.
재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.
Ruby
스토리지 클라이언트를 초기화하면 모든 재시도 구성이 위 표에 표시된 값으로 설정됩니다. 기본 재시도 동작을 수정하려면 스토리지 클라이언트를 초기화하는 동안 재시도 구성을 전달합니다.
특정 작업의 재시도 횟수를 재정의하려면 작업의 options
매개변수에 retries
를 전달하세요.
REST API
지수 백오프 알고리즘을 사용하여 자체 재시도 전략을 구현합니다.
지수 백오프 알고리즘
지수 백오프 알고리즘은 요청 간 대기 시간을 기하급수적으로 늘려 최대 백오프 시간까지 요청을 재시도합니다. 응답 및 멱등성 기준을 모두 충족하는 요청을 재시도하려면 일반적으로 지수 백오프를 지터와 함께 사용해야 합니다. 지수 백오프로 자동 재시도를 구현하는 권장사항은 연쇄 장애 해결을 참조하세요.
다음 단계
- 요청 전제조건 자세히 알아보기