O Eventarc Standard suporta a entrega de eventos, pelo menos, uma vez. Isto significa que, se um destino não confirmar um evento, o Eventarc tenta reenviá-lo automaticamente.
As caraterísticas de nova tentativa do Eventarc Standard correspondem às da respetiva camada de transporte, o Cloud Pub/Sub, que processa as falhas de processamento através de uma política de novas tentativas de subscrição.
Como funcionam as novas tentativas
Quando cria um acionador do Eventarc, o tópico e a subscrição de transporte do Pub/Sub
são criados automaticamente para si. (Os eventos de origens do Pub/Sub podem usar um tópico do Pub/Sub existente.)
Qualquer ID de subscrição criado automaticamente pelo Eventarc tem um formato que começa por eventarc-REGION-.
Por predefinição, quando um destino não consegue acusar a receção de uma mensagem, o Pub/Sub envia a mensagem novamente com um atraso de recuo exponencial. Uma retirada exponencial permite-lhe adicionar intervalos de tempo progressivamente mais longos entre as tentativas de repetição. O atraso predefinido começa com 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 da retenção de mensagens predefinida como 24 horas.
Para mais informações sobre como o Pub/Sub processa as novas tentativas, consulte os artigos Processar falhas de mensagens e Repetir pedidos.
Práticas recomendadas para o processamento de novas tentativas
Se não for possível entregar uma mensagem de evento com êxito dentro do período de retenção de mensagens, esta é rejeitada, a menos que esteja configurado um tópico de mensagens não entregues. Um tópico de mensagens não entregues permite-lhe armazenar e analisar falhas persistentes. Neste documento, consulte Tópicos de mensagens não entregues.
Devido à entrega, pelo menos, uma vez, o seu controlador de eventos pode receber eventos duplicados. É uma prática recomendada criar os seus controladores para serem idempotentes. Neste documento, consulte a secção Controladores de eventos idempotentes.
Configure novas tentativas
Pode querer personalizar o comportamento de repetição predefinido. Todas as definições de repetição e retenção são configuradas através da política de repetição de subscrição do Pub/Sub associada ao seu acionador do Eventarc.
Para modificar a política de repetição da subscrição, comece por identificar a subscrição do Pub/Sub associada ao seu acionador do Eventarc. Em seguida, atualize a própria subscrição.
Para mais informações sobre as propriedades de subscrição, consulte o artigo Propriedades de subscrição. Para ver informações sobre os limites de subscrição, consulte o artigo Limites de recursos do Pub/Sub.
Identifique a subscrição
Para identificar a subscrição do Pub/Sub associada ao seu acionador do Eventarc, faça o seguinte:
Consola
Na Google Cloud consola, aceda à página Triggers do Eventarc.
Na lista de acionadores, clique no acionador cujos detalhes quer saber.
Clique no nome do tópico.
Para apresentar o ID da subscrição, clique no separador Subscrições.
gcloud
Pode usar o comando
gcloud eventarc triggers describe
para obter o ID da subscrição.
gcloud eventarc triggers describe TRIGGER_NAME \ --location=LOCATION
Substitua o seguinte:
TRIGGER_NAME: o nome do acionador ou um identificador totalmente qualificado.LOCATION: a localização do acionador do Eventarc.
Este comando devolve informações sobre o acionador semelhantes às seguintes e que incluem o ID da subscrição:
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, pode usar o comando state show.google_eventarc_trigger
terraform state show google_eventarc_trigger.default
O comando state show devolve informações sobre o acionador que incluem o ID da subscrição. Por 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 a utilização do Terraform, consulte a documentação do Terraform no Google Cloud .
REST
Para descrever um acionador num determinado projeto e localização, use o método
projects.locations.triggers.get.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
TRIGGER_NAME: o nome do acionador que quer descrever.PROJECT_ID: o ID do seu Google Cloud projeto.LOCATION: a região na qual o acionador é criado, por exemplo,us-central1.
Para enviar o seu pedido, expanda uma destas opções:
Se for bem-sucedido, o corpo da resposta contém uma instância de
Trigger
semelhante à seguinte:
{
"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"
}
}
}
Atualize a subscrição
Para atualizar a política de repetição da subscrição do Pub/Sub associada ao seu acionador do Eventarc, faça o seguinte:
Consola
Na Google Cloud consola, aceda à página Triggers do Eventarc.
Na lista de acionadores, clique no acionador cujos detalhes quer saber.
Clique no nome do tópico.
Para apresentar o ID da subscrição, clique no separador Subscrições.
Clique no ID da subscrição e, de seguida, clique em Editar.
Na secção Política de repetição, selecione Repetir imediatamente.
Em alternativa, para tentar novamente após um atraso de retirada exponencial, introduza os seguintes valores em segundos:
Recuo mínimo: o atraso mínimo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 10 segundos e deve estar entre 0 e 600.
Recuo máximo: o atraso máximo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 600 segundos e deve estar entre 0 e 600.
Para mais informações, consulte a Política de Repetição.
Clique em Atualizar.
gcloud
Pode usar o comando
gcloud pubsub subscriptions update
para atualizar a política de novas tentativas de subscrição.
gcloud pubsub subscriptions update SUBSCRIPTION_ID \ --min-retry-delay=MIN_RETRY_DELAY \ --max-retry-delay=MAX_RETRY_DELAY
Substitua o seguinte:
SUBSCRIPTION_ID: o ID da subscrição ou um identificador totalmente qualificado.Tem de especificar ambas as flags seguintes para repetir após um atraso de recuo exponencial. Caso contrário, qualquer flag omitida reverte para o respetivo valor predefinido:
MIN_RETRY_DELAY: o atraso mínimo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 10 segundos e deve estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 600 segundos e deve estar entre 0 e 600.
Opcionalmente, pode usar a flag --clear-retry-policy para limpar a política de novas tentativas e definir a subscrição para tentar novamente imediatamente.
Terraform
Pode atualizar uma política de repetição de subscrição do Pub/Sub
configurando o recurso do Terraform
google_pubsub_subscription. Use o bloco
import
para importar a subscrição existente para que o Terraform possa acompanhar o recurso
no seu ficheiro de estado. Em seguida, pode gerir o recurso importado como qualquer outro, usando ignore_changes para especificar atributos que o Terraform deve ignorar ao atualizar o recurso.
Por 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 o seguinte:
SUBSCRIPTION_ID: o ID da subscrição.TOPIC_ID: o ID do tópico.MIN_RETRY_DELAY: o atraso mínimo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 10 segundos e deve estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 600 segundos e deve estar entre 0 e 600.
REST
Para atualizar a política de repetição de uma subscrição num determinado projeto, use o método
projects.subscriptions.patch.
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
MIN_RETRY_DELAY: o atraso mínimo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 10 segundos e deve estar entre 0 e 600.MAX_RETRY_DELAY: o atraso máximo em segundos entre as entregas consecutivas de uma determinada mensagem. A predefinição é 600 segundos e deve estar entre 0 e 600.PROJECT_ID: o ID do seu Google Cloud projeto.SUBSCRIPTION_ID: o ID da subscrição do Pub/Sub que está a atualizar.
Corpo JSON do pedido:
{
"subscription": {
"retryPolicy": {
"minimumBackoff": "MIN_RETRY_DELAYs",
"maximumBackoff": "MAX_RETRY_DELAYs"
}
},
"updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
Para enviar o seu pedido, expanda uma destas opções:
Se for bem-sucedido, o corpo da resposta contém uma instância de
Subscription
semelhante à seguinte:
{
"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ções
Deve ter em atenção as seguintes considerações ao processar falhas ou encaminhar mensagens não entregues.
Recuos de envio
Se um subscritor de push enviar demasiados reconhecimentos negativos, o Pub/Sub pode começar a entregar mensagens através de um recuo de push. Quando o Pub/Sub usa um recuo de envio, deixa de entregar mensagens durante um período predeterminado. Este intervalo de tempo pode variar entre 100 milissegundos e 60 segundos. Após o período de tempo, o Pub/Sub começa a enviar mensagens novamente. Para mais informações, consulte o artigo Push backoff.
Tópicos de mensagens não entregues
Se o destino não receber a mensagem, pode encaminhar mensagens não entregues para um tópico de mensagens não entregues (também conhecido como fila de mensagens não entregues). Um tópico de mensagens não entregues pode armazenar mensagens que o destino não consegue confirmar. Tem de definir um tópico de mensagens rejeitadas quando cria ou atualiza uma subscrição do Pub/Sub e não quando cria um tópico do Pub/Sub ou quando o Eventarc cria um tópico do Pub/Sub. Para mais informações, consulte o artigo Configure um tópico de mensagens não entregues.
Erros que não justificam novas tentativas
Quando as aplicações usam o Pub/Sub como a origem do evento e o evento não é entregue, é feita automaticamente uma nova tentativa de entrega do evento, exceto para erros que não justificam novas tentativas. Os eventos para um destino do Workflows a partir de qualquer origem não são repetidos se o fluxo de trabalho não for executado. Tenha em atenção que os fluxos de trabalho reconhecem os eventos assim que a execução do fluxo de trabalho começa. Se a execução do fluxo de trabalho começar, mas falhar mais tarde, as execuções não são repetidas. Para resolver estes problemas de serviço, deve processar os erros e as tentativas no fluxo de trabalho.
Eventos duplicados
Os eventos duplicados podem ser enviados para controladores de eventos. De acordo com a
especificação CloudEvents,
a combinação dos atributos source e id é considerada única e, por isso, todos os eventos com a mesma combinação são considerados duplicados. Deve implementar controladores de eventos idempotentes como prática recomendada geral.
Controladores de eventos idempotentes
Os controladores de eventos que podem ser repetidos devem ser idempotentes, usando as seguintes diretrizes gerais:
- Muitas APIs externas permitem-lhe fornecer uma chave de idempotência como parâmetro. Se estiver a usar uma API deste tipo, deve usar o ID do evento como chave de idempotência.
- A idempotência funciona bem com o fornecimento pelo menos uma vez, porque torna a repetição segura. Assim, uma prática recomendada geral para escrever código fiável é combinar a idempotência com as novas tentativas.
- Certifique-se de que o seu código é idempotente internamente. Por exemplo:
- Certifique-se de que as mutações podem ocorrer mais do que uma vez sem alterar o resultado.
- Consultar o estado da base de dados numa transação antes de alterar o estado.
- Certifique-se de que todos os efeitos secundários são idempotentes.
- Imponha uma verificação transacional fora do seu serviço, independentemente do código. Por exemplo, manter o estado num local que registe que um determinado ID do evento já foi processado.
- Lidar com chamadas duplicadas fora da banda. Por exemplo, ter um processo de limpeza separado que limpe após chamadas duplicadas.