Novas tentativas de eventos

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 lida com falhas de processamento usando uma política de nova tentativa de assinatura.

Como as novas tentativas funcionam

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. Com uma espera exponencial, é possível 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 da 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 esteja configurado. Um tópico de mensagens inativas permite armazenar e analisar falhas persistentes. Neste documento, consulte Tópicos de mensagens inativas.

Devido à entrega de 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.

Configurar novas tentativas

Talvez você queira personalizar o comportamento de repetição padrão. Todas as configurações de repetição e retenção são configuradas pela política de repetição de 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 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 seu gatilho do Eventarc, faça o seguinte:

gcloud eventarc triggers describe TRIGGER_NAME \
    --location=LOCATION

  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 state show google_eventarc_trigger.default

# 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"
        }
    }
}

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/triggers/TRIGGER_NAME" | Select-Object -Expand Content

{
  "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:

gcloud pubsub subscriptions update SUBSCRIPTION_ID \
    --min-retry-delay=MIN_RETRY_DELAY \
    --max-retry-delay=MAX_RETRY_DELAY

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]
  }
}

{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}

cat > request.json << 'EOF'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
EOF

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"

@'
{
  "subscription": {
    "retryPolicy": {
      "minimumBackoff": "MIN_RETRY_DELAYs",
      "maximumBackoff": "MAX_RETRY_DELAYs"
    }
  },
  "updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID" | Select-Object -Expand Content

{
  "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

Você precisa estar ciente das seguintes considerações ao lidar com falhas de processamento ou encaminhar mensagens não entregues.

Espera 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 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 Redução 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. 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.