O Eventarc Standard é compatível com a entrega de eventos do tipo "pelo menos uma vez". Isso significa que, se um destino não confirmar o recebimento de um evento, o Eventarc tentará entregá-lo novamente de forma automática.
As características de nova tentativa do Eventarc Standard correspondem às da camada de transporte, o Cloud Pub/Sub, que processa falhas usando uma política de nova tentativa de assinatura.
Como funcionam as novas tentativas
Quando você cria um gatilho do Eventarc, o tópico e a assinatura de transporte do Pub/Sub são criados automaticamente. Os eventos de origens do Pub/Sub podem usar um tópico existente do Pub/Sub.
Qualquer ID de assinatura criado automaticamente pelo Eventarc terá um
formato que começa com eventarc-REGION-.
Por padrão, quando um destino não consegue confirmar uma mensagem, o Pub/Sub envia a mensagem novamente com um atraso de espera exponencial. Uma espera exponencial permite adicionar atrasos cada vez mais longos entre as tentativas de repetição. O atraso padrão começa em um mínimo de 10 segundos e aumenta com cada falha subsequente, até um máximo de 600 segundos. O Eventarc define a duração padrão de retenção de mensagens como 24 horas.
Para mais informações sobre como o Pub/Sub lida com novas tentativas, consulte Como corrigir falhas nas mensagens e Novas tentativas de solicitações.
Práticas recomendadas para lidar com novas tentativas
Se uma mensagem de evento não puder ser entregue na janela de retenção de mensagens, ela será descartada, a menos que um tópico de mensagens inativas seja configurado. Um tópico de mensagens inativas permite armazenar e analisar falhas persistentes. Neste documento, consulte Tópicos de mensagens inativas.
Devido à entrega do tipo "pelo menos uma vez", seu manipulador de eventos pode receber eventos duplicados. É uma prática recomendada projetar seus manipuladores para serem idempotentes. Neste documento, consulte Manipuladores de eventos idempotentes.
Novas tentativas para destinos do Cloud Run
Opcionalmente, para destinos do Cloud Run (incluindo o Cloud Run Functions), é possível configurar uma única tentativa de entrega sem novas tentativas. Quando você cria um gatilho do Eventarc no console doGoogle Cloud na página do Cloud Run, essa é a configuração padrão. Caso contrário, ao criar um gatilho usando a Google Cloud CLI, o Terraform ou no Google Cloud console na página do Eventarc, as novas tentativas são ativadas por padrão.
Recomendamos desativar as novas tentativas ao desenvolver ou testar seu código para evitar tentativas descontroladas que podem aumentar o custo e o uso de recursos. Por outro lado, recomendamos ativar as novas tentativas quando o código estiver em produção e seguir as práticas recomendadas para processar novas tentativas para que cada mensagem seja processada conforme o esperado. Por exemplo, é possível encaminhar mensagens não entregues para um tópico de mensagens inativas (também conhecido como fila de mensagens inativas) que permite armazenar e analisar falhas persistentes.
Para mais informações, consulte os seguintes guias do Cloud Run: Configurar repetições de funções orientadas a eventos e Criar gatilhos com o Eventarc.
Configurar novas tentativas
Talvez você queira personalizar o comportamento de repetição padrão. Todas as configurações de nova tentativa e retenção são configuradas pela política de nova tentativa da assinatura do Pub/Sub associada ao gatilho do Eventarc.
Para modificar a política de nova tentativa da assinatura, primeiro identifique a assinatura do Pub/Sub associada ao gatilho do Eventarc. Em seguida, atualize a assinatura.
Para mais informações sobre as propriedades da assinatura, consulte Propriedades de assinatura. Para informações sobre limites de assinatura, consulte Limites de recursos do Pub/Sub.
Identificar a assinatura
Para identificar a assinatura do Pub/Sub associada ao gatilho do Eventarc, faça o seguinte:
Console
No console Google Cloud , acesse a página Gatilhos do Eventarc.
Na lista de gatilhos, clique naqueles sobre os quais você quer mais detalhes.
Clique no nome do tópico.
Para mostrar o ID da assinatura, clique na guia Assinaturas.
gcloud
Use o comando
gcloud eventarc triggers describe
para recuperar o ID da assinatura.
gcloud eventarc triggers describe TRIGGER_NAME \ --location=LOCATION
Substitua:
TRIGGER_NAME: o nome do gatilho ou um identificador totalmente qualificado.LOCATION: o local do gatilho do Eventarc.
Esse comando retorna informações sobre o gatilho, como as seguintes, e inclui o ID da assinatura:
createTime: '2023-03-16T13:40:44.889670204Z'
destination:
cloudRun:
path: /
region: us-central1
service: hello
eventDataContentType: application/protobuf
eventFilters:
...
transport:
pubsub:
subscription: projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_ID/topics/TOPIC_ID
Terraform
Para descrever um recurso do Terraform google_eventarc_trigger, use o comando state show.
terraform state show google_eventarc_trigger.default
O comando state show retorna informações sobre o gatilho, incluindo o ID da assinatura. Exemplo:
# google_eventarc_trigger.default:
resource "google_eventarc_trigger" "default" {
conditions = {}
create_time = "2025-07-14T17:29:22.575033822Z"
effective_labels = {
"goog-terraform-provisioned" = "true"
}
...
transport {
pubsub {
subscription = "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
topic = "projects/PROJECT_ID/topics/TOPIC_ID"
}
}
}
Para mais informações sobre como usar o Terraform, consulte a documentação do Terraform em Google Cloud .
REST
Para descrever um gatilho em um determinado projeto e local, use o método projects.locations.triggers.get.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
TRIGGER_NAME: o nome do gatilho que você quer descrever.PROJECT_ID: o ID do projeto do Google Cloud.LOCATION: a região onde o gatilho é criado, por exemplo,us-central1.
Para enviar a solicitação, expanda uma destas opções:
Se houver êxito, o corpo da resposta conterá uma instância de Trigger semelhante a esta:
{
"name": "projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME",
"uid": "d700773a-698b-47b2-a712-2ee10b690062",
"createTime": "2022-12-06T22:44:04.744001514Z",
"updateTime": "2022-12-06T22:44:09.116459550Z",
"eventFilters": [
{
"attribute": "type",
"value": "google.cloud.pubsub.topic.v1.messagePublished"
}
],
"serviceAccount": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
"destination": {
"workflow": "projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_NAME"
},
"transport": {
"pubsub": {
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
}
}
}
Atualizar a assinatura
Para atualizar a política de nova tentativa da assinatura do Pub/Sub associada ao gatilho do Eventarc, faça o seguinte:
Console
No console Google Cloud , acesse a página Gatilhos do Eventarc.
Na lista de gatilhos, clique naqueles sobre os quais você quer mais detalhes.
Clique no nome do tópico.
Para mostrar o ID da assinatura, clique na guia Assinaturas.
Clique no ID da assinatura e em Editar.
Na seção Política de novas tentativas, selecione Tentar novamente imediatamente.
Ou, para tentar de novo após um atraso de espera exponencial, insira os seguintes valores em segundos:
Espera mínima: o atraso mínimo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 10 segundos e precisa estar entre 0 e 600.
Espera máxima: o atraso máximo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 600 segundos e precisa estar entre 0 e 600.
Para mais informações, consulte Política de novas tentativas.
Clique em Atualizar.
gcloud
Use o comando
gcloud pubsub subscriptions update
para atualizar a política de novas tentativas de assinatura.
gcloud pubsub subscriptions update SUBSCRIPTION_ID \ --min-retry-delay=MIN_RETRY_DELAY \ --max-retry-delay=MAX_RETRY_DELAY
Substitua:
SUBSCRIPTION_ID: o ID da assinatura ou um identificador totalmente qualificado.As duas flags a seguir precisam ser especificadas para tentar novamente após um atraso de espera exponencial. Caso contrário, qualquer flag omitida volta ao valor padrão:
MIN_RETRY_DELAY: o atraso mínimo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 10 segundos e precisa estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 600 segundos e precisa estar entre 0 e 600.
Se quiser, use a flag --clear-retry-policy para limpar a política de novas tentativas e definir a assinatura para tentar novamente imediatamente.
Terraform
É possível atualizar uma política de nova tentativa de assinatura do Pub/Sub
configurando o recurso do Terraform
google_pubsub_subscription. Use o bloco
import
para importar a assinatura atual e permitir que o Terraform rastreie o recurso
no arquivo de estado. Em seguida, é possível gerenciar o recurso importado como qualquer outro,
usando
ignore_changes
para especificar atributos que o Terraform deve ignorar ao atualizar o
recurso.
Exemplo:
import { to = google_pubsub_subscription.default id = "SUBSCRIPTION_ID" } resource "google_pubsub_subscription" "default" { name = "SUBSCRIPTION_ID" topic = "TOPIC_ID" retry_policy { minimum_backoff = "MIN_RETRY_DELAYs" maximum_backoff = "MAX_RETRY_DELAYs" } lifecycle { # Ignore push delivery configuration which is managed by Eventarc ignore_changes = [push_config] } }
Substitua:
SUBSCRIPTION_ID: o ID da assinatura.TOPIC_ID: o ID do tópico.MIN_RETRY_DELAY: o atraso mínimo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 10 segundos e precisa estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 600 segundos e precisa estar entre 0 e 600.
REST
Para atualizar a política de novas tentativas de uma assinatura em um determinado projeto, use o método
projects.subscriptions.patch.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
MIN_RETRY_DELAY: o atraso mínimo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 10 segundos, e o valor precisa estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre entregas consecutivas de uma determinada mensagem. O padrão é 600 segundos e precisa estar entre 0 e 600.PROJECT_ID: o ID do projeto do Google Cloud.SUBSCRIPTION_ID: o ID da assinatura do Pub/Sub que você está atualizando.
Corpo JSON da solicitação:
{
"subscription": {
"retryPolicy": {
"minimumBackoff": "MIN_RETRY_DELAYs",
"maximumBackoff": "MAX_RETRY_DELAYs"
}
},
"updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
Para enviar a solicitação, expanda uma destas opções:
Se houver êxito, o corpo da resposta conterá uma instância de Subscription semelhante a esta:
{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
...
"retryPolicy": {
"minimumBackoff": "MIN_RETRY_DELAYs",
"maximumBackoff": "MAX_RETRY_DELAYs"
},
"state": "ACTIVE"
}
Outras considerações sobre repetição
É importante considerar o seguinte ao lidar com falhas de processamento ou encaminhar mensagens não entregues.
Backoffs de push
Se um assinante de push enviar muitas confirmações negativas, o Pub/Sub poderá começar a entregar mensagens usando um backoff de push. Quando o Pub/Sub usa uma espera de push, ele para de entregar mensagens por um período de tempo predeterminado. Esse período pode variar de 100 milissegundos a 60 segundos. Depois que o tempo expirar, o Pub/Sub vai começar a entregar mensagens novamente. Para mais informações, consulte Desistência de push.
Tópicos de mensagens inativas
Se o destino não receber a mensagem, será possível encaminhar as mensagens não entregues para um tópico de mensagens inativas (também conhecido como fila de mensagens inativas). Um tópico de mensagens inativas pode armazenar mensagens que o destino não consegue confirmar. Defina um tópico de mensagens inativas ao criar ou atualizar uma assinatura do Pub/Sub, não ao criar um tópico do Pub/Sub ou quando o Eventarc cria um tópico do Pub/Sub. Para mais informações, consulte Configurar um tópico de mensagens inativas.
Erros que não garantem novas tentativas
Quando os aplicativos usam o Pub/Sub como a fonte do evento e o evento não é entregue, ele é repetido automaticamente, com exceção dos erros que não garantem novas tentativas. Os eventos para um destino dos Workflows de qualquer origem não serão repetidos se o fluxo de trabalho não for executado. O Workflows reconhece eventos assim que a execução do fluxo de trabalho é iniciada. Se a execução do fluxo de trabalho começar, mas depois falhar, as execuções não serão repetidas. Para resolver esses problemas de serviço, você precisa processar erros e novas tentativas no fluxo de trabalho.
Duplicar eventos
Eventos duplicados podem ser entregues aos manipuladores de eventos. De acordo com a
especificação do CloudEvents, a combinação dos atributos source e id é considerada única e,
portanto, todos os eventos com a mesma combinação são considerados duplicados. Implemente manipuladores de eventos idempotentes como prática recomendada geral.
Manipuladores de eventos idempotentes
Os manipuladores de eventos que podem ser repetidos precisam ser idempotentes. Para isso, siga as seguintes diretrizes gerais:
- Muitas APIs externas permitem o fornecimento de uma chave de idempotência como um parâmetro. Se você estiver usando uma API como essa, utilize o ID do evento como chave de idempotência.
- A idempotência funciona bem com a entrega do tipo "pelo menos uma vez", porque torna as novas tentativas mais seguras. Dessa forma, para escrever um código confiável, a prática recomendada é combinar idempotência com tentativas.
- Verifique se o código é idempotente internamente. Por exemplo:
- Garanta que mutações possam ocorrer mais de uma vez sem alterar o resultado.
- Consulte o estado do banco de dados em uma transação antes de alterar o estado.
- Certifique-se de que todos os efeitos colaterais sejam idempotentes.
- Execute uma verificação transacional fora do serviço, independente do código. Por exemplo, mantenha a persistência de estado em algum local e registre que um determinado código de evento já foi processado.
- Lide com chamadas duplicadas fora da banda. Por exemplo, tenha um processo de limpeza separado que seja executado após chamadas duplicadas.