Los activadores de base de datos te permite ejecutar lógica del lado del servidor cada vez que ocurre un cambio en la base de datos en un clúster enlazado de MongoDB Atlas. Puedes configurar triggers en colecciones individuales, en bases de datos completas y en un clúster completo.
A diferencia de los activadores de datos SQL, que se ejecutan en el servidor de la base de datos, los activadores se ejecutan en una capa de cómputo sin servidor que escala de forma independiente del servidor de la base de datos. Los activadores llaman automáticamente a las Funciones Atlas y pueden reenviar eventos a controladores externos mediante 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 activadores de base de datos usan flujos de cambios de MongoDB para observar cambios en tiempo real en una colección. Un flujo de cambios es una serie de eventos de base de datos que describen cada una una operación en un documento de la colección. Tu aplicación abre un nuevo flujo de cambios por cada desencadenador 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.
You cannot define a database trigger on a serverless instance or Federated database instance because they do not support change streams.
You control which operations cause a trigger to fire as well as what happens when it does. For example, you can run a function whenever a specific field of a document is updated. The function can access the entire change event, so you always know what changed. You can also pass the change event to AWS EventBridge to handle the event outside of Atlas.
Los triggers permiten utilizar expresiones $match para filtrar eventos de cambios y expresiones $project para limitar los datos incluidos en cada evento.
Advertencia
In deployment and database level triggers, it is possible to configure triggers in a way that causes other triggers to fire, resulting in recursion. Examples include a database-level trigger writing to a collection within the same database, or a cluster-level logger or log forwarder writing logs to another database in the same cluster.
Crear un disparador de base de datos
To open the database trigger configuration screen in the App Services UI, click Triggers en el menú de navegación de la izquierda, haz clic en Create a Trigger y luego selecciona la pestaña Database junto a Trigger Type.
Configure the trigger and then click Save at the bottom of the page to add it to your current deployment draft.
To create a database trigger with the App Services CLI:
Agrega un archivo de configuración de activador de base de datos a la
triggerssubdirectory of a local application directory.Implemente el activador:
appservices push
Nota
Atlas App Services no aplica nombres de archivos específicos para los archivos de configuración de activador. Sin embargo, una vez importado, Atlas App Services renombrará cada archivo de configuración para coincidir con el nombre del activador que define, por ejemplo, mytrigger.json.
Configuración
Database triggers have the following configuration options:
Detalles del disparador
Within the Trigger Details section, you first select the Trigger Type. Set this value to Database for database triggers.
Next, you select the Watch Against, based on the level of granularity you want. Your options are:
Collection, cuando se produce un cambio en una colección específica
Database, cuando se produce un cambio en cualquier colección en una base de datos especificada
Deployment, when deployment changes occur on a specified cluster. If you select the Deployment source type, the following databases are not watched for changes:
Las bases de datos admin
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.
Según el tipo de fuente que utilices, las opciones adicionales varían. La siguiente tabla describe estas opciones.
Tipo de fuente | opciones |
|---|---|
Collection |
|
Database |
|
Deployment |
|
Tip
Preimágenes y optimización del rendimiento
Las preimágenes de eventos requieren almacenamiento adicional que puede afectar el rendimiento. Si no estás utilizando preimágenes en una colección, debes deshabilitarlas. Para obtener más información, consulta Deshabilitar preimágenes a nivel de colección.
Document preimages are supported on non-sharded Atlas clusters running MongoDB 4.4+, and on sharded Atlas clusters running MongoDB 5.3 and later. You can upgrade a non-sharded cluster (with preimages) to a sharded cluster, as long as the cluster is running 5.3 or later.
Configuraciones de activador
Campo | Descripción |
|---|---|
Auto-Resume Triggers | If enabled, when this Trigger's resume token cannot be found in the cluster's oplog, the Trigger automatically resumes processing events at the next relevant change stream event. All change stream events from when the Trigger was suspended until the Trigger resumes execution do not have the Trigger fire for them. |
Event Ordering | If enabled, trigger events are processed in the order in which they occur. If disabled, events can be processed in parallel, which is faster when many events occur at the same time. Si el ordenamiento de eventos está habilitado, se producirán múltiples ejecuciones de este activador de manera secuencial según las marcas de tiempo de los eventos de cambio. Si el ordenamiento de eventos está deshabilitado, se producirán múltiples ejecuciones de este activador de forma independiente. TipOptimización del rendimientoImprove performance for Triggers that respond to bulk database operations by disabling event ordering. Learn more. |
Skip Events On Re-Enable | Disabled by default. If enabled, any change events that occurred while this trigger was disabled will not be processed. |
Tipo de evento
Within the Event Type section, you choose what action is taken when the trigger fires. You can choose to run a function or use AWS EventBridge.
Avanzado
Within the Advanced section, the following optional configuration options are available:
Campo | Descripción | ||||||||
|---|---|---|---|---|---|---|---|---|---|
Project Expression | Una expresión $project que selecciona un subconjunto de campos de cada evento en el flujo de cambios. Puedes usar esto para optimizar la ejecución del activador. La expresión es un objeto que asigna el nombre de los campos en el evento de cambio a
| ||||||||
Match Expression | A $match expression document that App Services uses to filter which change events cause the Trigger to fire. The Trigger evaluates all change event objects that it receives against this match expression and only executes if the expression evaluates to NotaUse Dot-Notation for Embedded FieldsMongoDB 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 rendimientoLimit the number of fields that the Trigger processes by using a $match expression. Learn more. | ||||||||
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 por defecto 10,000. ImportanteTo enable maximum throughput, you must disable Event Ordering. Before increasing the maximum throughput, consider whether one or more of your triggers are calling a rate-limited external API. Increasing the trigger rate might result in exceeding those limits. Aumentar el rendimiento también puede añadir una mayor carga de trabajo, afectando 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 evento de cambio que fue emitido por el flujo de cambios subyacente. Los eventos de cambio tienen los siguientes tipos de operaciones:
Tipo de operación | Descripción |
|---|---|
Insert Document (All trigger types) | Representa un nuevo documento añadido a la colección. |
Update Document (All trigger types) | Representa un cambio en un documento existente en la colección. |
Delete Document (All trigger types) | Representa un documento eliminado de la colección. |
Replace Document (All trigger types) | Representa un nuevo documento que reemplazó a un documento en la colección. |
Create Collection (Database and Deployment trigger types only) | Representa la creación de una nueva colección. |
Modify Collection (Database and Deployment trigger types only) | Representa la colección de modificación. |
Rename Collection (Database and Deployment trigger types only) | Representa la colección que está siendo renombrada. |
Drop Collection (Database and Deployment trigger types only) | Representa una colección que se está eliminando. |
Colección de particiones (solo tipos de activador de base de datos e implementación) | Representa una colección que cambia de no fragmentada a fragmentada. |
Reshard Collection (Database and Deployment trigger types only) | Representa un cambio en el particionado de una colección. |
Refine Collection Shard Key (Database and Deployment trigger types only) | Representa un cambio en la clave de partición de una colección. |
Create Indexes (Database and Deployment trigger types only) | Representa la creación de un nuevo índice. |
Drop Indexes (Database and Deployment trigger types only) | Representa un índice que se está eliminando. |
Drop Database (Deployment trigger type only) | Representa una base de datos que se está descartando. |
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 en línea quiere notificar a sus clientes cada vez que uno de sus pedidos cambie de ubicación. Registran 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") }, ] }
To automate this process, the store creates a Database Trigger that listens for Update change events in the store.orders collection. When the trigger observes an Update event, it passes the change event object to its associated Function, textShippingUpdate. The Function checks the change event for any changes to the shippingLocation field and, if it was updated, sends a text message to the customer with the new location of the order.
{ "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 activadores de base de datos pueden entrar en un estado suspendido como respuesta a un evento que impide que el flujo de cambios del disparador continúe. Los eventos que pueden suspender un activador incluyen:
Invalidar eventos, como
dropDatabase,renameCollectiono aquellos causados por una disrupción de 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.
In the event of a suspended or failed trigger, Atlas App Services sends the project owner an email alerting them of the issue.
Reanudar automáticamente un disparador suspendido
Puedes configurar un activador para que se reanude automáticamente si se suspendió porque el token de reanudación ya no está en el oplog. El activador no procesa ningún evento perdido del flujo de cambios entre el momento en que se pierde el token de reanudación y cuando se completa el proceso de reanudación.
When creating or updating a Database Trigger in the App Services UI, navigate to the configuration page of the Trigger you want to automatically resume if suspended.
En la sección Advanced (Optional), seleccione Auto-Resume Triggers.
Guarda e implementa los cambios.
When creating or updating a Database Trigger with the Realm CLI, create or navigate to the configuration file for the Trigger you want to automatically resume if suspended.
In the Trigger's configuration file, include the following:
{ "name": "<Trigger Name>", "type": "DATABASE", "config": { "tolerate_resume_errors": true, // ...rest of Database Trigger configuration }, // ...rest of Trigger general configuration }
Deploy the changes with the following command:
appservices push --remote=<App ID>
Reanudar manualmente un activador suspendido
Cuando reanudas manualmente un activador suspendido, la aplicación intentará reanudar el activador en el siguiente evento del flujo de cambios después de que este se haya detenido. Si el token de reanudación ya no está en el oplog del clúster, el activador debe iniciarse sin un token de reanudación. Esto significa que el activador comienza a escuchar nuevos eventos, pero no procesa ningún evento pasado que se haya perdido.
Puedes ajustar el tamaño del opLog para mantener el token de reanudación por más tiempo después de una suspensión escalando el clúster de Atlas. Mantén un tamaño de oplog varias veces mayor que el pico de rendimiento de tu clúster (GB/hora) para reducir el riesgo de que el token de reanudación de un trigger suspendido desaparezca del oplog antes de que el trigger se ejecute. Mira el rendimiento del registro de operaciones de tu clúster en el Registro de operaciones GB/hora en el métricas del clúster de Atlas.
You can attempt to restart a suspended Trigger from the App Services UI or by importing an application directory with the App Services CLI.
Reiniciar el activador
Haz clic en Restart en la columna Actions del activador. Puedes elegir reiniciar el activador con un token de reanudación de flujo de cambios o abrir un nuevo flujo de cambios. Indica si se debe usar un token de reanudación y luego haz clic en Resume Database Trigger.
Nota
Tokens de reanudación
If you use a resume token, App Services attempts to resume the trigger's underlying change stream at the event immediately following the last change event it processed. If successful, the trigger processes any events that occurred while it was suspended. If you do not use a resume token, the trigger begins listening for new events but will not fire for any events that occurred while it was suspended.
Verificar que exista el archivo de configuración del activador
If you exported a new copy of your application, it should already include an up-to-date configuration file for the suspended trigger. You can confirm that the configuration file exists by looking in the /triggers directory for a trigger configuration file with the same name as the trigger.
Activar el reporte de horas
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
Atlas App Services keeps track of the last time a trigger was run. If the trigger is not sending any events, the server sends a heartbeat to ensure the trigger's resume token stays fresh. Whichever event is most recent is shown as the Latest Heartbeat.
Última vez que el clúster fue procesado
Atlas App Services also keeps track of the Last Cluster Time Processed, which is the last time the change stream backing a Trigger emitted an event. It will be older than the Latest Heartbeat if there have been no events since the most recent heartbeat.
Optimización del rendimiento
Desactivar la ordenación de eventos para operaciones de ráfaga
Consider disabling event ordering if your trigger fires on a collection that receives short bursts of events (e.g. inserting data as part of a daily batch job).
Ordered Triggers wait to execute a Function for a particular event until the Functions of previous events have finished executing. As a consequence, ordered Triggers are effectively rate-limited by the run time of each sequential Trigger function. This may cause a significant delay between the database event appearing on the change stream and the Trigger firing. In certain extreme cases, database events might fall off the oplog before a long-running ordered trigger processes them.
Las Unordered activadores 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 múltiples ejecuciones de una función de activación ocurran en el orden de los eventos.
Desactivar preimágenes a nivel de colección
Document preimages require your cluster to record additional data about each operation on a collection. Once you enable preimages for any trigger on a collection, your cluster stores preimages for every operation on the collection.
The additional storage space and compute overhead may degrade trigger performance depending on your cluster configuration.
To avoid the storage and compute overhead of preimages, you must disable preimages for the entire underlying MongoDB collection. This is a separate setting from any individual trigger's preimage setting.
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 aprender cómo, vea Deshabilitar preimágenes para una colección.
Uso de expresiones de coincidencia para limitar las llamadas de activador
Puedes limitar el número de invocaciones de activadores especificando una expresión $match en el campo Match Expression. Servicios de aplicación evalúa la expresión de coincidencia contra el documento de evento de cambio e invoca el activador 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.
We recommend only using match expressions when the volume of Trigger events measurably becomes a performance issue. Until then, receive all events and handle them individually in the Trigger function code.
The exact shape of the change event document depends on the event that caused the trigger to fire. For details, see the reference for each event type:
Ejemplo
La siguiente expresión de coincidencia permite que el activador se active solo si el objeto de evento de cambio especifica que el campo status en un documento cambió.
updateDescription es un campo de la objeto de evento de actualizar.
{ "updateDescription.updatedFields.status": { "$exists": true } }
La siguiente expresión de coincidencia permite que el activador se active solo cuando el campo needsTriggerResponse de un documento equivale a true. El campo fullDocument de los eventos insertar, actualizar y reemplazar representa un documento después de la operación dada. Para recibir el campo fullDocument, debe habilitar Full Document en su configuración del activador.
{ "fullDocument.needsTriggerResponse": true }
Expresiones de coincidencia de prueba
El siguiente procedimiento muestra una forma de probar si tu expresión de coincidencia funciona como se espera:
Download the MongoDB Shell (mongosh) and use it to connect to your cluster.
Reemplaza
DB_NAMEcon el nombre de tu base de datos,COLLECTION_NAMEcon el nombre de tu colección yYOUR_MATCH_EXPRESSIONcon la expresión de coincidencia que deseas probar. Pega 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())); } } In another terminal window, use mongosh to make changes to some test documents in the collection.
Observe lo que el flujo de cambio filtra dentro y fuera.
Usa 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
A trigger is configured with the following Project Expression:
{ "_id": 0, "operationType": 1, "updateDescription.updatedFields.status": 1 }
The change event object that App Services passes to the trigger function only includes the fields specified in the projection, as in the following example:
{ "operationType": "update", "updateDescription": { "updatedFields": { "status": "InProgress" } } }
Ejemplos adicionales
For additional examples of Triggers integrated into an App Services App, checkout the example Triggers on Github.