Nesta página, descrevemos estratégias de repetição, como a espera exponencial truncada para solicitações com falha para o Cloud Storage.
Visão geral
Para decidir se quer repetir uma solicitação com falha para o Cloud Storage, considere o tipo da solicitação e sua idempotência, que determina se a operação é segura para uma repetição. Geralmente, você usa a espera exponencial truncada para repetir os seguintes tipos de solicitações:
Todas as solicitações ao Cloud Storage que retornam códigos de resposta HTTP
5xx
e429
, incluindo uploads e downloads de dados ou metadados.Uploads retomáveis que retornam códigos de resposta HTTP
408
.Tempos limite de soquete e desconexões TCP.
Para mais informações, consulte os códigos de status e erro do JSON e XML.
Algoritmo de espera exponencial
A espera exponencial truncada é uma estratégia padrão de resolução de erros para aplicativos de rede em que um cliente repete periodicamente uma solicitação com falha, aumentando o atraso entre as solicitações.
Um algoritmo de retirada exponencial repete solicitações exponencialmente, aumentando o tempo de espera entre novas tentativas até um tempo máximo de retirada. Veja o exemplo a seguir:
Faça uma solicitação ao Cloud Storage.
Se a solicitação falhar, aguarde 1 +
random_number_milliseconds
segundos e repita a solicitação.Se a solicitação falhar, aguarde 2 +
random_number_milliseconds
segundos e repita a solicitação.Se a solicitação falhar, aguarde 4 +
random_number_milliseconds
segundos e repita a solicitação.E assim por diante, até um tempo
maximum_backoff
.Continue aguardando e repetindo até uma quantidade máxima de tempo (
deadline
), mas não aumente o período de espera demaximum_backoff
entre as repetições.
onde:
O tempo de espera é min(((2n)+
random_number_milliseconds
),maximum_backoff
), comn
incrementado em 1 para cada iteração (solicitação).random_number_milliseconds
é um número aleatório de milissegundos menor ou igual a 1.000. Isso ajuda a evitar casos em que muitos clientes são sincronizados e ficam repetindo ao mesmo tempo, enviando solicitações em ondas sincronizadas. O valor derandom_number_milliseconds
é recalculado após cada nova tentativa de solicitação.maximum_backoff
costuma ser 32 ou 64 segundos. O valor adequado depende do caso de uso.
É possível continuar repetindo depois de atingir o tempo maximum_backoff
, mas
recomendamos que sua solicitação falhe após um período de tempo para evitar que o
aplicativo deixe de responder. Por exemplo, se um cliente usar um
tempo maximum_backoff
de 64 segundos, depois de atingir esse valor, o cliente
poderá repetir a cada 64 segundos. Depois, o cliente para de repetir novamente após um deadline
de
600 segundos.
O caso de uso e as condições da rede determinam quanto tempo os clientes precisam aguardar entre novas tentativas e quantas vezes eles podem tentar novamente. Por exemplo, clientes móveis de um aplicativo podem precisar fazer mais novas tentativas e por intervalos maiores quando comparados a clientes desktop do mesmo aplicativo.
Caso as solicitações de nova tentativa falhem após exceder o maximum_backoff
e qualquer tempo extra permitido para novas tentativas, faça um relatório ou registre o erro usando um dos métodos listados em Suporte e ajuda.
Idempotência
Para determinar se é seguro repetir uma solicitação com falha para o Cloud Storage, considere se ela éidempotente, o que significa que aplicar a mesma operação várias vezes tem o mesmo efeito no estado do recurso de destino. As operações de idempotência geralmente são seguras para repetição.
Veja a seguir exemplos de condições que satisfazem a idempotência:
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.
Por exemplo, uma solicitação para listar buckets tem o mesmo efeito mesmo que a solicitação seja enviada várias vezes. Por outro lado, uma operação como criar uma nova notificação do Pub/Sub não é idempotente, porque ela cria um novo ID de notificação sempre que a solicitação é enviada.
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 repetição 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.
Repetir estratégia por ferramenta do Cloud Storage
Clique nas guias abaixo para ver as recomendações de estratégia de repetição para cada ferramenta do Cloud Storage.
Console
O Console do Cloud envia solicitações ao Cloud Storage em seu nome e processa qualquer espera necessária.
gsutil
Para ver a estratégia de repetição do gsutil, consulte Repetir a estratégia de manipulação.
Bibliotecas de cliente
C++
Por padrão, a biblioteca de cliente do C++ usa espera exponencial.
C#
Por padrão, a biblioteca de cliente do C# usa espera exponencial.
Go
Por padrão, a biblioteca de cliente do Go usa a espera exponencial.
Java
Por padrão, a biblioteca de cliente do Java usa a espera exponencial.
Node.js
O Node.js pode usar estratégias de espera automaticamente para repetir solicitações
com o parâmetro autoRetry
.
PHP
Por padrão, a biblioteca de cliente do PHP usa espera exponencial.
Python
Para repetir a estratégia, a biblioteca de cliente do Python distingue entre operações de mídia e de não mídia:
As operações de mídia incluem todas as ações que buscam ou enviam dados de payload para objetos. Por exemplo, isso inclui todos os métodos de um
Blob
começando com as palavras "upload" ou "download", bem comoClient.download_blob_to_file
.Operações que não são de mídia são ações que processam apenas metadados de objetos.
Por padrão, as operações de mídia e não mídia são compatíveis com repetições dos seguintes códigos de erro:
- Erros de conexão:
requests.exceptions.ConnectionError
requests.exceptions.ChunkedEncodingError
(somente chamadas de API de mídia)
- Códigos HTTP:
429 Too Many Requests
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
508 Resource Limit Exceeded
As operações pelo Python usam as seguintes configurações padrão de espera exponencial:
Configuração padrão | Chamadas de mídia | Chamadas que não são de mídia |
---|---|---|
Tempo de espera inicial (segundos) | 1 | 1 |
Multiplicador de tempo de espera por iteração (segundos) | 2 | 2 |
Tempo máximo de espera (segundos) | 64 | 60 |
Prazo padrão (segundos) | 600 | 120 |
Instabilidade implementada | Sim | Não |
Um subconjunto de operações de mídia e não mídia só é idempotente se incluir argumentos opcionais específicos. As operações que são condicionalmente seguras para repetição são repetidas por padrão se o caso de condição for transmitido. Atualmente, essas condições incluem:
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
- É seguro repetir
if generation
ouif_generation_match
foi transmitido como um argumento para o método. Muitas vezes, os métodos aceitam apenas um desses dois parâmetros.
- É seguro repetir
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
Políticas de repetição para operações de mídia
Para operações de mídia, é possível configurar o argumento num_retries
para
métodos de upload para especificar o número de repetições de upload. Por padrão, apenas
uploads com a condição if_metageneration_match
são repetidos para
garantir a idempotência. Definir o argumento num_retries
substitui o
comportamento padrão e garante novas tentativas mesmo sem a
condição if_metageneration_match
.
Políticas de repetição para operações que não são de mídia
As operações que não são de mídia que são seguras ou condicionalmente seguras para repetir
têm um parâmetro retry
adicionado à assinatura do método. O padrão para
esses parâmetros é um dos seguintes:
DEFAULT_RETRY
DEFAULT_RETRY_IF_GENERATION_SPECIFIED
DEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
DEFAULT_RETRY_IF_ETAG_IN_JSON
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
. Por exemplo, para modificar o prazo padrão para 30
segundos, transmita retry=DEFAULT_RETRY.with_deadline(30)
. Recomendamos que você
modifique os atributos um por um. Para mais informações, consulte a
referência Repetir 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 a seguir exemplos de novas repetições condicionais personalizadas:
blob.reload()
usaDEFAULT_RETRY
por padrão. Para modificar isso para que a função não seja repetida, chame-a comoblob.reload(retry=None)
.bucket.update()
usaDEFAULT_RETRY_IF_METAGENERATION_SPECIFIED
por padrão. Para modificar isso para que a função repita novamente mesmo que o número de metageração não esteja especificado, chame-a como:from google.cloud.storage.retry import DEFAULT_RETRY bucket.update(retry=DEFAULT_RETRY)
bucket.list_blobs()
usaDEFAULT_RETRY
por padrão. Para modificar isso para que a chamada de API repita com um prazo de 20 segundos em vez dos 120 segundos padrão, chame-a como:from google.cloud.storage.retry import DEFAULT_RETRY modified_retry = DEFAULT_RETRY.with_deadline(20) bucket.list_blobs(retry=modified_retry)
Ruby
Por padrão, a biblioteca de cliente do Ruby usa espera exponencial.
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.
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 |
|
A seguir
- Saiba como repetir solicitações no Serviço de transferência do Cloud Storage com Java ou Python.
- Saiba mais sobre condições prévias e números de geração.