Trigger SQL di Azure per Funzioni

Il trigger SQL di Azure usa la funzionalità di rilevamento delle modifiche SQL per monitorare una tabella SQL per rilevare le modifiche e attivare una funzione quando viene creata, aggiornata o eliminata una riga. Per informazioni dettagliate sulla configurazione per il rilevamento delle modifiche da usare con il trigger SQL di Azure, vedere Configurare il rilevamento delle modifiche. Per informazioni dettagliate sull'installazione dell'estensione SQL di Azure per Funzioni di Azure, vedere la panoramica dell'associazione SQL.

Le decisioni di ridimensionamento dei trigger sql di Azure per i piani a consumo e Premium vengono eseguite tramite il ridimensionamento basato sulla destinazione. Per altre informazioni, vedere Scalabilità basata su destinazione.

Panoramica delle funzionalità

L'associazione di trigger SQL di Azure usa un ciclo di polling per verificare la presenza di modifiche, attivando la funzione utente quando vengono rilevate modifiche. A livello generale, il ciclo è simile al seguente:

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

Le modifiche vengono elaborate nell'ordine in cui sono state apportate le modifiche, con le modifiche meno recenti elaborate per prime. Un paio di note sull'elaborazione delle modifiche:

1. Se le modifiche a più righe vengono apportate contemporaneamente all'ordine esatto in cui vengono inviate alla funzione si basa sull'ordine restituito dalla funzione CHANGETABLE
2. Le modifiche vengono "raggruppate" per una riga. Se vengono apportate più modifiche a una riga tra ogni iterazione del ciclo, esiste solo una singola voce di modifica per tale riga che mostrerà la differenza tra l'ultimo stato elaborato e lo stato corrente
3. Se vengono apportate modifiche a un set di righe e quindi viene apportato un altro set di modifiche alla metà delle stesse righe, la metà delle righe che non sono state modificate una seconda volta viene elaborata per prima. Questa logica di elaborazione è dovuta alla nota precedente con le modifiche in batch. Il trigger visualizzerà solo l'ultima modifica apportata e lo userà per l'ordine in cui li elabora.

Per altre informazioni sul rilevamento delle modifiche e sul modo in cui viene usato da applicazioni come i trigger SQL di Azure, vedere Usare il rilevamento delle modifiche.

namespace AzureSQL.ToDo
{
    public class ToDoItem
    {
        public Guid Id { get; set; }
        public int? order { get; set; }
        public string title { get; set; }
        public string url { get; set; }
        public bool? completed { get; set; }
    }
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

using System;
using System.Collections.Generic;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Sql;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;


namespace AzureSQL.ToDo
{
    public static class ToDoTrigger
    {
        [Function("ToDoTrigger")]
        public static void Run(
            [SqlTrigger("[dbo].[ToDo]", "SqlConnectionString")]
            IReadOnlyList<SqlChange<ToDoItem>> changes,
            FunctionContext context)
        {
            var logger = context.GetLogger("ToDoTrigger");
            foreach (SqlChange<ToDoItem> change in changes)
            {
                ToDoItem toDoItem = change.Item;
                logger.LogInformation($"Change operation: {change.Operation}");
                logger.LogInformation($"Id: {toDoItem.Id}, Title: {toDoItem.title}, Url: {toDoItem.url}, Completed: {toDoItem.completed}");
            }
        }
    }
}

namespace AzureSQL.ToDo
{
    public class ToDoItem
    {
        public Guid Id { get; set; }
        public int? order { get; set; }
        public string title { get; set; }
        public string url { get; set; }
        public bool? completed { get; set; }
    }
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

using System.Collections.Generic;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.Sql;

namespace AzureSQL.ToDo
{
    public static class ToDoTrigger
    {
        [FunctionName("ToDoTrigger")]
        public static void Run(
            [SqlTrigger("[dbo].[ToDo]", "SqlConnectionString")]
            IReadOnlyList<SqlChange<ToDoItem>> changes,
            ILogger logger)
        {
            foreach (SqlChange<ToDoItem> change in changes)
            {
                ToDoItem toDoItem = change.Item;
                logger.LogInformation($"Change operation: {change.Operation}");
                logger.LogInformation($"Id: {toDoItem.Id}, Title: {toDoItem.title}, Url: {toDoItem.url}, Completed: {toDoItem.completed}");
            }
        }
    }
}

package com.function;
import java.util.UUID;

public class ToDoItem {
    public UUID Id;
    public int order;
    public String title;
    public String url;
    public boolean completed;

    public ToDoItem() {
    }

    public ToDoItem(UUID Id, int order, String title, String url, boolean completed) {
        this.Id = Id;
        this.order = order;
        this.title = title;
        this.url = url;
        this.completed = completed;
    }
}

package com.function;

public class SqlChangeToDoItem {
    public ToDoItem item;
    public SqlChangeOperation operation;

    public SqlChangeToDoItem() {
    }

    public SqlChangeToDoItem(ToDoItem Item, SqlChangeOperation Operation) {
        this.Item = Item;
        this.Operation = Operation;
    }
}

package com.function;

import com.google.gson.annotations.SerializedName;

public enum SqlChangeOperation {
    @SerializedName("0")
    Insert,
    @SerializedName("1")
    Update,
    @SerializedName("2")
    Delete;
}

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

package com.function;

import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.sql.annotation.SQLTrigger;
import com.function.Common.SqlChangeToDoItem;
import com.google.gson.Gson;

import java.util.logging.Level;

public class ProductsTrigger {
    @FunctionName("ToDoTrigger")
    public void run(
            @SQLTrigger(
                name = "todoItems",
                tableName = "[dbo].[ToDo]",
                connectionStringSetting = "SqlConnectionString")
                SqlChangeToDoItem[] todoItems,
            ExecutionContext context) {

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

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

{
    "name": "todoChanges",
    "type": "sqlTrigger",
    "direction": "in",
    "tableName": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
}

using namespace System.Net

param($todoChanges)
# 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 = $todoChanges | ConvertTo-Json -Compress
Write-Host "SQL Changes: $changesJson"

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

{
    "name": "todoChanges",
    "type": "sqlTrigger",
    "direction": "in",
    "tableName": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
}

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

CREATE TABLE dbo.ToDo (
    [Id] UNIQUEIDENTIFIER PRIMARY KEY,
    [order] INT NULL,
    [title] NVARCHAR(200) NOT NULL,
    [url] NVARCHAR(200) NOT NULL,
    [completed] BIT NOT NULL
);

ALTER DATABASE [SampleDatabase]
SET CHANGE_TRACKING = ON
(CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);

ALTER TABLE [dbo].[ToDo]
ENABLE CHANGE_TRACKING;

import json
import logging
import azure.functions as func
from azure.functions.decorators.core import DataType

app = func.FunctionApp()

@app.function_name(name="ToDoTrigger")
@app.sql_trigger(arg_name="todo",
                        table_name="ToDo",
                        connection_string_setting="SqlConnectionString")
def todo_trigger(todo: str) -> None:
    logging.info("SQL Changes: %s", json.loads(todo))

{
    "name": "todoChanges",
    "type": "sqlTrigger",
    "direction": "in",
    "tableName": "dbo.ToDo",
    "connectionStringSetting": "SqlConnectionString"
}

import json
import logging

def main(changes):
    logging.info("SQL Changes: %s", json.loads(changes))

Configurazione facoltativa

Le impostazioni facoltative seguenti possono essere configurate per il trigger SQL per lo sviluppo locale o per le distribuzioni cloud.

host.json

Questa sezione descrive le impostazioni di configurazione disponibili per questa associazione nelle versioni 2.x e successive. Le impostazioni nel file host.json si applicano a tutte le funzioni in un'istanza dell'app per le funzioni. L'esempio host.json file seguente contiene solo le impostazioni della versione 2.x+ per questa associazione. Per altre informazioni sulle impostazioni di configurazione delle app per le funzioni nelle versioni 2.x e successive, vedere informazioni di riferimento host.json per Funzioni di Azure.

File di host.json di esempio

Di seguito è riportato un esempio di file host.json con le impostazioni facoltative:

{
  "version": "2.0",
  "extensions": {
      "Sql": {
        "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.

File di local.settings.json di esempio

Di seguito è riportato un esempio di file local.settings.json con le impostazioni facoltative:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "SqlConnectionString": "",
    "Sql_Trigger_MaxBatchSize": 300,
    "Sql_Trigger_PollingIntervalMs": 1000,
    "Sql_Trigger_MaxChangesPerWorker": 100
  }
}

Configurare il rilevamento delle modifiche (obbligatorio)

La configurazione del rilevamento delle modifiche da usare con il trigger SQL di Azure richiede due passaggi. Questi passaggi possono essere completati da qualsiasi strumento SQL che supporta l'esecuzione di query, tra cui Visual Studio Code, Azure Data Studio o SQL Server Management Studio.

1. Abilitare il rilevamento delle modifiche nel database SQL, sostituendo your database name con il nome del database in cui si trova la tabella da monitorare:

   ALTER DATABASE [your database name]
   SET CHANGE_TRACKING = ON
   (CHANGE_RETENTION = 2 DAYS, AUTO_CLEANUP = ON);
   

   L'opzione CHANGE_RETENTION specifica il periodo di tempo per il quale vengono mantenute le informazioni di rilevamento delle modifiche (cronologia modifiche). La conservazione della cronologia delle modifiche da parte del database SQL potrebbe influire sulla funzionalità dei trigger. Ad esempio, se la funzione di Azure è disattivata per diversi giorni e quindi ripresa, il database conterrà le modifiche apportate negli ultimi due giorni nell'esempio di configurazione precedente.

   L'opzione AUTO_CLEANUP viene usata per abilitare o disabilitare l'attività di pulizia che rimuove le informazioni di rilevamento delle modifiche precedenti. Se un problema temporaneo che impedisce l'esecuzione del trigger, disattivare la pulizia automatica può essere utile per sospendere la rimozione delle informazioni precedenti al periodo di conservazione fino a quando il problema non viene risolto.

   Altre informazioni sulle opzioni di rilevamento delle modifiche sono disponibili nella documentazione di SQL.

2. Abilitare il rilevamento delle modifiche nella tabella, sostituendo your table name con il nome della tabella da monitorare (modificando lo schema, se appropriato):

   ALTER TABLE [dbo].[your table name]
   ENABLE CHANGE_TRACKING;
   

   Il trigger deve avere accesso in lettura alla tabella monitorata per le modifiche e alle tabelle di sistema di rilevamento delle modifiche. Ogni trigger di funzione ha una tabella di rilevamento delle modifiche associata e una tabella lease in uno schema az_func. Queste tabelle vengono create dal trigger se non esistono ancora. Altre informazioni su queste strutture di dati sono disponibili nella documentazione della libreria di associazioni SQL di Azure.

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 SQL, è necessario abilitare il monitoraggio della scalabilità di runtime.

az resource update -g <RESOURCE_GROUP> -n <FUNCTION_APP_NAME>/config/web --set properties.functionsRuntimeScaleMonitoringEnabled=1 --resource-type Microsoft.Web/sites

Supporto di ripetizione dei tentativi

Altre informazioni sul supporto dei tentativi di trigger SQL e sulle tabelle di lease sono disponibili nel repository GitHub.

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 connessione interrotti

Se la funzione viene avviata correttamente, ma un errore causa l'interruzione della connessione , ad esempio il server offline, la funzione continua a provare e riaprire la connessione fino a quando la funzione non viene arrestata o la connessione ha esito positivo. Se la connessione viene ristabilita, l'elaborazione delle modifiche è stata interrotta.

Si noti che questi tentativi non rientrano nella logica di ripetizione dei tentativi di connessione inattiva predefinita che SqlClient può essere configurato con le ConnectRetryCount opzioni e ConnectRetryInterval stringa di connessione. I tentativi di connessione inattiva predefiniti vengono tentati per primi e se questi non riescono a riconnettersi, l'associazione trigger tenta di ristabilire la connessione stessa.

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 a quando non è trascorso il periodo di timeout.

Se l'esecuzione della funzione ha esito negativo cinque volte in una riga per una determinata riga, tale riga viene completamente 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. Ciò significa che non tutte le righe nel batch non riuscito verranno necessariamente ignorate. Se altre righe nel batch causavano l'eccezione, le righe "valide" potrebbero terminare in un batch diverso che non ha esito negativo nelle chiamate future.

Passaggi successivi

• Legge i dati da un database (associazione di input)
• Salvare i dati in un database (associazione di output)