Compartir vía


Enlace de desencadenador de Azure Database for MySQL para Azure Functions

Los enlaces de desencadenador de Azure Database for MySQL supervisan la tabla de usuario de los cambios (inserciones y actualizaciones) e invocan la función con datos de fila actualizados.

Los enlaces de desencadenador de Azure Database for MySQL usan az_func_updated_at datos de columna y para supervisar la tabla de usuario para ver los cambios. Por lo tanto, debe modificar la estructura de la tabla para permitir el seguimiento de cambios en la tabla MySQL antes de usar la compatibilidad con el desencadenador. Puede habilitar el seguimiento de cambios en una tabla a través de la consulta siguiente. Por ejemplo, habilite en la Products tabla:

ALTER TABLE Products
ADD az_func_updated_at TIMESTAMP DEFAULT 
CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP;

La tabla de concesiones contiene todas las columnas que corresponden a la clave principal de la tabla de usuario y tres columnas más: az_func_AttemptCount, az_func_LeaseExpirationTimey az_func_SyncCompletedTime. Si alguna de las columnas de clave principal tiene el mismo nombre, el resultado es un mensaje de error que muestra conflictos. En este caso, se debe cambiar el nombre de las columnas de clave principal enumeradas para que el desencadenador funcione.

Introducción a la funcionalidad

Cuando se inicia la función de desencadenador, inicia dos bucles independientes: el bucle de sondeo de cambios y el bucle de renovación de concesión. Estos bucles se ejecutan continuamente hasta que se detiene la función.

El enlace de desencadenador de Azure Database for MySQL usa el bucle de sondeo para comprobar si hay cambios. El bucle de sondeo desencadena la función de usuario cuando detecta cambios. En un nivel alto, el bucle tiene el siguiente aspecto:

while (true) {
    1. Get list of changes on table - up to a maximum number controlled by the MySql_Trigger_MaxBatchSize setting
    2. Trigger function with list of changes
    3. Wait for delay controlled by MySql_Trigger_PollingIntervalMs setting
}

Los cambios se procesan en el orden en que se realizan. Los cambios más antiguos se procesan primero. Tenga en cuenta estos puntos sobre el procesamiento de cambios:

  • Si se producen cambios en varias filas a la vez, el orden exacto en el que se envían a la función se basa en el orden ascendente de la az_func_updated_at columna y las columnas de clave principal.
  • Los cambios se procesan por lotes para una fila. Si se producen varios cambios en una fila entre cada iteración del bucle, solo se considera la entrada de cambio más reciente que existe para esa fila.

Nota:

Actualmente, las identidades administradas no se admiten para las conexiones entre Azure Functions y Azure Database for MySQL.

Ejemplo de uso

Hay más ejemplos para el desencadenador de Azure Database for MySQL disponible en el repositorio de GitHub.

En este ejemplo se hace referencia a una clase Product y una tabla de base de datos correspondiente:

namespace AzureMySqlSamples.Common
{
    public class Product
    {
        public int? ProductId { get; set; }

        public string Name { get; set; }

        public int Cost { get; set; }

        public override bool Equals(object obj)
        {
            if (obj is Product)
            {
                var that = obj as Product;
                return this.ProductId == that.ProductId && this.Name == that.Name && this.Cost == that.Cost;
            }
            return false;
        }
    }
DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Para habilitar el seguimiento de cambios en la base de datos, agregue una columna a la tabla:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

El desencadenador de Azure Database for MySQL se enlaza a IReadOnlyList<MySqlChange<T>>, que enumera MySqlChange los objetos . Cada objeto tiene dos propiedades:

  • Item: elemento que se cambió. El tipo del elemento debe seguir el esquema de la tabla, como se muestra en la ToDoItem clase .
  • Operation: un valor de la MySqlChangeOperation enumeración. El valor posible es Update para inserciones y actualizaciones.

En el ejemplo siguiente se muestra una función de C# que se invoca cuando se producen cambios en la Product tabla:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.MySql;
using Microsoft.Extensions.Logging;
using AzureMySqlSamples.Common;

namespace AzureMySqlSamples.TriggerBindingSamples
{
        private static readonly Action<ILogger, string, Exception> _loggerMessage = LoggerMessage.Define<string>(LogLevel.Information, eventId: new EventId(0, "INFO"), formatString: "{Message}");

        [Function(nameof(ProductsTrigger))]
        public static void Run(
            [MySqlTrigger("Products", "MySqlConnectionString")]
            IReadOnlyList<MySqlChange<Product>> changes, FunctionContext context)
        {
            ILogger logger = context.GetLogger("ProductsTrigger");
            // The output is used to inspect the trigger binding parameter in test methods.
            foreach (MySqlChange<Product> change in changes)
            {
                Product product = change.Item;
                _loggerMessage(logger, $"Change operation: {change.Operation}", null);
                _loggerMessage(logger, $"Product Id: {product.ProductId}, Name: {product.Name}, Cost: {product.Cost}", null);
            }
        }
}

Ejemplo de uso

Hay más ejemplos para el desencadenador de Azure Database for MySQL disponible en el repositorio de GitHub.

En el ejemplo se hace referencia a una Product clase, una MySqlChangeProduct clase, una MySqlChangeOperation enumeración y una tabla de base de datos correspondiente.

En un archivo independiente denominado Product.java:

package com.function.Common;

import com.fasterxml.jackson.annotation.JsonProperty;

public class Product {
    @JsonProperty("ProductId")
    private int ProductId;
    @JsonProperty("Name")
    private String Name;
    @JsonProperty("Cost")
    private int Cost;

    public Product() {
    }

    public Product(int productId, String name, int cost) {
        ProductId = productId;
        Name = name;
        Cost = cost;
    }
}

En un archivo independiente denominado MySqlChangeProduct.java:

package com.function.Common;

public class MySqlChangeProduct {
    private MySqlChangeOperation Operation;
    private Product Item;

    public MySqlChangeProduct() {
    }

    public MySqlChangeProduct(MySqlChangeOperation operation, Product item) {
        this.Operation = operation;
        this.Item = item;
    }
}

En un archivo independiente denominado MySqlChangeOperation.java:

package com.function.Common;

import com.google.gson.annotations.SerializedName;

public enum MySqlChangeOperation {
    @SerializedName("0")
    Update
}
DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Para habilitar el seguimiento de cambios en la base de datos, agregue la siguiente columna a la tabla:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

El desencadenador de Azure Database for MySQL se enlaza a MySqlChangeProduct[], que es una matriz de MySqlChangeProduct objetos . Cada objeto tiene dos propiedades:

  • item: elemento que se cambió. El tipo del elemento debe seguir el esquema de la tabla, como se muestra en la Product clase .
  • operation: un valor de la MySqlChangeOperation enumeración. El valor posible es Update para inserciones y actualizaciones.

En el ejemplo siguiente se muestra una función de Java que se invoca cuando se producen cambios en la Product tabla:

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 */

package com.function;

import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.mysql.annotation.MySqlTrigger;
import com.function.Common.MySqlChangeProduct;
import com.google.gson.Gson;

import java.util.logging.Level;

public class ProductsTrigger {
    @FunctionName("ProductsTrigger")
    public void run(
            @MySqlTrigger(
                name = "changes",
                tableName = "Products",
                connectionStringSetting = "MySqlConnectionString")
                MySqlChangeProduct[] changes,
            ExecutionContext context) {

        context.getLogger().log(Level.INFO, "MySql Changes: " + new Gson().toJson(changes));
    }
}

Ejemplo de uso

Hay más ejemplos para el desencadenador de Azure Database for MySQL disponible en el repositorio de GitHub.

El ejemplo hace referencia a una tabla de base de datos Product:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Para habilitar el seguimiento de cambios en la base de datos, agregue una columna a la tabla:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

El desencadenador de Azure Database for MySQL se enlaza a Product, que enumera los objetos . Cada objeto tiene dos propiedades:

  • item: elemento que se cambió. La estructura del elemento sigue el esquema de la tabla.
  • operation: el valor posible es Update para inserciones y actualizaciones.

En el ejemplo siguiente se muestra una función de PowerShell que se invoca cuando se producen cambios en la Product tabla.

En el siguiente ejemplo se muestran los datos de enlace del archivo function.json:

{
    "bindings": [
      {
        "name": "changes",
        "type": "mysqlTrigger",
        "direction": "in",
        "tableName": "Products",
        "connectionStringSetting": "MySqlConnectionString"
      }
    ],
    "disabled": false
  }

En la sección Configuración se explican estas propiedades.

El ejemplo siguiente es código de PowerShell de ejemplo para la función en el archivo run.ps1:

using namespace System.Net

param($changes)
# The output is used to inspect the trigger binding parameter in test methods.
# Use -Compress to remove new lines and spaces for testing purposes.
$changesJson = $changes | ConvertTo-Json -Compress
Write-Host "MySql Changes: $changesJson"

Ejemplo de uso

Hay más ejemplos para el desencadenador de Azure Database for MySQL disponible en el repositorio de GitHub.

El ejemplo hace referencia a una tabla de base de datos Product:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Para habilitar el seguimiento de cambios en la base de datos, agregue una columna a la tabla:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

El desencadenador de Azure Database for MySQL se enlaza a Changes, que es una matriz de objetos . Cada objeto tiene dos propiedades:

  • item: elemento que se cambió. La estructura del elemento sigue el esquema de la tabla.
  • operation: el valor posible es Update para inserciones y actualizaciones.

En el ejemplo siguiente se muestra una función de JavaScript que se invoca cuando se producen cambios en la Product tabla.

En el siguiente ejemplo se muestran los datos de enlace del archivo function.json:

{
    "bindings": [
      {
        "name": "changes",
        "type": "mysqlTrigger",
        "direction": "in",
        "tableName": "Products",
        "connectionStringSetting": "MySqlConnectionString",
      }
    ],
    "disabled": false
  }

En la sección Configuración se explican estas propiedades.

En el ejemplo siguiente se muestra código JavaScript de ejemplo para la función del index.js archivo:

module.exports = async function (context, changes) {
    context.log(`MySql Changes: ${JSON.stringify(changes)}`)
}

Ejemplo de uso

Hay más ejemplos para el desencadenador de Azure Database for MySQL disponible en el repositorio de GitHub.

El ejemplo hace referencia a una tabla de base de datos Product:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Para habilitar el seguimiento de cambios en la base de datos, agregue una columna a la tabla:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Nota:

Debe usar la versión 1.22.0b4 de Azure Functions para Python.

El desencadenador de Azure Database for MySQL se enlaza a una variable denominada Product, que enumera los objetos. Cada objeto tiene dos propiedades:

  • item: elemento que se cambió. La estructura del elemento sigue el esquema de la tabla.
  • operation: el valor posible es Update para inserciones y actualizaciones.

En el ejemplo siguiente se muestra una función de Python que se invoca cuando se producen cambios en la Product tabla.

El ejemplo siguiente es código de Python de ejemplo para el archivo function_app.py:

import json
import logging
import azure.functions as func

app = func.FunctionApp()

# The function is triggered when a change (insert, update)
# is made to the Products table.
@app.function_name(name="ProductsTrigger")
@app.mysql_trigger(arg_name="products",
table_name="Products",
connection_string_setting="MySqlConnectionString")

def products_trigger(products: str) -> None:
logging.info("MySQL Changes: %s", json.loads(products))

Atributos

Propiedad de atributo Descripción
TableName Necesario. Nombre de la tabla que supervisa el desencadenador.
ConnectionStringSetting Necesario. Nombre de una configuración de aplicación que contiene la cadena de conexión de la base de datos que contiene la tabla supervisada para los cambios. El nombre de la configuración de la cadena de conexión corresponde a la configuración de la aplicación (en local.settings.json para el desarrollo local) que contiene la cadena de conexión a Azure Database for MySQL.
LeasesTableName Opcional. Nombre de la tabla para almacenar concesiones. Si no se especifica, el nombre es Leases_{FunctionId}_{TableId}.

anotaciones

En la biblioteca en tiempo de ejecución de funciones de Java, use la @MySQLTrigger anotación en parámetros cuyos valores provendrían de Azure Database for MySQL. Esta anotación admite los siguientes elementos:

Elemento Descripción
name Necesario. Nombre del parámetro al que enlaza el desencadenador.
tableName Necesario. Nombre de la tabla que supervisa el desencadenador.
connectionStringSetting Necesario. Nombre de una configuración de aplicación que contiene la cadena de conexión de la base de datos que contiene la tabla supervisada para los cambios. El nombre de la configuración de la cadena de conexión corresponde a la configuración de la aplicación (en local.settings.json para el desarrollo local) que contiene la cadena de conexión a Azure Database for MySQL.
LeasesTableName Opcional. Nombre de la tabla para almacenar concesiones. Si no se especifica, el nombre es Leases_{FunctionId}_{TableId}.

Configuración

En la tabla siguiente se explican las propiedades de configuración de enlace establecidas en el archivo function.json:

Propiedad Descripción
name Necesario. Nombre del parámetro al que enlaza el desencadenador.
type Necesario. Se debe establecer en MysqlTrigger.
direction Necesario. Se debe establecer en in.
tableName Necesario. Nombre de la tabla que supervisa el desencadenador.
connectionStringSetting Necesario. Nombre de una configuración de aplicación que contiene la cadena de conexión de la base de datos que contiene la tabla supervisada para los cambios. El nombre de la configuración de la cadena de conexión corresponde a la configuración de la aplicación (en local.settings.json para el desarrollo local) que contiene la cadena de conexión a Azure Database for MySQL.
LeasesTableName Opcional. Nombre de la tabla para almacenar concesiones. Si no se especifica, el nombre es Leases_{FunctionId}_{TableId}.

Configuración opcional

Puede configurar las siguientes opciones opcionales para el desencadenador de Azure Database for MySQL para el desarrollo local o para las implementaciones en la nube.

host.json

En esta sección se describen las opciones de configuración disponibles para este enlace en la versión 2.x y posteriores. La configuración del archivo host.json se aplica a todas las funciones de una instancia de la aplicación de funciones. Para más información sobre las opciones de configuración de la aplicación de funciones, consulte host.json referencia para Azure Functions.

Configuración Valor predeterminado Descripción
MaxBatchSize 100 Número máximo de cambios procesados con cada iteración del bucle desencadenador antes de enviarlos a la función desencadenada.
PollingIntervalMs 1000 El retraso en milisegundos entre el procesamiento de cada lote de cambios. (1000 ms es de 1 segundo).
MaxChangesPerWorker 1000 Límite superior del número de cambios pendientes en la tabla de usuarios que se permiten por trabajo de aplicación. Si el recuento de cambios supera este límite, podría dar lugar a un escalado horizontal. La configuración solo se aplica a las aplicaciones de funciones de Azure con el escalado controlado por tiempo de ejecución habilitado.

Archivo de host.json de ejemplo

Este es un ejemplo host.json archivo con la configuración opcional:

{
  "version": "2.0",
  "extensions": {
      "MySql": {
        "MaxBatchSize": 300,
        "PollingIntervalMs": 1000,
        "MaxChangesPerWorker": 100
      }
  },
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    },
    "logLevel": {
      "default": "Trace"
    }
  }
}

local.setting.json

El archivo local.settings.json almacena la configuración y la configuración de la aplicación que usan las herramientas de desarrollo locales. La configuración del archivo local.settings.json solo se usa al ejecutar el proyecto de forma local. Al publicar el proyecto en Azure, asegúrese de agregar también cualquier configuración necesaria a la configuración de la aplicación para la aplicación de funciones.

Importante

Dado que el archivo local.settings.json puede contener secretos, como cadenas de conexión, nunca debe almacenarlo en un repositorio remoto. Las herramientas que admiten Azure Functions proporcionan maneras de sincronizar la configuración en el archivo local.settings.json con la configuración de la aplicación en la aplicación de funciones en la que se implementa el proyecto.

Configuración Valor predeterminado Descripción
MySql_Trigger_BatchSize 100 Número máximo de cambios procesados con cada iteración del bucle desencadenador antes de enviarlos a la función desencadenada.
MySql_Trigger_PollingIntervalMs 1000 El retraso en milisegundos entre el procesamiento de cada lote de cambios. (1000 ms es de 1 segundo).
MySql_Trigger_MaxChangesPerWorker 1000 Límite superior del número de cambios pendientes en la tabla de usuarios que se permiten por trabajo de aplicación. Si el recuento de cambios supera este límite, podría dar lugar a un escalado horizontal. La configuración solo se aplica a las aplicaciones de funciones de Azure con el escalado controlado por tiempo de ejecución habilitado.

Archivo de local.settings.json de ejemplo

Este es un ejemplo local.settings.json archivo con la configuración opcional:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "MySqlConnectionString": "",
    "MySql_Trigger_MaxBatchSize": 300,
    "MySql_Trigger_PollingIntervalMs": 1000,
    "MySql_Trigger_MaxChangesPerWorker": 100
  }
}

Configuración del seguimiento de cambios (requerido)

La configuración del seguimiento de cambios para su uso con el desencadenador de Azure Database for MySQL requiere que agregue una columna en una tabla mediante una función . Puede completar estos pasos desde cualquier herramienta mySQL que admita la ejecución de consultas, como Visual Studio Code o Azure Data Studio.

Los enlaces de desencadenador de Azure Database for MySQL usan az_func_updated_at datos de columna y para supervisar la tabla de usuario para ver los cambios. Por lo tanto, debe modificar la estructura de la tabla para permitir el seguimiento de cambios en la tabla MySQL antes de usar la compatibilidad con el desencadenador. Puede habilitar el seguimiento de cambios en una tabla a través de la consulta siguiente. Por ejemplo, habilite en la Products tabla:

ALTER TABLE Products;
ADD az_func_updated_at 
TIMESTAMP DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

La tabla para concesiones contiene todas las columnas que corresponden a la clave principal de la tabla de usuario y dos columnas más: az_func_AttemptCount y az_func_LeaseExpirationTime. Si alguna de las columnas de clave principal tiene el mismo nombre, el resultado es un mensaje de error que muestra conflictos. En este caso, se debe cambiar el nombre de las columnas de clave principal enumeradas para que el desencadenador funcione.

Activación del escalado controlado por tiempo de ejecución

Opcionalmente, las funciones pueden escalar automáticamente en función del número de cambios pendientes de procesarse en la tabla de usuario. Para permitir que las funciones se escalen correctamente en el plan Premium cuando use desencadenadores de Azure Database for MySQL, debe habilitar la supervisión de escalado en tiempo de ejecución.

  1. En Azure Portal, en la aplicación de funciones, seleccione Configuración.

  2. En la pestaña Configuración del entorno de ejecución de la función, en Supervisión de escalado en tiempo de ejecución, seleccione Activado.

    Captura de pantalla del área de Azure Portal para habilitar el escalado en tiempo de ejecución.

Compatibilidad con los reintentos

Reintentos de inicio

Si se produce una excepción durante el inicio, el tiempo de ejecución del host intenta reiniciar automáticamente el agente de escucha del desencadenador con una estrategia de retroceso exponencial. Estos reintentos continúan hasta que el agente de escucha se inicia correctamente o se cancela el inicio.

Reintentos de excepción de función

Si se produce una excepción en la función de usuario durante el procesamiento de cambios, el lote de filas que se está procesando se vuelve a intentar en 60 segundos. Otros cambios se procesan como normales durante este tiempo, pero las filas del lote que provocaron la excepción se omiten hasta que transcurre el período de tiempo de espera.

Si se produce un error en la ejecución de la función cinco veces consecutivas para una fila determinada, esa fila se omite para todos los cambios futuros. Dado que las filas de un lote no son deterministas, es posible que las filas de un lote con errores terminen en lotes diferentes en invocaciones posteriores. Este comportamiento significa que no todas las filas del lote con errores se omiten necesariamente. Si otras filas del lote provocaron la excepción, es posible que las filas "buenas" terminen en un lote diferente que no produzca un error en futuras invocaciones.