Eventos de reintento

Eventarc Estándar admite la entrega de eventos al menos una vez. Esto significa que, si un destino no confirma la recepción de un evento, Eventarc intentará volver a entregarlo automáticamente.

Las características de reintento de Eventarc Estándar coinciden con las de su capa de transporte, Cloud Pub/Sub, que controla las fallas de procesamiento con una política de reintento de suscripción.

Cómo funcionan los reintentos

Cuando creas un activador de Eventarc, el tema y la suscripción de transporte de Pub/Sub se crean automáticamente para ti. (Los eventos de las fuentes de Pub/Sub pueden usar un tema de Pub/Sub existente). Cualquier ID de suscripción creado automáticamente por Eventarc tendrá un formato que comienza con eventarc-REGION-.

De forma predeterminada, cuando un destino no puede confirmar un mensaje, Pub/Sub volverá a enviar el mensaje con un retraso de retirada exponencial. Una retirada exponencial te permite agregar retrasos cada vez más largos entre los reintentos. El retraso predeterminado comienza con un mínimo de 10 segundos y aumenta con cada falla posterior, hasta un máximo de 600 segundos. Eventarc establece la duración predeterminada de la retención de mensajes en 24 horas.

Para obtener más información sobre cómo Pub/Sub controla los reintentos, consulta Cómo controlar las fallas de los mensajes y Cómo reintentar solicitudes.

Prácticas recomendadas para controlar los reintentos

Si no se puede entregar correctamente un mensaje de evento dentro del período de retención de mensajes, se descarta, a menos que se configure un tema de mensajes no entregados. Un tema de mensajes no entregados te permite almacenar y analizar errores persistentes. En este documento, consulta Temas de mensajes no entregados.

Debido a la entrega al menos una vez, es posible que tu controlador de eventos reciba eventos duplicados. Se recomienda diseñar tus controladores para que sean idempotentes. En este documento, consulta Controladores de eventos idempotentes.

Configura reintentos

Es posible que desees personalizar el comportamiento de reintentos predeterminado. Todos los parámetros de configuración de reintentos y retención se configuran a través de la política de reintentos de la suscripción de Pub/Sub asociada con tu activador de Eventarc.

Para modificar la política de reintentos de la suscripción, primero identifica la suscripción de Pub/Sub asociada con tu activador de Eventarc. Luego, actualiza la suscripción.

Para obtener más información sobre las propiedades de suscripción, consulta Propiedades de la suscripción. Para obtener información sobre los límites de suscripción, consulta Límites de recursos de Pub/Sub.

Identifica la suscripción

Para identificar la suscripción de Pub/Sub asociada a tu activador de Eventarc, haz lo siguiente:

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

Actualiza la suscripción

Para actualizar la política de reintento de la suscripción a Pub/Sub asociada con tu activador de Eventarc, haz lo siguiente:

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

Otras consideraciones sobre los reintentos

Debes tener en cuenta los siguientes factores cuando manejes errores de procesamiento o reenvíes mensajes no entregados.

Retiradas de envío

Si un suscriptor de envío envía demasiadas confirmaciones negativas, Pub/Sub puede comenzar a entregar mensajes con una retirada de envío. Cuando Pub/Sub usa una retirada de envío, deja de entregar mensajes durante un período predeterminado. Este período puede variar entre 100 milisegundos y 60 segundos. Una vez transcurrido el tiempo, Pub/Sub comienza a entregar mensajes de nuevo. Para obtener más información, consulta Retraso exponencial de reintentos de envío.

Temas de mensajes no entregados

Si el destino no recibe el mensaje, puedes reenviar los mensajes no entregados a un tema de mensajes no entregados (también conocido como la cola de mensajes no entregados). Un tema de mensajes no entregados puede almacenar mensajes que el destino no puede confirmar. Debes establecer un tema de mensajes no entregados cuando crees o actualices una suscripción de Pub/Sub, no cuando crees un tema de Pub/Sub o cuando Eventarc cree un tema de Pub/Sub. Para obtener más información, consulta Configura un tema de mensajes no entregados.

Errores que no garantizan reintentos

Cuando las aplicaciones usan Pub/Sub como la fuente del evento y dicho evento no se entrega, se vuelve a intentar el evento de forma automática, excepto los errores que no garantizan reintentos. Los eventos a un destino de Workflows desde cualquier fuente no se volverán a intentar si el flujo de trabajo no se ejecuta. Ten en cuenta que Workflows confirma los eventos apenas comienza la ejecución del flujo de trabajo. Si se inicia la ejecución del flujo de trabajo, pero luego falla, no se reintentan las ejecuciones. Para resolver estos problemas de servicio, debes manejar los errores y los reintentos dentro del flujo de trabajo.

Eventos duplicados

Los eventos duplicados pueden entregarse a los controladores de eventos. Según la especificación de CloudEvents, la combinación de los atributos source y id se considera única y, por lo tanto, cualquier evento con la misma combinación se considera duplicado. Debes implementar controladores de eventos idempotentes como práctica recomendada general.

Controladores de eventos idempotentes

Los controladores de eventos que se pueden reintentar deben ser idempotentes con los siguientes lineamientos generales:

• Muchas APIs externas te permiten proporcionar una clave de idempotencia como parámetro. Si usas una API de este tipo, debes usar el ID de evento como la clave de idempotencia.
• La idempotencia funciona bien con la entrega "al menos una vez", ya que permite que los reintentos sean seguros. Por lo tanto, una recomendación general para escribir un código confiable es combinar la idempotencia con los intentos reiterados.
• Asegúrate de que tu código sea idempotente de forma interna. Por ejemplo:
  • Asegúrate de que puedan ocurrir mutaciones más de una vez sin que cambie el resultado.
  • Consulta el estado de la base de datos en una transacción antes de mutar el estado.
  • Asegúrate de que todos los efectos secundarios sean idempotentes en sí.
• Debes imponer una verificación transaccional fuera del servicio, sin importar el código. Por ejemplo, conserva el estado en algún lugar que registre si ya se procesó un ID de evento determinado.
• Administra las llamadas duplicadas fuera de banda. Por ejemplo, implementa un proceso de limpieza independiente que borre las llamadas duplicadas.