再試行の方法

このページでは、失敗したリクエストを Cloud Storage ツールが再試行する方法と、再試行の動作をカスタマイズする方法について説明します。また、リクエストを再試行する際の考慮事項についても説明します。

概要

リクエストの再試行が安全かどうかは、次の 2 つの要素で決まります。

  1. リクエストからの受信レスポンス。
  2. リクエストのべき等性。

レスポンス

リクエストから返されたレスポンスは、リクエストの再試行に役立つかどうかを示します。通常、一時的な問題に関連するレスポンスは再試行できます。一方、永続的なエラーに関連するレスポンスは、リクエストを再試行する前に、承認や構成の変更などを行う必要があることを示します。次のレスポンスは、再試行する価値がある一時的な問題を示しています。

  • 408、429、5xx の HTTP レスポンス コード。
  • ソケット タイムアウトと TCP 切断。

詳細については、JSON と XML のステータス コードとエラーコードをご覧ください。

べき等性

リクエストがべき等であることは、リクエストを繰り返し実行しても、対象となるリソースが常に同じ終了状態になることを意味します。たとえば、一覧表示のリクエストは、リソースを変更しないので、常にべき等です。一方、新しい Pub/Sub 通知の作成はべき等ではありません。リクエストが成功するたびに新しい通知 ID が生成されるためです。

以下に、オペレーションをべき等にする条件の例を示します。

  • オペレーションを連続してリクエストしても、対象リソースに対して結果が生成される。

  • オペレーションが 1 回だけ成功する。

  • 対象リソースの状態に対して観察可能な結果がない。

再試行可能なレスポンスを受け取った場合は、リクエストのべき等性を考慮する必要があります。これは、べき等でないリクエストを再試行すると、競合状態などの競合が発生する可能性があるためです。

条件付きべき等性

リクエストのサブセットは条件付きべき等性になります。つまり、特定のオプション引数が含まれる場合にのみ、べき等になります。条件付きで安全に再試行できるオペレーションは、条件のケースに該当した場合にのみデフォルトで再試行されます。Cloud Storage は、リクエストの条件ケースとして前提条件と ETag を受け入れます。

オペレーションのべき等性

次の表に、べき等性の各カテゴリに属する Cloud Storage オペレーションの一覧を示します。

べき等性 オペレーション
常にべき等
  • すべての取得リクエストと一覧表示リクエスト
  • バケットを挿入または削除する
  • バケットの IAM ポリシーと権限のテスト
  • 保持ポリシーをロックする
  • HMAC キーまたは Pub/Sub 通知を削除する
条件付きべき等性
  • HTTP 前提条件として IfMetagenerationMatch1 または etag1 を使用するバケットの更新 / パッチ リクエスト
  • HTTP 前提条件が IfMetagenerationMatch1 または etag1 であるオブジェクトの更新 / パッチ リクエスト
  • HTTP 前提条件またはリソース本文で etag1 を使用してバケットの IAM ポリシーを設定する
  • HTTP 前提条件またはリソースの本文で etag1 を使用して HMAC キーを更新する
  • ifGenerationMatch1 を使用してオブジェクトを挿入、コピー、作成、書き換える
  • ifGenerationMatch1（またはオブジェクト バージョンの世代番号）を持つオブジェクトを削除する
べき等でない
  • HMAC キーを作成する
  • Pub/Sub 通知を作成する
  • バケットとオブジェクトの ACL、またはデフォルト オブジェクト ACL のパッチ / 更新リクエストを作成、削除、または送信する

1 このフィールドは JSON API で使用できます。クライアント ライブラリで使用できるフィールドについては、関連するクライアント ライブラリのドキュメントをご覧ください。

Cloud Storage ツールの再試行方法の実装方法

コンソール

Google Cloud コンソールが 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

    • メソッドが etag を JSON リクエスト本文に挿入する場合は、安全に再試行できます。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

Java ライブラリでは、すべての指数バックオフ設定が構成可能です。デフォルトでは、Java によるオペレーションでは指数バックオフ用に次の設定が使用されます。

設定 デフォルト値（秒）
自動再試行 べき等の場合は true
最大試行回数 6
最初の再試行までの経過時間 1 秒
再試行遅延乗数 2.0
再試行の最大遅延 32 秒
合計タイムアウト 50 秒
初期 RPC タイムアウト 50 秒
RPC タイムアウト乗数 1.0
最大 RPC タイムアウト 50 秒
接続タイムアウト 20 秒
読み取りタイムアウト 20 秒

設定の詳細については、Java リファレンス ドキュメントの 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

    • メソッドが etag を JSON リクエスト本文に挿入する場合は、安全に再試行できます。HMACKeyMetadata.update() の場合は、HMACKeyMetadata オブジェクト自体に etag を設定する必要があります。他のクラスの set_iam_policy() メソッドの場合は、メソッドに渡される「policy」引数に etag を設定する必要があります。

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 を使用するか、すべての gcloud コマンドに gcloud config set コマンドを使用して構成を適用します。

クライアント ライブラリ

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 は、ペイロード データの取得やオブジェクトに送信するオペレーション（アップロードやダウンロードなど）ではサポートされていません。属性は 1 つずつ変更することをおすすめします。詳細については、google-api-core Retry リファレンスをご覧ください。

独自の条件付き再試行を構成するには、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

指数バックオフ アルゴリズムを使用して、独自の再試行方法を実装します。

指数バックオフ アルゴリズム

指数バックオフのアルゴリズムは、リクエスト間の待ち時間の間隔を最大バックオフ時間まで増加させながら、指数関数的にリクエストを再試行します。通常は、ジッターと指数バックオフを使用して、レスポンスとべき等性の両方の条件を満たすリクエストを再試行する必要があります。指数バックオフを使用して自動再試行を実装するベスト プラクティスについては、カスケード障害への対応をご覧ください。

次のステップ