Repetir estratégia

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 e 429, 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:

1. Faça uma solicitação ao Cloud Storage.

2. Se a solicitação falhar, aguarde 1 + random_number_milliseconds segundos e repita a solicitação.

3. Se a solicitação falhar, aguarde 2 + random_number_milliseconds segundos e repita a solicitação.

4. Se a solicitação falhar, aguarde 4 + random_number_milliseconds segundos e repita a solicitação.

5. E assim por diante, até um tempo maximum_backoff.

6. Continue aguardando e repetindo até uma quantidade máxima de tempo (deadline), mas não aumente o período de espera de maximum_backoff entre as repetições.

onde:

• O tempo de espera é min(((2ⁿ)+random_number_milliseconds), maximum_backoff), com n 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 de random_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 como Client.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 ou if_generation_match foi 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.

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() usa DEFAULT_RETRY por padrão. Para modificar isso para que a função não seja repetida, chame-a como blob.reload(retry=None).

• bucket.update() usa DEFAULT_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() usa DEFAULT_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	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 IfMetagenerationMatch ou ETag como condição prévia HTTP Solicitações de atualização/patch para objetos com IfMetagenerationMatch ou ETag como condição prévia HTTP Definir uma política de IAM do bucket com a ETag como condição prévia HTTP ou no corpo do recurso Atualizar uma chave HMAC com ETag como condição prévia HTTP ou no corpo do recurso Inserir, copiar, compor ou regravar objetos com ifGenerationMatch Excluir um objeto com ifGenerationMatch (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

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.