Repetir estratégia

Nesta página, descrevemos como as ferramentas do Cloud Storage repetem solicitações com falha e como personalizar o comportamento de novas tentativas. Também descrevemos considerações ao repetir solicitações.

Informações gerais

Há dois fatores que determinam se uma solicitação é segura para repetição:

  1. A resposta que você recebe da solicitação.
  2. A idempotência da solicitação.

Resposta

A resposta recebida da solicitação indica se é útil repetir a solicitação. Geralmente, as respostas relacionadas a problemas temporários podem ser repetidas. Por outro lado, a resposta relacionada a erros permanentes indica que você precisa fazer alterações, como alterações de autorização ou de configuração, antes de ser útil repetir a solicitação. As seguintes respostas indicam problemas temporários que são úteis para novas tentativas:

  • Códigos de resposta HTTP 408, 429 e 5xx.
  • Tempos limite de soquete e desconexões TCP.

Para mais informações, consulte os códigos de status e erro do JSON e XML.

Idempotência

Uma solicitação que é idempotente significa que ela pode ser executada repetidamente e sempre deixa o recurso de destino no mesmo estado final. Por exemplo, as solicitações de listagem são sempre idempotentes, porque elas não modificam os recursos. Por outro lado, a criação de uma nova notificação do Pub/Sub nunca é idempotente, porque cria um novo ID de notificação sempre que a solicitação é bem-sucedida.

Veja a seguir exemplos de condições que tornam uma operação idempotente

  • A operação tem o mesmo efeito observável no recurso de destino, mesmo quando solicitada continuamente.

  • A operação só funciona uma vez.

  • A operação não tem efeito observável no estado do recurso de destino.

Ao receber uma resposta que permite uma nova tentativa, considere a idempotência da solicitação, porque novas solicitações que não são idempotentes podem levar a disputas e outros conflitos.

Idempotência condicional

Um subconjunto de solicitações é idempotente condicionalmente, o que significa que elas só serão idempotentes se incluírem argumentos opcionais específicos. As operações que são condicionalmente seguras para nova tentativa só precisam ser repetidas por padrão se o caso de condição for transmitido. O Cloud Storage aceita condições prévias e ETags como casos de condição para solicitações.

Idempotência das operações

A tabela a seguir lista as operações do Cloud Storage que se enquadram em cada categoria de idempotência.

Idempotência Operações
Sempre idempotente
  • Todas as solicitações de recebimento e listagem
  • Inserir ou excluir buckets
  • Testar políticas e permissões de IAM do bucket
  • Bloquear políticas de retenção
  • Excluir uma chave HMAC ou notificação do Pub/Sub
Condicionalmente idempotente
  • Solicitações de atualização/patch para buckets com IfMetagenerationMatch1 ou etag1 como pré-condição HTTP
  • Solicitações de atualização/patch para objetos com IfMetagenerationMatch1 ou etag1 como pré-condição HTTP.
  • Definir uma política de IAM do bucket com a ETag etag1 como condição prévia HTTP ou no corpo do recurso
  • Atualizar uma chave HMAC com ETag etag1 como condição prévia HTTP ou no corpo do recurso
  • Inserir, copiar, compor ou regravar objetos com ifGenerationMatch1
  • Excluir um objeto com ifGenerationMatch1 (ou com um número de geração para versões de objeto)
Nunca idempotente
  • Criar uma chave HMAC
  • Criar uma notificação do Pub/Sub
  • Criar, excluir ou enviar solicitações de patch/atualização para ACLs de bucket e de objeto ou ACLs de objeto padrão

1 Esse campo está disponível para uso na API JSON. Para os campos disponíveis para uso nas bibliotecas de cliente, consulte a documentação relevante da biblioteca de cliente.

Como as ferramentas do Cloud Storage implementam estratégias de repetição

Console

O console do Google Cloud envia solicitações ao Cloud Storage em seu nome e processa qualquer espera necessária.

Linha de comando

Os comandos gcloud storage repetem os erros listados na seção Resposta sem exigir que você realize outras ações. Pode ser necessário tomar medidas em relação a outros erros, como:

  • Credenciais inválidas ou permissões insuficientes.

  • Rede inacessível devido a um problema de configuração de proxy.

Para erros que aceitam novas tentativas, a CLI gcloud repete solicitações usando uma estratégia de espera exponencial binária truncada. O número máximo de novas tentativas é 32 para a CLI gcloud.

Bibliotecas de cliente

C++

Por padrão, as operações são compatíveis com novas tentativas para os seguintes códigos de erro HTTP, bem como quaisquer erros de soquete que indiquem que a conexão foi perdida ou nunca foi estabelecida.

  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Todas as configurações de espera exponencial e nova tentativa na biblioteca C++ são configuráveis. Se os algoritmos implementados na biblioteca não forem compatíveis com suas necessidades, é possível fornecer um código personalizado para implementar suas próprias estratégias.

Configuração Valor padrão
Repetir automaticamente Verdadeiro
Tempo máximo para repetição de uma solicitação 15 minutos
Tempo de espera inicial (retirada) 1 segundo
Multiplicador do tempo de espera por iteração 2
Tempo máximo de espera 5 minutos

Por padrão, a biblioteca C++ repete todas as operações com erros que podem ser repetidos, mesmo aquelas que nunca são idempotentes e podem excluir ou criar vários recursos quando bem-sucedidas. Para repetir apenas as operações idempotentes, use a classe google::cloud::storage::StrictIdempotencyPolicy.

C#

Por padrão, a biblioteca de cliente do C# usa espera exponencial.

Go

Por padrão, as operações são compatíveis com novas tentativas para os seguintes erros:

  • Erros de conexão:
    • io.ErrUnexpectedEOF: pode ocorrer devido a problemas temporários de rede.
    • url.Error com connection refused: pode ocorrer devido a problemas temporários de rede.
    • url.Error com connection reset by peer: significa que o Google Cloud redefiniu a conexão.
    • net.ErrClosed: significa que o Google Cloud encerrou a conexão.
  • Códigos HTTP:
    • 408 Request Timeout
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Erros que implementam a interface Temporary() e agregam o valor de err.Temporary() == true
  • Qualquer um dos erros acima que foram encapsulados usando o encapsulamento de erros do Go 1.13

Todas as configurações de espera exponencial na biblioteca Go são configuráveis. Por padrão, as operações em Go usam as seguintes configurações para espera exponencial (os padrões são obtidos do gax):

Configuração Valor padrão (em segundos)
Repetir automaticamente Verdadeiro se for idempotente
Número máximo de tentativas Sem limite
Atraso inicial para tentar novamente: 1 segundo
Multiplicador de atraso nas tentativas 2,0
Atraso máximo para a nova tentativa 30 segundos
Tempo limite total (bloco de upload retomável) 32 segundos
Tempo limite total (todas as outras operações) Sem limite

Em geral, a nova tentativa continuará indefinidamente, a menos que o contexto de controle seja cancelado, o cliente seja fechado ou um erro não transitório seja recebido. Para interromper novas tentativas, use tempos limite ou cancelamento de contexto. A única exceção a esse comportamento é ao executar uploads retomáveis usando Gravador, em que os dados são grandes o suficiente para exigir várias solicitações. Nesse cenário, cada bloco expira e para de tentar novamente após 32 segundos por padrão. É possível ajustar o tempo limite padrão alterando Writer.ChunkRetryDeadline.

Há um subconjunto de operações Go condicionalmente idempotente (condicionalmente seguro para nova tentativa). Estas operações só tentarão novamente se atenderem a condições específicas:

  • GenerationMatch ou Generation

    • É seguro tentar novamente se uma condição prévia GenerationMatch foi aplicada à chamada ou se ObjectHandle.Generation foi definido.

  • MetagenerationMatch

    • É seguro tentar novamente se uma condição prévia MetagenerationMatch foi aplicada à chamada.

  • Etag

    • É seguro repetir se o método inserir uma etag no corpo da solicitação JSON. Usado apenas em HMACKeyHandle.Update quando HmacKeyMetadata.Etag foi definido.

RetryPolicy é definido como RetryPolicy.RetryIdempotent por padrão. Consulte Personalizar novas tentativas para ver exemplos de como modificar o comportamento padrão de novas tentativas.

Java

Por padrão, as operações são compatíveis com novas tentativas para os seguintes erros:

  • Erros de conexão:
    • Connection reset by peer: significa que o Google Cloud redefiniu a conexão.
    • Unexpected connection closure: significa que o Google Cloud encerrou a conexão.
  • Códigos HTTP:
    • 408 Request Timeout
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

Todas as configurações de espera exponencial na biblioteca Java são configuráveis. Por padrão, as operações por Java usam as configurações a seguir para espera exponencial:

Configuração Valor padrão (em segundos)
Repetir automaticamente Verdadeiro se for idempotente
Número máximo de tentativas 6
Atraso inicial para tentar novamente: 1 segundo
Multiplicador de atraso nas tentativas 2,0
Atraso máximo para a nova tentativa 32 segundos
Tempo limite total 50 segundos
Tempo limite inicial da RPC 50 segundos
Multiplicador de tempo limite de RPC 1.0
Tempo limite máximo da RPC 50 segundos
Tempo limite da conexão atingido 20 segundos
Tempo limite de leitura 20 segundos

Para mais informações sobre as configurações, consulte a documentação de referência do Java para RetrySettings.Builder e HttpTransportOptions.Builder.

Há um subconjunto de operações Java condicionalmente idempotente (condicionalmente seguro para nova tentativa). Essas operações só tentarão novamente se incluírem argumentos específicos:

  • ifGenerationMatch ou generation

    • É seguro repetir se ifGenerationMatch ou generation tiver sido transmitido como uma opção para o método.

  • ifMetagenerationMatch

    • É seguro tentar novamente se ifMetagenerationMatch for transmitido como uma opção.

StorageOptions.setStorageRetryStrategy é definido como StorageRetryStrategy#getDefaultStorageRetryStrategy por padrão. Consulte Personalizar novas tentativas para exemplos de como modificar o comportamento de nova tentativa padrão.

Node.js

Por padrão, as operações aceitam novas tentativas para os seguintes códigos de erro:

  • Erros de conexão:
    • EAI_again: este é um erro de busca DNS. Para mais informações, consulte a documentaçãogetaddrinfo.
    • Connection reset by peer: significa que o Google Cloud redefiniu a conexão.
    • Unexpected connection closure: significa que o Google Cloud encerrou a conexão.
  • Códigos HTTP:
    • 408 Request Timeout
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

Todas as configurações de espera exponencial na biblioteca Node.js são configuráveis. Por padrão, as operações por meio do Node.js usam as seguintes configurações para espera exponencial:

Configuração Valor padrão (em segundos)
Repetir automaticamente Verdadeiro se for idempotente
Número máximo de novas tentativas 3
Tempo de espera inicial 1 segundo
Multiplicador do tempo de espera por iteração 2
Tempo máximo de espera 64 segundos
Prazo padrão 600 segundos

Há um subconjunto de operações Node.js que é condicionalmente idempotente (condicionalmente seguro para tentar novamente). Essas operações só vão tentar novamente se incluírem argumentos específicos:

  • ifGenerationMatch ou generation

    • É seguro repetir se ifGenerationMatch ou generation tiver sido transmitido como uma opção para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.

  • ifMetagenerationMatch

    • É seguro tentar novamente se ifMetagenerationMatch for transmitido como uma opção.

retryOptions.idempotencyStrategy é definido como IdempotencyStrategy.RetryConditional por padrão. Consulte Personalizar novas tentativas para ver exemplos de como modificar o comportamento padrão de novas tentativas.

PHP

Por padrão, a biblioteca de cliente do PHP usa espera exponencial.

Python

Por padrão, as operações aceitam novas tentativas para os seguintes códigos de erro:

  • Erros de conexão:
    • requests.exceptions.ConnectionError
    • requests.exceptions.ChunkedEncodingError (somente para operações que buscam ou enviam dados de payload para objetos, como uploads e downloads)
    • ConnectionError
  • Códigos HTTP:
    • 408 Request Timeout
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout

As operações pelo Python usam as seguintes configurações padrão de espera exponencial:

Configuração Valor padrão (em segundos)
Repetir automaticamente Verdadeiro se for idempotente
Tempo de espera inicial 1
Multiplicador do tempo de espera por iteração 2
Tempo máximo de espera 60
Prazo padrão 120

Há um subconjunto de operações Python condicionalmente idempotente (condicionalmente seguro para nova tentativa) quando inclui argumentos específicos. Essas operações só tentarão novamente se um caso de condição for aprovado:

  • DEFAULT_RETRY_IF_GENERATION_SPECIFIED

    • É seguro repetir se generation ou if_generation_match tiver sido transmitido como um argumento para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.

  • DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED

    • É seguro repetir se if_metageneration_match tiver sido transmitido como um argumento para o método.

  • DEFAULT_RETRY_IF_ETAG_IN_JSON

    • É seguro repetir se o método inserir uma etag no corpo da solicitação JSON. Para HMACKeyMetadata.update(), isso significa que a etag precisa ser configurada no próprio objeto HMACKeyMetadata. Para o método set_iam_policy() em outras classes, isso significa que a etag precisa ser configurada no argumento "política" transmitido para o método.

Ruby

Por padrão, as operações aceitam novas tentativas para os seguintes códigos de erro:

  • Erros de conexão:
    • SocketError
    • HTTPClient::TimeoutError
    • Errno::ECONNREFUSED
    • HTTPClient::KeepAliveDisconnected
  • Códigos HTTP:
    • 408 Request Timeout
    • 429 Too Many Requests
    • 5xx Server Error

Todas as definições de espera exponencial da biblioteca de cliente do Ruby são configuráveis. Por padrão, as operações por meio da biblioteca de cliente do Ruby usam as seguintes configurações de espera exponencial:

Configuração Valor padrão
Repetir automaticamente Verdadeiro
Número máximo de novas tentativas 3
Tempo de espera inicial 1 segundo
Multiplicador do tempo de espera por iteração 2
Tempo máximo de espera 60 segundos
Prazo padrão 900 segundos

Há um subconjunto de operações Ruby condicionalmente idempotente (condicionalmente seguro para nova tentativa) quando inclui argumentos específicos:

  • if_generation_match ou generation

    • É seguro tentar novamente se o parâmetro generation ou if_generation_match for transmitido como um argumento para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.

  • if_metageneration_match

    • É possível tentar novamente se o parâmetro if_metageneration_match for transmitido como uma opção.

Por padrão, todas as operações idempotentes são repetidas. Além disso, as operações condicionalmente idempotentes são repetidas somente se o caso de condição for aprovado. Operações não idempotentes não são repetidas. Consulte Personalizar novas tentativas para ver exemplos de como modificar o comportamento padrão.

APIs REST

Ao chamar a API JSON ou XML diretamente, use o algoritmo de espera exponencial para implementar sua própria estratégia de repetição.

Como personalizar novas tentativas

Console

Não é possível personalizar o comportamento de repetição com o console do Google Cloud.

Linha de comando

Para comandos gcloud storage, é possível controlar a estratégia de repetição criando uma configuração nomeada e definindo algumas ou todas as seguintes propriedades:

  • base_retry_delay
  • exponential_sleep_multiplier
  • max_retries
  • max_retry_delay

Em seguida, aplique a configuração definida por comando usando a --configuration sinalização em todo o projeto ou para todos os comandos gcloud usando o comando gcloud config set

Bibliotecas de cliente

C++

Para personalizar o comportamento de repetição, forneça valores para as seguintes opções ao inicializar o objeto google::cloud::storage::Client:

  • google::cloud::storage::RetryPolicyOption: a biblioteca fornece classes google::cloud::storage::LimitedErrorCountRetryPolicy e google::cloud::storage::LimitedTimeRetryPolicy. É possível fornecer sua própria classe, que precisa implementar a interface google::cloud::RetryPolicy.

  • google::cloud::storage::BackoffPolicyOption: a biblioteca fornece a classe google::cloud::storage::ExponentialBackoffPolicy. É possível fornecer sua própria classe, que precisa implementar a interface google::cloud::storage::BackoffPolicy.

  • google::cloud::storage::IdempotencyPolicyOption: a biblioteca fornece as classes google::cloud::storage::StrictIdempotencyPolicy e google::cloud::storage::AlwaysRetryIdempotencyPolicy. Você pode fornecer sua própria classe, que precisa implementar a interface google::cloud::storage::IdempotencyPolicy.

Para saber mais, consulte a documentação de referência da biblioteca de cliente 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#

Não é possível personalizar a estratégia de repetição padrão usada pela biblioteca de cliente C#.

Go

Quando você inicializa um cliente de armazenamento, uma configuração de repetição padrão é definida. A menos que sejam substituídas, as opções na configuração são definidas com os valores padrão. Os usuários podem configurar um comportamento de repetição não padrão para uma única chamada de biblioteca (usando BucketHandle.Retryer e ObjectHandle.Retryer) ou para todas as chamadas feitas por um cliente (usando Client.SetRetry). Para modificar o comportamento da nova tentativa, transmita o RetryOptions relevante para um destes métodos.

Veja o exemplo de código a seguir para saber como personalizar seu comportamento de nova tentativa.

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

Ao inicializar Storage, uma instância de RetrySettings também será inicializada. A menos que sejam substituídas, as opções em RetrySettings são definidas com os valores padrão. Para modificar o comportamento de repetição automática padrão, transmita o StorageRetryStrategy personalizado para o StorageOptions usado para criar a instância Storage. Para modificar qualquer um dos outros parâmetros escalares, transmita um RetrySettings personalizado para o StorageOptions usado para construir a instância Storage.

Veja o exemplo a seguir para saber como personalizar o comportamento de repetição:


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

Quando você inicializa o Cloud Storage, um arquivo de configuração tryOptions também é inicializado. A menos que sejam substituídas, as opções na configuração são definidas com os valores padrão. Para modificar o comportamento de repetição padrão, transmita a configuração de repetição personalizada retryOptions para o construtor de armazenamento na inicialização. A biblioteca de cliente Node.js pode usar automaticamente as estratégias de espera para repetir solicitações com o parâmetro autoRetry.

Veja o exemplo de código a seguir para saber como personalizar seu comportamento de nova tentativa.

/**
 * 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

Não é possível personalizar a estratégia de repetição padrão usada pela biblioteca de cliente PHP.

Python

Para modificar o comportamento padrão de repetição, crie uma cópia do objeto google.cloud.storage.retry.DEFAULT_RETRY chamando-o com um método with_XXX. A biblioteca de cliente do Python usa automaticamente as estratégias de espera para repetir solicitações se você incluir o parâmetro DEFAULT_RETRY.

with_predicate não é compatível com operações que buscam ou enviam dados de payload para objetos, como uploads e downloads. É recomendável modificar os atributos um por um. Para mais informações, consulte a referência Nova tentativa google-api-core.

Para configurar sua própria repetição condicional, crie um objeto ConditionalRetryPolicy e una o objeto personalizado Retry com DEFAULT_RETRY_IF_GENERATION_SPECIFIED, DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED ou DEFAULT_RETRY_IF_ETAG_IN_JSON.

Veja o exemplo de código a seguir para saber como personalizar seu comportamento de nova tentativa.

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

Quando você inicializa o cliente de armazenamento, todas as configurações de repetição são definidas com os valores mostrados na tabela acima. Para modificar o comportamento de nova tentativa padrão, transmita as configurações de repetição ao inicializar o cliente de armazenamento.

Para substituir o número de novas tentativas de uma operação específica, transmita retries no parâmetro options da operação.

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

APIs REST

Use o algoritmo de espera exponencial para implementar sua própria estratégia de repetição.

Algoritmo de espera exponencial

Um algoritmo de espera exponencial repete solicitações usando tempos de espera exponencialmente crescentes entre as solicitações, até um tempo máximo de espera. Em geral, é necessário usar a espera exponencial com instabilidade para repetir solicitações que atendam aos critérios de resposta e idempotência. Para ver as práticas recomendadas para implementar tentativas automáticas com espera exponencial, consulte Como resolver falhas em cascata.

A seguir