O Eventarc Standard oferece suporte à entrega de eventos pelo menos uma vez. Isso significa que, se um destino não confirmar 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
Ao criar 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 a envia novamente com um atraso de espera exponencial. Uma espera exponencial permite adicionar atrasos cada vez mais longos entre as novas tentativas. O atraso padrão 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 padrão de retenção de mensagens como 24 horas.
Para mais informações sobre como o Pub/Sub processa novas tentativas, consulte Processar falhas de mensagens e Novas tentativas de solicitações.
Práticas recomendadas para processar 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 pelo menos uma vez, o manipulador de eventos pode receber eventos duplicados. É uma prática recomendada projetar seus gerenciadores para serem idempotentes. Neste documento, consulte Gerenciadores de eventos idempotentes.
Novas tentativas para destinos do Cloud Run
Opcionalmente, para destinos do Cloud Run (incluindo funções do Cloud Run), é possível configurar uma única tentativa de entrega sem novas tentativas. Ao criar um gatilho do Eventarc no Google Cloud console 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 o código para evitar tentativas descontroladas que podem levar a aumento de custos e 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 novas tentativas de funções orientadas a eventos e Criar gatilhos com o Eventarc.
Configurar novas tentativas
Talvez você queira personalizar o comportamento padrão de novas tentativas. Todas as configurações de nova tentativa e retenção são configuradas pela política de nova tentativa de assinatura do Pub/Sub associada ao gatilho do Eventarc.
Para modificar a política de nova tentativa de 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 da 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 Google Cloud console, 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
É possível usar o
gcloud eventarc triggers describe
comando 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, semelhantes às 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
google_eventarc_trigger
recurso do Terraform, use o state show comando.
terraform state show google_eventarc_trigger.default
O comando state show retorna informações sobre o gatilho que incluem 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 Google Cloud do Terraform.
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 estas substituições:
TRIGGER_NAME: o nome do gatilho que você quer descrever.PROJECT_ID: o ID do seu Google Cloud projeto.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 de assinatura do Pub/Sub associada ao gatilho do Eventarc, faça o seguinte:
Console
No Google Cloud console, 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 nova tentativa, selecione Repetir imediatamente.
Ou, para repetir 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 nova tentativa.
Clique em Atualizar.
gcloud
É possível usar o
gcloud pubsub subscriptions update
comando para atualizar a política de nova tentativa 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 repetir após um atraso de espera exponencial. Caso contrário, qualquer flag omitida será revertida para o 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.
Opcionalmente, é possível usar a flag --clear-retry-policy para limpar a política de nova tentativa e definir a assinatura para repetir imediatamente.
Terraform
É possível atualizar uma política de nova tentativa de assinatura do Pub/Sub ao
configurar o
google_pubsub_subscription
recurso do Terraform. Use o
import bloco
para importar a assinatura atual para que o Terraform possa rastrear 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 precisa 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 nova tentativa de uma assinatura em um determinado projeto, use o
projects.subscriptions.patch
método.
Antes de usar os dados da solicitação abaixo, faça estas substituições:
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.PROJECT_ID: o ID do seu Google Cloud projeto.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 novas tentativas
Esteja ciente das seguintes considerações ao processar falhas ou encaminhar mensagens não entregues.
Esperas de push
Se um assinante de push enviar muitas confirmações negativas, o Pub/Sub poderá começar a entregar mensagens usando uma espera de push. Quando o Pub/Sub usa uma espera de push, ele interrompe a entrega de mensagens por um período predeterminado. Esse período pode variar de 100 milissegundos a 60 segundos. Após o tempo decorrido, o Pub/Sub começa a entregar mensagens novamente. Para mais informações, consulte Espera 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 do Workflows de qualquer origem não serão repetidos se o fluxo de trabalho não for executado. Observação: 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.
Gerenciadores 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.