재시도 전략

이 페이지에서는 Cloud Storage 도구가 실패한 요청을 재시도하는 방법과 재시도 동작을 맞춤설정하는 방법을 설명합니다. 또한 재시도 요청에 대한 고려사항도 설명합니다.

개요

요청을 재시도해도 안전한지 여부를 결정하는 두 가지 요소는 다음과 같습니다.

요청에서 수신된 응답.
요청의 멱등성

응답

요청에서 수신된 응답에 요청을 재시도하는 것이 유용한지 여부가 표시됩니다. 일시적인 문제와 관련된 응답은 일반적으로 재시도 가능합니다. 반면에 영구적인 오류와 관련된 응답에는 승인 또는 구성 변경과 같이 항목을 변경한 후에야 요청을 다시 시도하는 것이 유용한 것으로 표시됩니다. 다음 응답은 재시도하는 것이 유용한 일시적인 문제를 보여줍니다.

HTTP 408, 429, 5xx 응답 코드
소켓 시간 초과 및 TCP 연결 해제

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

멱등성

멱등성 요청은 반복적으로 수행될 수 있으며 항상 대상 리소스를 동일한 종료 상태로 유지합니다. 예를 들어 나열 요청은 리소스를 수정하지 않으므로 항상 나열 요청이 멱등성을 갖습니다. 반면 새로운 Pub/Sub 알림 만들기는 요청이 성공할 때마다 새 알림 ID를 만들기 때문에 멱등적이지 않습니다.

다음은 작업을 멱등적으로 만드는 조건의 예시입니다.

이 작업은 지속적으로 요청하더라도 대상 리소스에 동일하게 관찰 가능한 영향을 미칩니다.
이 작업은 한 번만 성공합니다.
작업은 대상 리소스 상태에 관찰 가능한 영향을 미치지 않습니다.

재시도할 수 있는 응답을 받으면 요청의 멱등성을 고려해야 합니다. 멱등성이 아닌 요청을 재시도하면 경합 상태 및 기타 충돌이 발생할 수 있기 때문입니다.

조건부 멱등성

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

작업의 멱등성

다음 표에는 각 멱등성 카테고리에 속하는 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에 대한 패치/업데이트 요청 만들기, 삭제, 전송

¹이 필드는 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에 사용됩니다.

RetryPolicy는 기본적으로 RetryPolicy.RetryIdempotent로 설정됩니다. 기본 재시도 동작을 수정하는 방법에 대한 예시는 재시도 맞춤설정을 참조하세요.

Java

기본적으로 작업은 다음 오류에 대한 재시도를 지원합니다.

연결 오류:
- 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' 인수에서 설정해야 합니다.

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++ 클라이언트 라이브러리 참고 문서를 확인하세요.

namespace gcs = ::google::cloud::storage;
// Create the client configuration:
auto options = google::cloud::Options{};
// Retries only idempotent operations.
options.set<gcs::IdempotencyPolicyOption>(
    gcs::StrictIdempotencyPolicy().clone());
// On error, it backs off for a random delay between [1, 3] seconds, then [3,
// 9] seconds, then [9, 27] seconds, etc. The backoff time never grows larger
// than 1 minute.
options.set<gcs::BackoffPolicyOption>(
    gcs::ExponentialBackoffPolicy(
        /*initial_delay=*/std::chrono::seconds(1),
        /*maximum_delay=*/std::chrono::minutes(1),
        /*scaling=*/3.0)
        .clone());
// Retries all operations for up to 5 minutes, including any backoff time.
options.set<gcs::RetryPolicyOption>(
    gcs::LimitedTimeRetryPolicy(std::chrono::minutes(5)).clone());
return gcs::Client(std::move(options));

C#

C# 클라이언트 라이브러리에서 사용하는 기본 재시도 전략은 맞춤설정할 수 없습니다.

Go

스토리지 클라이언트를 초기화하면 기본 재시도 구성이 설정됩니다. 재정의되지 않는 한 구성의 옵션은 기본값으로 설정됩니다. 사용자는 단일 라이브러리 호출에 대해(BucketHandle.Retryer 및 ObjectHandle.Retryer 사용) 또는 클라이언트에서 수행된 모든 호출에 대해(Client.SetRetry 사용) 기본값이 아닌 재시도 동작을 구성할 수 있습니다. 재시도 동작을 수정하려면 관련 RetryOptions를 다음 메서드 중 하나에 전달합니다.

재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
	"github.com/googleapis/gax-go/v2"
)

// configureRetries configures a custom retry strategy for a single API call.
func configureRetries(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Configure retries for all operations using this ObjectHandle. Retries may
	// also be configured on the BucketHandle or Client types.
	o := client.Bucket(bucket).Object(object).Retryer(
		// Use WithBackoff to control the timing of the exponential backoff.
		storage.WithBackoff(gax.Backoff{
			// Set the initial retry delay to a maximum of 2 seconds. The length of
			// pauses between retries is subject to random jitter.
			Initial: 2 * time.Second,
			// Set the maximum retry delay to 60 seconds.
			Max: 60 * time.Second,
			// Set the backoff multiplier to 3.0.
			Multiplier: 3,
		}),
		// Use WithPolicy to customize retry so that all requests are retried even
		// if they are non-idempotent.
		storage.WithPolicy(storage.RetryAlways),
	)

	// Use context timeouts to set an overall deadline on the call, including all
	// potential retries.
	ctx, cancel := context.WithTimeout(ctx, 500*time.Second)
	defer cancel()

	// Delete an object using the specified retry policy.
	if err := o.Delete(ctx); err != nil {
		return fmt.Errorf("Object(%q).Delete: %w", object, err)
	}
	fmt.Fprintf(w, "Blob %v deleted with a customized retry strategy.\n", object)
	return nil
}

Java

Storage를 초기화하면 RetrySettings의 인스턴스도 함께 초기화됩니다. 재정의되지 않는 한 RetrySettings의 옵션은 기본값으로 설정됩니다. 기본 자동 재시도 동작을 수정하려면 Storage 인스턴스 생성을 위해 사용된 StorageOptions에 커스텀 StorageRetryStrategy를 전달합니다. 다른 스칼라 매개변수를 수정하려면 Storage 인스턴스 생성을 위해 사용된 StorageOptions에 커스텀 RetrySettings를 전달합니다.

재시도 동작을 맞춤설정하는 방법은 다음 예시를 참조하세요.


import com.google.api.gax.retrying.RetrySettings;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.cloud.storage.StorageRetryStrategy;
import org.threeten.bp.Duration;

public final class ConfigureRetries {
  public static void main(String[] args) {
    String bucketName = "my-bucket";
    String blobName = "blob/to/delete";
    deleteBlob(bucketName, blobName);
  }

  static void deleteBlob(String bucketName, String blobName) {
    // Customize retry behavior
    RetrySettings retrySettings =
        StorageOptions.getDefaultRetrySettings()
            .toBuilder()
            // Set the max number of attempts to 10 (initial attempt plus 9 retries)
            .setMaxAttempts(10)
            // Set the backoff multiplier to 3.0
            .setRetryDelayMultiplier(3.0)
            // Set the max duration of all attempts to 5 minutes
            .setTotalTimeout(Duration.ofMinutes(5))
            .build();

    StorageOptions alwaysRetryStorageOptions =
        StorageOptions.newBuilder()
            // Customize retry so all requests are retried even if they are non-idempotent.
            .setStorageRetryStrategy(StorageRetryStrategy.getUniformStorageRetryStrategy())
            // provide the previously configured retrySettings
            .setRetrySettings(retrySettings)
            .build();

    // Instantiate a client
    Storage storage = alwaysRetryStorageOptions.getService();

    // Delete the blob
    BlobId blobId = BlobId.of(bucketName, blobName);
    boolean success = storage.delete(blobId);

    System.out.printf(
        "Deletion of Blob %s completed %s.%n", blobId, success ? "successfully" : "unsuccessfully");
  }
}

Node.js

Cloud Storage를 초기화하면 retryOptions 구성 파일도 함께 초기화됩니다. 재정의되지 않는 한 구성의 옵션은 기본값으로 설정됩니다. 기본 재시도 동작을 수정하려면 초기화할 때 커스텀 재시도 구성 retryOptions를 스토리지 생성자로 전달합니다. Node.js 클라이언트 라이브러리는 자동으로 백오프 전략을 사용하여 autoRetry 매개변수로 요청을 재시도할 수 있습니다.

재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of your GCS file
// const fileName = 'your-file-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  retryOptions: {
    // If this is false, requests will not retry and the parameters
    // below will not affect retry behavior.
    autoRetry: true,
    // The multiplier by which to increase the delay time between the
    // completion of failed requests, and the initiation of the subsequent
    // retrying request.
    retryDelayMultiplier: 3,
    // The total time between an initial request getting sent and its timeout.
    // After timeout, an error will be returned regardless of any retry attempts
    // made during this time period.
    totalTimeout: 500,
    // The maximum delay time between requests. When this value is reached,
    // retryDelayMultiplier will no longer be used to increase delay time.
    maxRetryDelay: 60,
    // The maximum number of automatic retries attempted before returning
    // the error.
    maxRetries: 5,
    // Will respect other retry settings and attempt to always retry
    // conditionally idempotent operations, regardless of precondition
    idempotencyStrategy: IdempotencyStrategy.RetryAlways,
  },
});
console.log(
  'Functions are customized to be retried according to the following parameters:'
);
console.log(`Auto Retry: ${storage.retryOptions.autoRetry}`);
console.log(
  `Retry delay multiplier: ${storage.retryOptions.retryDelayMultiplier}`
);
console.log(`Total timeout: ${storage.retryOptions.totalTimeout}`);
console.log(`Maximum retry delay: ${storage.retryOptions.maxRetryDelay}`);
console.log(`Maximum retries: ${storage.retryOptions.maxRetries}`);
console.log(
  `Idempotency strategy: ${storage.retryOptions.idempotencyStrategy}`
);

async function deleteFileWithCustomizedRetrySetting() {
  await storage.bucket(bucketName).file(fileName).delete();
  console.log(`File ${fileName} deleted with a customized retry strategy.`);
}

deleteFileWithCustomizedRetrySetting();

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로 래핑합니다.

재시도 동작을 맞춤설정하는 방법은 다음 코드 샘플을 참조하세요.

from google.cloud import storage
from google.cloud.storage.retry import DEFAULT_RETRY


def configure_retries(bucket_name, blob_name):
    """Configures retries with customizations."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"
    # The ID of your GCS object
    # blob_name = "your-object-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    # Customize retry with a deadline of 500 seconds (default=120 seconds).
    modified_retry = DEFAULT_RETRY.with_deadline(500.0)
    # Customize retry with an initial wait time of 1.5 (default=1.0).
    # Customize retry with a wait time multiplier per iteration of 1.2 (default=2.0).
    # Customize retry with a maximum wait time of 45.0 (default=60.0).
    modified_retry = modified_retry.with_delay(initial=1.5, multiplier=1.2, maximum=45.0)

    # blob.delete() uses DEFAULT_RETRY_IF_GENERATION_SPECIFIED by default.
    # Override with modified_retry so the function retries even if the generation
    # number is not specified.
    print(
        f"The following library method is customized to be retried according to the following configurations: {modified_retry}"
    )

    blob.delete(retry=modified_retry)
    print(f"Blob {blob_name} deleted with a customized retry strategy.")

Ruby

스토리지 클라이언트를 초기화하면 모든 재시도 구성이 위 표에 표시된 값으로 설정됩니다. 기본 재시도 동작을 수정하려면 스토리지 클라이언트를 초기화하는 동안 재시도 구성을 전달합니다.

특정 작업의 재시도 횟수를 재정의하려면 작업의 options 매개변수에 retries를 전달하세요.

def configure_retries bucket_name: nil, file_name: nil
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  require "google/cloud/storage"

  # Creates a client
  storage = Google::Cloud::Storage.new(

    # The maximum number of automatic retries attempted before returning
    # the error.
    #
    # Customize retry configuration with the maximum retry attempt of 5.
    retries: 5,

    # The total time in seconds that requests are allowed to keep being retried.
    # After max_elapsed_time, an error will be returned regardless of any
    # retry attempts made during this time period.
    #
    # Customize retry configuration with maximum elapsed time of 500 seconds.
    max_elapsed_time: 500,

    # The initial interval between the completion of failed requests, and the
    # initiation of the subsequent retrying request.
    #
    # Customize retry configuration with an initial interval of 1.5 seconds.
    base_interval: 1.5,

    # The maximum interval between requests. When this value is reached,
    # multiplier will no longer be used to increase the interval.
    #
    # Customize retry configuration with maximum interval of 45.0 seconds.
    max_interval: 45,

    # The multiplier by which to increase the interval between the completion
    # of failed requests, and the initiation of the subsequent retrying request.
    #
    # Customize retry configuration with an interval multiplier per iteration of 1.2.
    multiplier: 1.2
  )

  # Uses the retry configuration set during the client initialization above with 5 retries
  file = storage.service.get_file bucket_name, file_name

  # Maximum retry attempt can be overridden for each operation using options parameter.
  storage.service.delete_file bucket_name, file_name, options: { retries: 4 }
  puts "File #{file.name} deleted with a customized retry strategy."
end

REST API

지수 백오프 알고리즘을 사용하여 자체 재시도 전략을 구현합니다.

지수 백오프 알고리즘

지수 백오프 알고리즘은 요청 간 대기 시간을 기하급수적으로 늘려 최대 백오프 시간까지 요청을 재시도합니다. 응답 및 멱등성 기준을 모두 충족하는 요청을 재시도하려면 일반적으로 지수 백오프를 지터와 함께 사용해야 합니다. 지수 백오프로 자동 재시도를 구현하는 권장사항은 연쇄 장애 해결을 참조하세요.

다음 단계

자바 또는 Python을 사용하여 Storage Transfer Service에서 요청을 재시도하는 방법 알아보기
요청 전제조건 자세히 알아보기