Eventarc Standard admite la entrega de eventos "al menos una vez". Esto significa que, si un destino no confirma un evento, Eventarc intentará volver a entregarlo de forma automática.
Las características de reintento de Eventarc Standard coinciden con las de su capa de transporte, Cloud Pub/Sub, que controla las fallas de procesamiento mediante 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. (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 vuelve 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 Controla las fallas de los mensajes y Reintenta las solicitudes.
Prácticas recomendadas para controlar los reintentos
Si un mensaje de evento no se puede entregar correctamente 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 fallas 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 reintento predeterminado. Todos los parámetros de configuración de reintento y retención se configuran a través de la política de reintento de suscripción de Pub/Sub asociada con tu activador de Eventarc.
Para modificar la política de reintento de 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 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 con tu activador de Eventarc, haz lo siguiente:
Console
En la consola de Google Cloud , ve a la página Activadores de Eventarc.
En la lista de activadores, haz clic en el activador cuyos detalles deseas conocer.
Haz clic en el nombre del tema.
Para mostrar el ID de suscripción, haz clic en la pestaña Suscripciones.
gcloud
Puedes usar el
gcloud eventarc triggers describe
comando para recuperar el ID de suscripción.
gcloud eventarc triggers describe TRIGGER_NAME \ --location=LOCATION
Reemplaza lo siguiente:
TRIGGER_NAME: el nombre del activador o un identificador completamente calificado.LOCATION: la ubicación del activador de Eventarc.
Con este comando, se muestra información sobre el activador que es similar a la siguiente y que incluye el ID de suscripción:
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 describir un
google_eventarc_trigger
recurso de Terraform, puedes usar el comando state show.
terraform state show google_eventarc_trigger.default
El comando state show muestra información sobre el activador que incluye el ID de suscripción. Por ejemplo:
# 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 obtener más información sobre el uso de Terraform, consulta la documentación de Terraform. Google Cloud
REST
Para describir un activador en un proyecto y una ubicación determinados, usa el
método projects.locations.triggers.get.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
TRIGGER_NAME: el nombre del activador que deseas describir.PROJECT_ID: tu Google Cloud ID del proyecto.LOCATION: la región en la que se crea el activador, por ejemplo,us-central1.
Para enviar tu solicitud, expande una de estas opciones:
Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de
Trigger
similar a la siguiente:
{
"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 suscripción de Pub/Sub asociada con tu activador de Eventarc, haz lo siguiente:
Console
En la consola de Google Cloud , ve a la página Activadores de Eventarc.
En la lista de activadores, haz clic en el activador cuyos detalles deseas conocer.
Haz clic en el nombre del tema.
Para mostrar el ID de suscripción, haz clic en la pestaña Suscripciones.
Haz clic en el ID de suscripción y, luego, en Editar.
En la sección Política de reintentos, selecciona Reintentar de inmediato.
O bien, para reintentar después de un retraso de retirada exponencial, ingresa los siguientes valores en segundos:
Retirada mínima: Es el retraso mínimo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 10 segundos y debe estar entre 0 y 600.
Retirada máxima: Es el retraso máximo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 600 segundos y debe estar entre 0 y 600.
Para obtener más información, consulta Política de reintentos.
Haz clic en Actualizar.
gcloud
Puedes usar el
gcloud pubsub subscriptions update
comando para actualizar la política de reintento de suscripción.
gcloud pubsub subscriptions update SUBSCRIPTION_ID \ --min-retry-delay=MIN_RETRY_DELAY \ --max-retry-delay=MAX_RETRY_DELAY
Reemplaza lo siguiente:
SUBSCRIPTION_ID: el ID de la suscripción o un identificador completamente calificado.Se deben especificar las siguientes marcas para reintentar después de un retraso de retirada exponencial; de lo contrario, cualquier marca omitida volverá a su valor predeterminado:
MIN_RETRY_DELAY: Es el retraso mínimo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 10 segundos y debe estar entre 0 y 600.MAX_RETRY_DELAY: Es el retraso máximo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 600 segundos y debe estar entre 0 y 600.
De manera opcional, puedes usar la marca --clear-retry-policy para borrar la política de reintento y configurar la suscripción para que se reintente de inmediato.
Terraform
Puedes actualizar una política de reintento de suscripción de Pub/Sub si
configuras el
google_pubsub_subscription
recurso de Terraform. Usa el
import bloque
para importar la suscripción existente de modo que Terraform pueda hacer un seguimiento del recurso
en tu archivo de estado. Luego, puedes administrar el recurso importado como cualquier otro,
usando
ignore_changes
para especificar los atributos que Terraform debe ignorar cuando actualiza el
recurso.
Por ejemplo:
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] } }
Reemplaza lo siguiente:
SUBSCRIPTION_ID: el ID de la suscripción.TOPIC_ID: el ID del tema.MIN_RETRY_DELAY: Es el retraso mínimo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 10 segundos y debe estar entre 0 y 600.MAX_RETRY_DELAY: Es el retraso máximo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 600 segundos y debe estar entre 0 y 600.
REST
Para actualizar la política de reintento de una suscripción en un proyecto determinado, usa el
projects.subscriptions.patch
método.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
MIN_RETRY_DELAY: Es el retraso mínimo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 10 segundos y debe estar entre 0 y 600.MAX_RETRY_DELAY: Es el retraso máximo en segundos entre las entregas consecutivas de un mensaje determinado. El valor predeterminado es 600 segundos y debe estar entre 0 y 600.PROJECT_ID: tu Google Cloud ID del proyecto.SUBSCRIPTION_ID: el ID de la suscripción de Pub/Sub que estás actualizando.
Cuerpo JSON de la solicitud:
{
"subscription": {
"retryPolicy": {
"minimumBackoff": "MIN_RETRY_DELAYs",
"maximumBackoff": "MAX_RETRY_DELAYs"
}
},
"updateMask": "retry_policy.maximum_backoff,retry_policy.minimum_backoff"
}
Para enviar tu solicitud, expande una de estas opciones:
Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de
Subscription
similar a la siguiente:
{
"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 controles las fallas 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 podría 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 oscilar 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 Retirada 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 errores y 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 source y id atributos 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.