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:
- A resposta que você recebe da solicitação.
- 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
e5xx
. - 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 |
|
Condicionalmente idempotente |
|
Nunca idempotente |
|
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
comconnection refused
: pode ocorrer devido a problemas temporários de rede.url.Error
comconnection 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 deerr.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
ouGeneration
- É seguro tentar novamente se uma condição prévia
GenerationMatch
foi aplicada à chamada ou seObjectHandle.Generation
foi definido.
- É seguro tentar novamente se uma condição prévia
MetagenerationMatch
- É seguro tentar novamente se uma condição prévia
MetagenerationMatch
foi aplicada à chamada.
- É seguro tentar novamente se uma condição prévia
Etag
- É seguro repetir se o método inserir uma
etag
no corpo da solicitação JSON. Usado apenas emHMACKeyHandle.Update
quandoHmacKeyMetadata.Etag
foi definido.
- É seguro repetir se o método inserir uma
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
ougeneration
- É seguro repetir se
ifGenerationMatch
ougeneration
tiver sido transmitido como uma opção para o método.
- É seguro repetir se
ifMetagenerationMatch
- É seguro tentar novamente se
ifMetagenerationMatch
for transmitido como uma opção.
- É seguro tentar novamente se
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
ougeneration
- É seguro repetir se
ifGenerationMatch
ougeneration
tiver sido transmitido como uma opção para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.
- É seguro repetir se
ifMetagenerationMatch
- É seguro tentar novamente se
ifMetagenerationMatch
for transmitido como uma opção.
- É seguro tentar novamente se
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
ouif_generation_match
tiver sido transmitido como um argumento para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.
- É seguro repetir se
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
- É seguro repetir se
if_metageneration_match
tiver sido transmitido como um argumento para o método.
- É seguro repetir se
DEFAULT_RETRY_IF_ETAG_IN_JSON
- É seguro repetir se o método inserir uma
etag
no corpo da solicitação JSON. ParaHMACKeyMetadata.update()
, isso significa que a etag precisa ser configurada no próprio objetoHMACKeyMetadata
. Para o métodoset_iam_policy()
em outras classes, isso significa que a etag precisa ser configurada no argumento "política" transmitido para o método.
- É seguro repetir se o método inserir uma
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
ougeneration
- É seguro tentar novamente se o parâmetro
generation
ouif_generation_match
for transmitido como um argumento para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.
- É seguro tentar novamente se o parâmetro
if_metageneration_match
- É possível tentar novamente se o parâmetro
if_metageneration_match
for transmitido como uma opção.
- É possível tentar novamente se o parâmetro
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 classesgoogle::cloud::storage::LimitedErrorCountRetryPolicy
egoogle::cloud::storage::LimitedTimeRetryPolicy
. É possível fornecer sua própria classe, que precisa implementar a interfacegoogle::cloud::RetryPolicy
.google::cloud::storage::BackoffPolicyOption
: a biblioteca fornece a classegoogle::cloud::storage::ExponentialBackoffPolicy
. É possível fornecer sua própria classe, que precisa implementar a interfacegoogle::cloud::storage::BackoffPolicy
.google::cloud::storage::IdempotencyPolicyOption
: a biblioteca fornece as classesgoogle::cloud::storage::StrictIdempotencyPolicy
egoogle::cloud::storage::AlwaysRetryIdempotencyPolicy
. Você pode fornecer sua própria classe, que precisa implementar a interfacegoogle::cloud::storage::IdempotencyPolicy
.
Para saber mais, consulte a documentação de referência da biblioteca de cliente C++.
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.
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:
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.
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.
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.
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
- Saiba mais sobre como solicitar condições prévias.