Los disparadores de base de datos permiten ejecutar la lógica del servidor cada vez que se produce un cambio en la base de datos de un clúster de MongoDB Atlas vinculado. Se pueden configurar disparadores en colecciones individuales, bases de datos completas y en un clúster completo.
A diferencia de los desencadenadores de datos SQL, que se ejecutan en el servidor de base de datos, los desencadenadores se ejecutan en una capa de cómputo sin servidor que escala independientemente del servidor de base de datos. Los desencadenadores llaman automáticamente a las funciones de Atlas y pueden reenviar eventos a controladores externos a través de AWS EventBridge.
Utilice activadores de base de datos para implementar interacciones de datos impulsadas por eventos. Por ejemplo, se puede actualizar automáticamente la información en un documento cuando se actualiza un documento relacionado o enviar una solicitud a un servicio externo cada vez que se inserta un nuevo documento.
Los disparadores de base de datos utilizan flujos de cambios de MongoDB para detectar cambios en tiempo real en una colección. Un flujo de cambios es una serie de eventos de base de datos que describen una operación en un documento de la colección. La aplicación abre un nuevo flujo de cambios por cada disparador de base de datos creado en una colección.
Importante
Limitaciones del flujo de cambios
Existen límites en el número total de flujos de cambios que puedes abrir en un clúster, dependiendo del tamaño del clúster. Consulta limitaciones de flujos de cambios para obtener más información.
No se puede definir un activador de base de datos en una instancia sin servidor o en una instancia de base de datos federada porque no admiten flujos de cambio.
Usted controla qué operaciones activan un disparador y qué sucede cuando lo hace. Por ejemplo, puede ejecutar una función cada vez que se actualiza un campo específico de un documento. La función puede acceder a todo el evento de cambio, por lo que siempre sabrá qué ha cambiado. También puede pasar el evento de cambio a AWS EventBridge para gestionarlo fuera de Atlas.
Los activadores admiten expresiones $match para filtrar eventos de cambio y expresiones $project para limitar los datos incluidos en cada evento.
Advertencia
En los disparadores a nivel de implementación y base de datos, es posible configurarlos de forma que provoquen la activación de otros disparadores, lo que genera recursión. Por ejemplo, un disparador a nivel de base de datos que escribe en una colección dentro de la misma base de datos, o un registrador o reenviador de registros a nivel de clúster que escribe registros en otra base de datos del mismo clúster.
Crear un disparador de base de datos
Para abrir la pantalla de configuración del activador de la base de datos en la interfaz de usuario de App Services, haga clic en Triggers En el menú de navegación de la izquierda, haga clic en Create a Trigger y luego seleccione la pestaña Database junto a Trigger Type.
Configure el disparador y luego haga clic en Save en la parte inferior de la página para agregarlo a su borrador de implementación actual.
Para crear un activador de base de datos con la CLI de App Services:
Agregue un archivo de configuración de activación de base de datos a la
triggerssubdirectorio de un directorio de aplicación local.Implemente el activador:
appservices push
Nota
Atlas App Services no exige nombres de archivo específicos para los archivos de configuración de los disparadores. Sin embargo, una vez importados, Atlas App Services renombrará cada archivo de configuración para que coincida con el nombre del disparador que define, por ejemplo, mytrigger.json.
Configuración
Los activadores de base de datos tienen las siguientes opciones de configuración:
Detalles del disparador
En la sección Trigger Details, primero seleccione Trigger Type. Establezca este valor en Database para los activadores de la base de datos.
A continuación, seleccione Watch Against según el nivel de granularidad que desee. Sus opciones son:
Collection, cuando se produce un cambio en una colección específica
Database, cuando se produce un cambio en cualquier colección de una base de datos específica
DeploymentCuando se producen cambios en la implementación de un clúster específico. Si selecciona el tipo de origen de implementación, no se supervisarán los cambios en las siguientes bases de datos:
Las bases de datos de administración
admin,localyconfigLas bases de datos de sincronización
__realm_syncy__realm_sync_<app_id>
Importante
El tipo de fuente de nivel de implementación solo está disponible en niveles dedicados.
Las opciones adicionales varían según el tipo de fuente que utilice. La siguiente tabla describe estas opciones.
Tipo de fuente | opciones |
|---|---|
Collection |
|
Database |
|
Deployment |
|
Tip
Preimágenes y optimización del rendimiento
Las preimágenes requieren almacenamiento adicional, lo que puede afectar el rendimiento. Si no las usa en una colección, desactívelas. Para obtener más información, consulte Desactivar preimágenes a nivel de colección.
Las preimágenes de documentos son compatibles con clústeres Atlas no fragmentados que ejecutan MongoDB 4.4o superior, y con clústeres Atlas fragmentados que ejecutan MongoDB 5.3 y versiones posteriores. Puede actualizar un clúster no fragmentado (con preimágenes) a un clúster fragmentado, siempre que el clúster ejecute 5.3 o versiones posteriores.
Configuraciones de activador
Campo | Descripción |
|---|---|
Auto-Resume Triggers | Si está habilitado, cuando no se encuentra el token de reanudación de este disparador en el registro de operaciones del clúster, este reanuda automáticamente el procesamiento de eventos en el siguiente evento relevante del flujo de cambios. El disparador no activará ningún evento del flujo de cambios desde que se suspendió el disparador hasta que reanude su ejecución. |
Event Ordering | Si está habilitado, los eventos de activación se procesan en el orden en que ocurren. Si está deshabilitado, los eventos se pueden procesar en paralelo, lo cual es más rápido cuando ocurren muchos eventos simultáneamente. Si la ordenación de eventos está habilitada, este disparador se ejecutará secuencialmente según las marcas de tiempo de los eventos de cambio. Si está deshabilitada, este disparador se ejecutará de forma independiente. TipOptimización del rendimientoMejore el rendimiento de los disparadores que responden a operaciones masivas de la base de datos deshabilitando la ordenación de eventos. Más información. |
Skip Events On Re-Enable | Deshabilitado por defecto. Si está habilitado, no se procesarán los eventos de cambio que se hayan producido mientras este disparador estaba deshabilitado. |
Tipo de evento
En la sección, elige la Event Type acción que se realiza cuando se activa el disparador. Puedes elegir entre ejecutar una función o usar AWS EventBridge.
Avanzada
Dentro de la Advanced sección, están disponibles las siguientes opciones de configuración opcionales:
Campo | Descripción | ||||||||
|---|---|---|---|---|---|---|---|---|---|
Project Expression | Una expresión $project que selecciona un subconjunto de campos de cada evento en el flujo de cambios. Puede usarla para optimizar la ejecución del disparador. La expresión es un objeto que asigna el nombre de los campos del evento de cambio a
| ||||||||
Match Expression | Un documento de expresión $match que App Services utiliza para filtrar los eventos de cambio que activan el disparador. El disparador evalúa todos los objetos de evento de cambio que recibe con esta expresión de coincidencia y solo se ejecuta si la expresión da como NotaUsar notación de puntos para campos incrustadosMongoDB realiza una coincidencia de igualdad completa para los documentos incrustados en una expresión de coincidencia. Si desea que un campo específico coincida con un documento incrustado, consulte el campo directamente mediante la notación de puntos. Para más información, consulte Consulta en documentos incrustados en el manual del servidor MongoDB. TipOptimización del rendimientoLimite el número de campos que procesa el disparador mediante una expresión $match. Más información. | ||||||||
Maximum Throughput | Si la fuente de datos vinculada es un servidor dedicado (nivel M10+), puede aumentar el rendimiento máximo más allá de los procesos concurrentes predeterminados 10,000. ImportantePara habilitar el máximo rendimiento, debe deshabilitar el ordenamiento de eventos. Antes de aumentar el rendimiento máximo, considere si uno o más de sus activadores están llamando a una API externa con límite de velocidad. Aumentar la velocidad de activación podría resultar en la superación de dichos límites. Aumentar el rendimiento también puede agregar una mayor carga de trabajo, lo que afecta el rendimiento general del clúster. |
Cambiar tipos de eventos
Los eventos de cambio de base de datos representan cambios individuales en una colección específica de su clúster MongoDB Atlas vinculado.
Cada evento de base de datos tiene el mismo tipo de operación y estructura que el objeto de evento de cambio emitido por el flujo de cambios subyacente. Los eventos de cambio tienen los siguientes tipos de operación:
Tipo de operación | Descripción |
|---|---|
Insertar documento (todos los tipos de activadores) | Representa un nuevo documento agregado a la colección. |
Actualizar documento (todos los tipos de activadores) | Representa un cambio en un documento existente en la colección. |
Eliminar documento (todos los tipos de activadores) | Representa un documento eliminado de la colección. |
Reemplazar documento (todos los tipos de activadores) | Representa un nuevo documento que reemplazó un documento de la colección. |
Crear colección (solo tipos de desencadenadores de base de datos e implementación) | Representa la creación de una nueva colección. |
Modificar colección (solo tipos de desencadenadores de base de datos e implementación) | Representa la colección de modificación. |
Cambiar el nombre de la colección (solo para tipos de desencadenadores de base de datos e implementación) | Representa una colección que está siendo renombrada. |
Recopilación de caídas (solo tipos de desencadenadores de base de datos e implementación) | Representa una colección que se está eliminando. |
Recopilación de fragmentos (solo tipos de desencadenadores de base de datos e implementación) | Representa una colección que cambia de no fragmentada a fragmentada. |
Recopilación de fragmentos (solo tipos de desencadenadores de base de datos e implementación) | Representa un cambio en el particionado de una colección. |
Refinar clave de fragmento de colección (solo tipos de desencadenadores de base de datos e implementación) | Representa un cambio en la clave de fragmento de una colección. |
Crear índices (solo tipos de desencadenadores de base de datos e implementación) | Representa la creación de un nuevo índice. |
Índices de eliminación (solo tipos de desencadenadores de base de datos e implementación) | Representa un índice que se está eliminando. |
Base de datos de Drop (solo tipo de activador de implementación) | Representa una base de datos que se está eliminando. |
Los objetos de evento de cambio de base de datos tienen la siguiente forma general:
{ _id : <ObjectId>, "operationType": <string>, "fullDocument": <document>, "fullDocumentBeforeChange": <document>, "ns": { "db" : <string>, "coll" : <string> }, "documentKey": { "_id": <ObjectId> }, "updateDescription": <document>, "clusterTime": <Timestamp> }
Ejemplo de activador de base de datos
Una tienda online quiere notificar a sus clientes cada vez que uno de sus pedidos cambia de ubicación. Registra cada pedido en la colección store.orders como un documento similar al siguiente:
{ _id: ObjectId("59cf1860a95168b8f685e378"), customerId: ObjectId("59cf17e1a95168b8f685e377"), orderDate: ISODate("2018-06-26T16:20:42.313Z"), shipDate: ISODate("2018-06-27T08:20:23.311Z"), orderContents: [ { qty: 1, name: "Earl Grey Tea Bags - 100ct", price: NumberDecimal("10.99") } ], shippingLocation: [ { location: "Memphis", time: ISODate("2018-06-27T18:22:33.243Z") }, ] }
Para automatizar este proceso, la tienda crea un disparador de base de datos que detecta eventos de cambio de actualización en la store.orders colección. Cuando el disparador detecta un evento de actualización, pasa el objeto de evento de cambio a su función asociada,. textShippingUpdate La función comprueba si el evento de cambio ha cambiado el shippingLocation campo y, si se ha actualizado, envía un mensaje de texto al cliente con la nueva ubicación del pedido.
{ "type": "DATABASE", "name": "shippingLocationUpdater", "function_name": "textShippingUpdate", "config": { "service_name": "mongodb-atlas", "database": "store", "collection": "orders", "operation_types": ["UPDATE"], "unordered": false, "full_document": true, "match": {} }, "disabled": false }
exports = async function (changeEvent) { // Destructure out fields from the change stream event object const { updateDescription, fullDocument } = changeEvent; // Check if the shippingLocation field was updated const updatedFields = Object.keys(updateDescription.updatedFields); const isNewLocation = updatedFields.some(field => field.match(/shippingLocation/) ); // If the location changed, text the customer the updated location. if (isNewLocation) { const { customerId, shippingLocation } = fullDocument; const mongodb = context.services.get("mongodb-atlas"); const customers = mongodb.db("store").collection("customers"); const { location } = shippingLocation.pop(); const customer = await customers.findOne({ _id: customerId }); const twilio = require('twilio')( // Your Account SID and Auth Token from the Twilio console: context.values.get("TwilioAccountSID"), context.values.get("TwilioAuthToken"), ); await twilio.messages.create({ To: customer.phoneNumber, From: context.values.get("ourPhoneNumber"), Body: `Your order has moved! The new location is ${location}.` }) } };
Disparadores suspendidos
Los disparadores de base de datos pueden entrar en estado suspendido en respuesta a un evento que impide que el flujo de cambios del disparador continúe. Los eventos que pueden suspender un disparador incluyen:
invalidar eventos
dropDatabaserenameCollectioncomo, o aquellos causados por una interrupción de la red.el token de reanudación requerido para reanudar el flujo de cambios ya no está en el oplogdel clúster. Los registros de la aplicación se refieren a esto como un error
ChangeStreamHistoryLost.
En caso de que un disparador se suspenda o falle, Atlas App Services envía un correo electrónico al propietario del proyecto para alertarlo sobre el problema.
Reanudar automáticamente un disparador suspendido
Puede configurar un disparador para que se reanude automáticamente si se suspendió porque el token de reanudación ya no está en el registro de operaciones. El disparador no procesa ningún evento de flujo de cambios perdido entre la pérdida del token de reanudación y la finalización del proceso de reanudación.
Al crear o actualizar un disparador de base de datos en la interfaz de usuario de App Services, navegue a la página de configuración del disparador que desea reanudar automáticamente si se suspende.
En la sección Advanced (Optional), seleccione Auto-Resume Triggers.
Guarda e implementa los cambios.
Al crear o actualizar un activador de base de datos con la CLI de Realm, cree o navegue hasta el archivo de configuración del activador que desea reanudar automáticamente si se suspende.
En el archivo de configuración del disparador, incluya lo siguiente:
{ "name": "<Trigger Name>", "type": "DATABASE", "config": { "tolerate_resume_errors": true, // ...rest of Database Trigger configuration }, // ...rest of Trigger general configuration }
Implemente los cambios con el siguiente comando:
appservices push --remote=<App ID>
Reanudar manualmente un disparador suspendido
Al reanudar manualmente un disparador suspendido, la aplicación intenta reanudarlo en el siguiente evento de flujo de cambios después de que se detuviera. Si el token de reanudación ya no está en el registro de operaciones del clúster, el disparador debe iniciarse sin un token de reanudación. Esto significa que el disparador comienza a escuchar nuevos eventos, pero no procesa los eventos pasados que se hayan perdido.
Puede ajustar el tamaño del registro de operaciones para conservar el token de reanudación durante más tiempo después de una suspensión escalando su clúster Atlas. Mantenga un tamaño del registro de operaciones varias veces mayor que el rendimiento máximo del registro de operaciones de su clúster (GB/hora) para reducir el riesgo de que el token de reanudación de un disparador suspendido se elimine del registro de operaciones antes de que este se ejecute. Consulte el rendimiento del registro de operaciones de su clúster en el gráfico GB/hora del registro de operaciones en las métricas del clúster Atlas.
Puede intentar reiniciar un disparador suspendido desde la interfaz de usuario de App Services o importando un directorio de aplicaciones con la CLI de App Services.
Reiniciar el disparador
Haga clic Restart en en la Actions columna del disparador. Puede reiniciar el disparador con un token de reanudación de flujo de cambios o abrir uno nuevo. Indique si desea usar un token de reanudación y haga clic Resume Database Trigger en.
Nota
Tokens de reanudación
Si usa un token de reanudación, App Services intenta reanudar el flujo de cambios subyacente del disparador en el evento inmediatamente posterior al último evento de cambio que procesó. Si lo logra, el disparador procesa cualquier evento ocurrido mientras estaba suspendido. Si no usa un token de reanudación, el disparador comienza a detectar nuevos eventos, pero no se activará para ninguno de los eventos ocurridos mientras estaba suspendido.
Verificar que exista el archivo de configuración del disparador
Si exportó una nueva copia de su aplicación, esta ya debería incluir un archivo de configuración actualizado para el disparador suspendido. Puede confirmar la existencia del archivo de configuración buscando en el /triggers directorio un archivo de configuración del disparador con el mismo nombre que el disparador.
Informe de tiempo de activación
La lista de activadores en la interfaz de usuario de Atlas App Services muestra tres marcas de tiempo:
Última modificación
Este es el momento en el que se creó o modificó por última vez el disparador.
Último latido del corazón
Atlas App Services registra la última vez que se ejecutó un disparador. Si el disparador no envía ningún evento, el servidor envía un latido para garantizar que su token de reanudación se mantenga actualizado. El evento más reciente se muestra como Latest Heartbeat.
Hora del último clúster procesado
Atlas App Services también registra el Last Cluster Time Processed, que corresponde a la última vez que el flujo de cambios que respalda un disparador emitió un evento. Será anterior a Latest Heartbeat si no ha habido eventos desde el latido más reciente.
Optimización del rendimiento
Deshabilitar el orden de eventos para operaciones de ráfaga
Considere deshabilitar el orden de eventos si su disparador se activa en una colección que recibe ráfagas cortas de eventos (por ejemplo, insertar datos como parte de un trabajo por lotes diario).
Los disparadores ordenados esperan para ejecutar una función para un evento específico hasta que las funciones de eventos anteriores hayan terminado de ejecutarse. En consecuencia, su velocidad está limitada por el tiempo de ejecución de cada función secuencial. Esto puede causar un retraso significativo entre la aparición del evento de base de datos en el flujo de cambios y su activación. En casos extremos, los eventos de base de datos pueden desaparecer del registro de operaciones antes de que un disparador ordenado de larga duración los procese.
Los activadores no ordenados ejecutan funciones en paralelo si es posible, lo que puede ser significativamente más rápido (dependiendo de su caso de uso), pero no garantiza que se produzcan múltiples ejecuciones de una función activadora en el orden del evento.
Desactivar preimágenes a nivel de colección
Las preimágenes de documento requieren que el clúster registre datos adicionales sobre cada operación en una colección. Una vez habilitadas las preimágenes para cualquier disparador de una colección, el clúster almacena preimágenes para cada operación en la colección.
El espacio de almacenamiento adicional y la sobrecarga computacional pueden degradar el rendimiento del disparador dependiendo de la configuración del clúster.
Para evitar la sobrecarga de almacenamiento y procesamiento de las preimágenes, debe deshabilitarlas para toda la colección subyacente de MongoDB. Esta configuración es independiente de la configuración de preimágenes de cualquier disparador individual.
Si desactivas los preimágenes a nivel de colección, entonces ningún activador activo en esa colección puede usar preimágenes. Sin embargo, si borras o desactivas todos los activadores de preimágenes en una colección, entonces también puedes desactivar los preimágenes a nivel de colección.
Para saber cómo hacerlo,consulte Deshabilitar preimágenes para una colección.
Utilice expresiones de coincidencia para limitar las invocaciones de activadores
Puede limitar el número de invocaciones del disparador especificando una expresión $match en el Match Expression campo. App Services evalúa la expresión de coincidencia con el documento del evento de cambio e invoca el disparador solo si la expresión se evalúa como verdadera para el evento de cambio dado.
La expresión de coincidencia es un documento JSON que especifica las condiciones de consulta utilizando la sintaxis de consulta de lectura de MongoDB.
Recomendamos usar expresiones de coincidencia solo cuando el volumen de eventos de disparo represente un problema de rendimiento considerable. Hasta entonces, reciba todos los eventos y gestione cada uno individualmente en el código de la función de disparo.
La forma exacta del documento de evento de cambio depende del evento que provocó la activación del disparador. Para más detalles, consulte la referencia de cada tipo de evento:
Ejemplo
La siguiente expresión de coincidencia permite que el disparador se active solo si el objeto de evento de cambio especifica que el campo status en un documento cambió.
updateDescription es un campo del objeto de evento de actualización.
{ "updateDescription.updatedFields.status": { "$exists": true } }
La siguiente expresión de coincidencia permite que el disparador se active solo cuando el needsTriggerResponse campo de un documento true es. El fullDocument campo de los eventos de inserción, actualización y reemplazo representa un documento después de la operación dada. Para recibir el fullDocument campo, debe habilitar Full Document en la configuración del disparador.
{ "fullDocument.needsTriggerResponse": true }
Prueba de expresiones de coincidencia
El siguiente procedimiento muestra una forma de probar si tu expresión de coincidencia funciona como se espera:
Descargue MongoDB Shell (mongosh) y úselo para conectarse a su clúster.
Reemplace
DB_NAMEcon el nombre de su base de datos,COLLECTION_NAMEcon el nombre de su colección yYOUR_MATCH_EXPRESSIONcon la expresión de coincidencia que desea probar, pegue lo siguiente en mongosh para abrir un flujo de cambios en una colección existente:db.getSiblingDB(DB_NAME).COLLECTION_NAME.watch([{$match: YOUR_MATCH_EXPRESSION}]) while (!watchCursor.isClosed()) { if (watchCursor.hasNext()) { print(tojson(watchCursor.next())); } } En otra ventana de terminal, use mongosh para realizar cambios en algunos documentos de prueba en la colección.
Observe lo que el flujo de cambio filtra dentro y fuera.
Utilice expresiones de proyecto para reducir el tamaño de los datos de entrada
En el Project Expression campo, limite la cantidad de campos que procesa el disparador mediante una expresión $project.
Nota
El proyecto es solo inclusivo
Al usar activadores, una expresión de proyección es solo inclusiva. El proyecto no admite la combinación de inclusiones y exclusiones. La expresión del proyecto debe ser inclusiva, ya que los activadores requieren que se operationType incluya.
Si deseas excluir un solo campo, la expresión de proyección debe incluir todos los campos excepto el que deseas excluir. Solo puede excluir explícitamente _id, que se incluye por defecto.
Ejemplo
Un disparador se configura con lo siguiente Project Expression:
{ "_id": 0, "operationType": 1, "updateDescription.updatedFields.status": 1 }
El objeto de evento de cambio que App Services pasa a la función de activación solo incluye los campos especificados en la proyección, como en el siguiente ejemplo:
{ "operationType": "update", "updateDescription": { "updatedFields": { "status": "InProgress" } } }
Ejemplos adicionales
Para obtener ejemplos adicionales de activadores integrados en una aplicación de servicios de aplicaciones, consulte los activadores de ejemplo en Github.