Reintentar eventos

Eventarc Standard 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 enviarlo automáticamente.

Las características de reintento de Eventarc Standard coinciden con las de su capa de transporte, Cloud Pub/Sub, que gestiona los errores de procesamiento mediante una política de reintento de suscripción.

Cómo funcionan los reintentos

Cuando creas un activador de Eventarc, se crean automáticamente el tema y la suscripción de transporte de Pub/Sub. Los eventos de fuentes de Pub/Sub pueden usar un tema de Pub/Sub. Los IDs de suscripción que cree automáticamente Eventarc tendrán un formato que empiece por eventarc-REGION-.

De forma predeterminada, cuando un destino no puede confirmar un mensaje, Pub/Sub vuelve a enviar el mensaje con un retraso de espera exponencial. Un tiempo de espera exponencial te permite añadir retrasos cada vez más largos entre los intentos. El retraso predeterminado empieza con un mínimo de 10 segundos y aumenta con cada fallo posterior hasta un máximo de 600 segundos. Eventarc establece la duración predeterminada de retención de mensajes en 24 horas.

Para obtener más información sobre cómo gestiona Pub/Sub los reintentos, consulta Gestionar errores de mensajes y Reintentar solicitudes.

Prácticas recomendadas para gestionar reintentos

Si un mensaje de evento no se puede entregar correctamente en el periodo de retención de mensajes, se descarta a menos que se configure un tema de mensajes fallidos. Un tema de mensajes fallidos te permite almacenar y analizar fallos persistentes. En este documento, consulta Temas de mensajes fallidos.

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

Configurar reintentos

Puede que quieras personalizar el comportamiento de reintento predeterminado. Todos los ajustes de reintento y retención se configuran mediante la política de reintento de la suscripción de Pub/Sub asociada a tu activador de Eventarc.

Para modificar la política de reintentos de la suscripción, primero debe identificar la suscripción de Pub/Sub asociada a su activador de Eventarc. A continuación, actualiza la suscripción.

Para obtener más información sobre las propiedades de las suscripciones, consulta Propiedades de las suscripciones. Para obtener información sobre los límites de las suscripciones, 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"
    }
  }
}

Actualizar la suscripción

Para actualizar la política de reintentos de la suscripción de Pub/Sub asociada a 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

Debe tener en cuenta lo siguiente al gestionar los errores de procesamiento o reenviar mensajes no entregados.

Retrasos de envío

Si un suscriptor push envía demasiadas confirmaciones negativas, Pub/Sub puede empezar a enviar mensajes mediante un retroceso push. Cuando Pub/Sub usa un retroceso de inserción, deja de enviar mensajes durante un periodo predeterminado. Este periodo puede oscilar entre 100 milisegundos y 60 segundos. Una vez transcurrido el tiempo, Pub/Sub vuelve a enviar mensajes. Para obtener más información, consulta Retraso de envío.

Temas de mensajes fallidos

Si el destino no recibe el mensaje, puedes reenviar los mensajes no entregados a un tema de mensajes fallidos (también conocido como cola de mensajes fallidos). Un tema de mensajes fallidos puede almacenar mensajes que el destino no puede confirmar. Debes definir un tema de mensajes fallidos al crear o actualizar una suscripción de Pub/Sub, no al crear un tema de Pub/Sub o cuando Eventarc crea un tema de Pub/Sub. Para obtener más información, consulta Configurar un tema de mensajes fallidos.

Errores que no justifican reintentos

Cuando las aplicaciones usan Pub/Sub como origen de eventos y el evento no se entrega, se vuelve a intentar automáticamente, excepto en el caso de los errores que no justifican reintentos. Los eventos enviados a un destino de Workflows desde cualquier origen no se volverán a intentar si el flujo de trabajo no se ejecuta. Ten en cuenta que Workflows confirma los eventos en cuanto empieza la ejecución del flujo de trabajo. Si la ejecución del flujo de trabajo se inicia, pero falla más adelante, no se vuelve a intentar. Para solucionar estos problemas de servicio, debes gestionar los errores y los reintentos en el flujo de trabajo.

Duplicación de eventos

Es posible que se envíen eventos duplicados a los controladores de eventos. Según la especificación de CloudEvents, la combinación de los atributos source y id se considera única, por lo que los eventos con la misma combinación se consideran duplicados. Como práctica recomendada general, debes implementar controladores de eventos idempotentes.

Gestores de eventos idempotentes

Los controladores de eventos que se pueden volver a intentar deben ser idempotentes y seguir estas directrices 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 clave de idempotencia.
• La idempotencia funciona bien con la entrega al menos una vez, ya que permite reintentar la operación de forma segura. Por lo tanto, una práctica recomendada general para escribir código fiable es combinar la idempotencia con los reintentos.
• Asegúrate de que tu código sea idempotente internamente. Por ejemplo:
  • Asegúrate de que las mutaciones puedan producirse más de una vez sin cambiar 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.
• Imponer una comprobación transaccional fuera de tu servicio, independientemente del código. Por ejemplo, persiste el estado en algún lugar registrando que ya se ha procesado un ID de evento determinado.
• Gestiona las llamadas duplicadas fuera de banda. Por ejemplo, puedes tener un proceso de limpieza independiente que se ejecute después de las llamadas duplicadas.