Condividi tramite


Associazione di trigger di Database di Azure per MySQL per Funzioni di Azure

Le associazioni di trigger di Database di Azure per MySQL monitorano la tabella utente per le modifiche (inserimenti e aggiornamenti) e richiamano la funzione con i dati di riga aggiornati.

Le associazioni di trigger di Database di Azure per MySQL usano az_func_updated_at i dati delle colonne e per monitorare la tabella utente per verificare la disponibilità di modifiche. Di conseguenza, è necessario modificare la struttura della tabella per consentire il rilevamento delle modifiche nella tabella MySQL prima di usare il supporto del trigger. È possibile abilitare il rilevamento delle modifiche in una tabella tramite la query seguente. Ad esempio, abilitarlo nella Products tabella:

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

La tabella per i lease contiene tutte le colonne che corrispondono alla chiave primaria della tabella utente e altre tre colonne: az_func_AttemptCount, az_func_LeaseExpirationTimee az_func_SyncCompletedTime. Se una delle colonne chiave primaria ha lo stesso nome, il risultato è un messaggio di errore che elenca i conflitti. In questo caso, le colonne chiave primaria elencate devono essere rinominate affinché il trigger funzioni.

Panoramica delle funzionalità

All'avvio della funzione trigger, avvia due cicli separati: il ciclo di polling delle modifiche e il ciclo di rinnovo del lease. Questi cicli vengono eseguiti continuamente fino a quando la funzione non viene arrestata.

L'associazione di trigger di Database di Azure per MySQL usa il ciclo di polling per verificare la presenza di modifiche. Il ciclo di polling attiva la funzione utente quando rileva le modifiche. A livello generale, il ciclo è simile all'esempio seguente:

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
}

Le modifiche vengono elaborate nell'ordine in cui vengono apportate. Le modifiche meno recenti vengono elaborate per prime. Considerare questi punti sull'elaborazione delle modifiche:

  • Se le modifiche si verificano in più righe contemporaneamente, l'ordine esatto in cui vengono inviate alla funzione si basa sull'ordine crescente delle colonne della colonna e della az_func_updated_at chiave primaria.
  • Le modifiche vengono raggruppate in batch per una riga. Se si verificano più modifiche in una riga tra ogni iterazione del ciclo, viene considerata solo la voce di modifica più recente esistente per tale riga.

Nota

Attualmente, le identità gestite non sono supportate per le connessioni tra Funzioni di Azure e Database di Azure per MySQL.

Esempio di utilizzo

Altri esempi per il trigger Database di Azure per MySQL sono disponibili nel repository GitHub.

L’esempio fa riferimento a una classe Product e a una tabella di database corrispondente:

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
);

Per abilitare il rilevamento delle modifiche nel database, aggiungere una colonna alla tabella:

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

Il trigger di Database di Azure per MySQL viene associato a IReadOnlyList<MySqlChange<T>>, che elenca gli MySqlChange oggetti. Ogni oggetto ha due proprietà:

  • Item: elemento modificato. Il tipo dell'elemento deve seguire lo schema della tabella, come illustrato nella ToDoItem classe .
  • Operation: valore dell'enumerazione MySqlChangeOperation . Il valore possibile è Update per gli inserimenti e gli aggiornamenti.

L'esempio seguente mostra una funzione C# richiamata quando si verificano modifiche nella Product tabella:

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);
            }
        }
}

Esempio di utilizzo

Altri esempi per il trigger Database di Azure per MySQL sono disponibili nel repository GitHub.

L'esempio fa riferimento a una Product classe, a una MySqlChangeProduct classe, a un'enumerazione MySqlChangeOperation e a una tabella di database corrispondente.

In un file separato denominato 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;
    }
}

In un file separato denominato 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;
    }
}

In un file separato denominato 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
);

Per abilitare il rilevamento delle modifiche nel database, aggiungere la colonna seguente alla tabella :

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

Il trigger di Database di Azure per MySQL viene associato a MySqlChangeProduct[], ovvero una matrice di MySqlChangeProduct oggetti. Ogni oggetto ha due proprietà:

  • item: elemento modificato. Il tipo dell'elemento deve seguire lo schema della tabella, come illustrato nella Product classe .
  • operation: valore dell'enumerazione MySqlChangeOperation . Il valore possibile è Update per gli inserimenti e gli aggiornamenti.

L'esempio seguente mostra una funzione Java richiamata quando si verificano modifiche nella Product tabella:

/**
 * 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));
    }
}

Esempio di utilizzo

Altri esempi per il trigger Database di Azure per MySQL sono disponibili nel repository GitHub.

L'esempio fa riferimento a una Product tabella di database:

DROP TABLE IF EXISTS Products;

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

Per abilitare il rilevamento delle modifiche nel database, aggiungere una colonna alla tabella:

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

Il trigger di Database di Azure per MySQL viene associato a Product, che elenca gli oggetti. Ogni oggetto ha due proprietà:

  • item: elemento modificato. La struttura dell'elemento segue lo schema della tabella.
  • operation: il valore possibile è Update per gli inserimenti e gli aggiornamenti.

L'esempio seguente mostra una funzione di PowerShell richiamata quando si verificano modifiche nella Product tabella.

L'esempio seguente è l'associazione dei dati nel file function.json:

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

La sezione Configurazione illustra queste proprietà.

L'esempio seguente è il codice di PowerShell di esempio per la funzione nel file 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"

Esempio di utilizzo

Altri esempi per il trigger Database di Azure per MySQL sono disponibili nel repository GitHub.

L'esempio fa riferimento a una Product tabella di database:

DROP TABLE IF EXISTS Products;

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

Per abilitare il rilevamento delle modifiche nel database, aggiungere una colonna alla tabella:

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

Il trigger di Database di Azure per MySQL viene associato a Changes, ovvero una matrice di oggetti. Ogni oggetto ha due proprietà:

  • item: elemento modificato. La struttura dell'elemento segue lo schema della tabella.
  • operation: il valore possibile è Update per gli inserimenti e gli aggiornamenti.

L'esempio seguente mostra una funzione JavaScript richiamata quando si verificano modifiche nella Product tabella.

L'esempio seguente è l'associazione dei dati nel file function.json:

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

La sezione Configurazione illustra queste proprietà.

L'esempio seguente è il codice JavaScript di esempio per la funzione nel index.js file :

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

Esempio di utilizzo

Altri esempi per il trigger Database di Azure per MySQL sono disponibili nel repository GitHub.

L'esempio fa riferimento a una Product tabella di database:

DROP TABLE IF EXISTS Products;

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

Per abilitare il rilevamento delle modifiche nel database, aggiungere una colonna alla tabella:

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

Nota

È necessario usare Funzioni di Azure versione 1.22.0b4 per Python.

Il trigger di Database di Azure per MySQL viene associato a una variabile denominata Product, che elenca gli oggetti . Ogni oggetto ha due proprietà:

  • item: elemento modificato. La struttura dell'elemento segue lo schema della tabella.
  • operation: il valore possibile è Update per gli inserimenti e gli aggiornamenti.

L'esempio seguente mostra una funzione Python richiamata quando si verificano modifiche nella Product tabella.

L'esempio seguente è il codice Python di esempio per il file 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))

Attributi

Proprietà dell'attributo Descrizione
TableName Obbligatorio. Nome della tabella monitorata dal trigger.
ConnectionStringSetting Obbligatorio. Nome di un'impostazione dell'app che contiene la stringa di connessione per il database che contiene la tabella monitorata per le modifiche. Il nome dell'impostazione della stringa di connessione corrisponde all'impostazione dell'applicazione (in local.settings.json per lo sviluppo locale) che contiene la stringa di connessione a Database di Azure per MySQL.
LeasesTableName Facoltativo. Nome della tabella per l'archiviazione dei lease. Se non è specificato, il nome è Leases_{FunctionId}_{TableId}.

Annotazioni

Nella libreria di runtime delle funzioni Java usare l'annotazione @MySQLTrigger sui parametri i cui valori provengono da Database di Azure per MySQL. Questa annotazione supporta gli elementi seguenti:

Elemento Descrizione
name Obbligatorio. Nome del parametro a cui viene associato il trigger.
tableName Obbligatorio. Nome della tabella monitorata dal trigger.
connectionStringSetting Obbligatorio. Nome di un'impostazione dell'app che contiene la stringa di connessione per il database che contiene la tabella monitorata per le modifiche. Il nome dell'impostazione della stringa di connessione corrisponde all'impostazione dell'applicazione (in local.settings.json per lo sviluppo locale) che contiene la stringa di connessione a Database di Azure per MySQL.
LeasesTableName Facoltativo. Nome della tabella per l'archiviazione dei lease. Se non è specificato, il nome è Leases_{FunctionId}_{TableId}.

Impostazione

La tabella seguente illustra le proprietà di configurazione dell'associazione impostate nel file function.json:

Proprietà Descrizione
name Obbligatorio. Nome del parametro a cui viene associato il trigger.
type Obbligatorio. Deve essere impostato su MysqlTrigger.
direction Obbligatorio. Deve essere impostato su in.
tableName Obbligatorio. Nome della tabella monitorata dal trigger.
connectionStringSetting Obbligatorio. Nome di un'impostazione dell'app che contiene la stringa di connessione per il database che contiene la tabella monitorata per le modifiche. Il nome dell'impostazione della stringa di connessione corrisponde all'impostazione dell'applicazione (in local.settings.json per lo sviluppo locale) che contiene la stringa di connessione a Database di Azure per MySQL.
LeasesTableName Facoltativo. Nome della tabella per l'archiviazione dei lease. Se non è specificato, il nome è Leases_{FunctionId}_{TableId}.

Configurazione facoltativa

È possibile configurare le impostazioni facoltative seguenti per il trigger di Database di Azure per MySQL per lo sviluppo locale o per le distribuzioni cloud.

host.json

Questa sezione descrive le impostazioni di configurazione disponibili per questa associazione nella versione 2.x e successive. Le impostazioni nel file host.json si applicano a tutte le funzioni in un'istanza dell'app per le funzioni. Per altre informazioni sulle impostazioni di configurazione dell'app per le funzioni, vedere informazioni di riferimentohost.json per Funzioni di Azure.

Impostazione Valore predefinito Descrizione
MaxBatchSize 100 Numero massimo di modifiche elaborate con ogni iterazione del ciclo di trigger prima che vengano inviate alla funzione attivata.
PollingIntervalMs 1000 Ritardo in millisecondi tra l'elaborazione di ogni batch di modifiche. (1.000 ms è 1 secondo.
MaxChangesPerWorker 1000 Limite massimo per il numero di modifiche in sospeso nella tabella utente consentite per ogni ruolo di lavoro dell'applicazione. Se il numero di modifiche supera questo limite, potrebbe comportare un aumento del numero di istanze. L'impostazione si applica solo per le app per le funzioni di Azure con scalabilità guidata dal runtime abilitata.

File di host.json di esempio

Ecco un esempio di file host.json con le impostazioni facoltative:

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

local.setting.json

Il file local.settings.json archivia le impostazioni e le impostazioni dell'app usate dagli strumenti di sviluppo locali. Le impostazioni nel file local.settings.json vengono usate solo quando si esegue il progetto in locale. Quando si pubblica il progetto in Azure, assicurarsi di aggiungere anche le impostazioni necessarie alle impostazioni dell'app per l'app per le funzioni.

Importante

Poiché il file local.settings.json potrebbe contenere segreti, ad esempio le stringhe di connessione, non è mai consigliabile archiviarlo in un repository remoto. Gli strumenti che supportano Funzioni di Azure consentono di sincronizzare le impostazioni nel file local.settings.json con le impostazioni dell'app nell'app per le funzioni in cui viene distribuito il progetto.

Impostazione Valore predefinito Descrizione
MySql_Trigger_BatchSize 100 Numero massimo di modifiche elaborate con ogni iterazione del ciclo di trigger prima che vengano inviate alla funzione attivata.
MySql_Trigger_PollingIntervalMs 1000 Ritardo in millisecondi tra l'elaborazione di ogni batch di modifiche. (1.000 ms è 1 secondo.
MySql_Trigger_MaxChangesPerWorker 1000 Limite massimo per il numero di modifiche in sospeso nella tabella utente consentite per ogni ruolo di lavoro dell'applicazione. Se il numero di modifiche supera questo limite, potrebbe comportare un aumento del numero di istanze. L'impostazione si applica solo per le app per le funzioni di Azure con scalabilità guidata dal runtime abilitata.

File di local.settings.json di esempio

Ecco un esempio di file local.settings.json con le impostazioni facoltative:

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

Configurare il rilevamento delle modifiche (obbligatorio)

Per configurare il rilevamento delle modifiche da usare con il trigger database di Azure per MySQL è necessario aggiungere una colonna in una tabella usando una funzione . È possibile completare questi passaggi da qualsiasi strumento MySQL che supporta l'esecuzione di query, tra cui Visual Studio Code o Azure Data Studio.

Le associazioni di trigger di Database di Azure per MySQL usano az_func_updated_at i dati delle colonne e per monitorare la tabella utente per verificare la disponibilità di modifiche. Di conseguenza, è necessario modificare la struttura della tabella per consentire il rilevamento delle modifiche nella tabella MySQL prima di usare il supporto del trigger. È possibile abilitare il rilevamento delle modifiche in una tabella tramite la query seguente. Ad esempio, abilitarlo nella Products tabella:

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

La tabella per i lease contiene tutte le colonne che corrispondono alla chiave primaria della tabella utente e altre due colonne: az_func_AttemptCount e az_func_LeaseExpirationTime. Se una delle colonne chiave primaria ha lo stesso nome, il risultato è un messaggio di errore che elenca i conflitti. In questo caso, le colonne chiave primaria elencate devono essere rinominate affinché il trigger funzioni.

Abilitare il ridimensionamento basato sul runtime

Facoltativamente, le funzioni possono essere ridimensionate automaticamente in base al numero di modifiche in sospeso da elaborare nella tabella utente. Per consentire alle funzioni di ridimensionare correttamente il piano Premium quando si usano i trigger di Database di Azure per MySQL, è necessario abilitare il monitoraggio della scalabilità di runtime.

  1. Nell'app per le funzioni del portale di Azure selezionare Configurazione.

  2. Nella scheda Impostazioni runtime funzione selezionare per Monitoraggio scalabilità di runtime.

    Screenshot dell'area del portale di Azure per abilitare il ridimensionamento in fase di esecuzione.

Supporto di ripetizione dei tentativi

Tentativi di avvio

Se si verifica un'eccezione durante l'avvio, il runtime dell'host tenta automaticamente di riavviare il listener del trigger con una strategia di backoff esponenziale. Questi tentativi continuano fino a quando il listener non viene avviato correttamente o l'avvio viene annullato.

Tentativi di eccezione della funzione

Se si verifica un'eccezione nella funzione utente durante l'elaborazione delle modifiche, il batch di righe attualmente in fase di elaborazione viene ritentato in 60 secondi. Durante questo periodo di tempo vengono elaborate altre modifiche, ma le righe del batch che hanno causato l'eccezione vengono ignorate fino al termine del periodo di timeout.

Se l'esecuzione della funzione ha esito negativo cinque volte consecutive per una determinata riga, tale riga viene ignorata per tutte le modifiche future. Poiché le righe di un batch non sono deterministiche, le righe di un batch non riuscito potrebbero terminare in batch diversi nelle chiamate successive. Questo comportamento significa che non tutte le righe del batch non riuscito vengono necessariamente ignorate. Se altre righe nel batch hanno causato l'eccezione, le righe "valide" potrebbero terminare in un batch diverso che non ha esito negativo nelle chiamate future.