Azure SQL-Trigger für Functions

Der Azure SQL-Trigger verwendet SQL-Änderungsnachverfolgungsfunktionen, um eine SQL-Tabelle auf Änderungen zu überwachen und eine Funktion auszulösen, wenn eine Zeile erstellt, aktualisiert oder gelöscht wird. Konfigurationsdetails für die Änderungsnachverfolgung im Zusammenhang mit dem Azure SQL-Trigger finden Sie unter Einrichten von Änderungsnachverfolgung. Informationen zu Setupdetails der Azure SQL-Erweiterung für Azure Functions finden Sie in der Übersicht über die SQL-Bindung.

Die Entscheidungen zur Skalierung von Azure SQL-Trigger für die Tarife „Verbrauch“ und „Premium“ werden über die zielbasierte Skalierung getroffen. Weitere Informationen finden Sie unter Zielbasierte Skalierung.

Übersicht über die Funktionalität

Die Azure SQL-Triggerbindung verwendet eine Abrufschleife, um nach Änderungen zu suchen, und lösen die Benutzerfunktion aus, wenn Änderungen erkannt werden. Im Großen und Ganzen sieht die Schleife wie folgt aus:

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
}

Änderungen werden in der Reihenfolge verarbeitet, in der sie vorgenommen wurden, wobei die ältesten Änderungen zuerst verarbeitet werden. Einige Hinweise zur Verarbeitung von Änderungen:

1. Wenn Änderungen an mehreren Zeilen gleichzeitig vorgenommen werden, basiert die genaue Reihenfolge, in der sie an die Funktion gesendet werden, auf der Reihenfolge, die von der CHANGETABLE-Funktion zurückgegeben wird.
2. Änderungen an einer Zeile werden in einem „Batch“ zusammengefasst. Wenn zwischen jeder Iteration der Schleife mehrere Änderungen an einer Zeile vorgenommen werden, ist nur ein einzelner Änderungseintrag für diese Zeile vorhanden, der den Unterschied zwischen dem zuletzt verarbeiteten Zustand und dem aktuellen Zustand anzeigt.
3. Wenn Änderungen an mehreren Zeilen vorgenommen werden und dann andere Änderungen an der Hälfte dieser Zeilen vorgenommen werden, wird die Hälfte der Zeilen, die nicht ein zweites Mal geändert wurde, zuerst verarbeitet. Diese Verarbeitungslogik ist auf den obigen Hinweis zurückzuführen, bei dem die Änderungen als Batch verarbeitet werden. Der Trigger wird nur die „letzte“ vorgenommene Änderung sehen und verwendet diese für die Reihenfolge, in der er sie verarbeitet.

Weitere Informationen zur Änderungsnachverfolgung und ihrer Verwendung durch Anwendungen wie Azure SQL-Triggers finden Sie unter Verwenden der Änderungsnachverfolgung.

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

Optionale Konfiguration

Die folgenden optionalen Einstellungen können für den SQL-Trigger für die lokale Entwicklung oder für Cloudbereitstellungen konfiguriert werden.

host.json

In diesem Abschnitt werden die für diese Bindung verfügbaren Konfigurationseinstellungen in Version 2.x und höher beschrieben. Einstellungen in der Datei „host.json“ gelten für alle Funktionen in einer Funktions-App-Instanz. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x und höhere Versionen für diese Bindung. Weitere Informationen zu den Konfigurationseinstellungen für Funktions-Apps in Version 2.x und höher finden Sie unter host.json-Referenz für Azure Functions.

Beispieldatei host.json

Hier ist ein Beispiel host.json Datei mit den optionalen Einstellungen:

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

local.setting.json

Die Datei „local.settings.json“ speichert App-Einstellungen und Einstellungen, die von lokalen Entwicklungstools verwendet werden. Einstellungen in der Datei „local.settings.json“ werden nur bei der lokalen Ausführung Ihrer Projekte verwendet. Wenn Sie Ihr Projekt in Azure veröffentlichen, müssen Sie auch alle erforderlichen Einstellungen zu den App-Einstellungen für die Funktions-App hinzufügen.

Beispieldatei local.settings.json

Nachfolgend sehen Sie ein Beispiel local.settings.json Datei mit den optionalen Einstellungen:

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

Einrichten von Änderungsnachverfolgung (erforderlich)

Zum Einrichten von Änderungsnachverfolgung für die Verwendung mit dem Azure SQL-Trigger sind zwei Schritte erforderlich. Diese Schritte können mit jedem SQL-Tool ausgeführt werden, das die Ausführung von Abfragen unterstützt, einschließlich Visual Studio Code, Azure Data Studio oder SQL Server Management Studio.

1. Aktivieren Sie Änderungsnachverfolgung für die SQL-Datenbank, und ersetzen Sie dabei your database name durch den Namen der Datenbank, in der sich die zu überwachende Tabelle befindet:

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

   Die CHANGE_RETENTION-Option gibt den Zeitraum an, für den Änderungsnachverfolgungsinformationen (Änderungsverlauf) aufbewahrt werden. Die Aufbewahrung des Änderungsverlaufs durch die SQL-Datenbank kann sich auf die Triggerfunktionalität auswirken. Wenn die Azure-Funktion beispielsweise für mehrere Tage deaktiviert und dann fortgesetzt wird, enthält die Datenbank beim obigen Setupbeispiel nur die Änderungen der letzten beiden Tage.

   Die AUTO_CLEANUP-Option wird verwendet, um den Bereinigungstask zu aktivieren oder zu deaktivieren, mit dem alte Änderungsnachverfolgungsinformationen entfernt werden. Wenn ein vorübergehendes Problem die Ausführung des Triggers verhindert, kann das Deaktivieren der automatischen Bereinigung hilfreich sein, um das Entfernen von Informationen zu unterbrechen, die älter als der Aufbewahrungszeitraum sind, bis das Problem behoben wurde.

   Weitere Informationen zu Optionen für Änderungsnachverfolgung finden Sie in der SQL-Dokumentation.

2. Aktivieren Sie Änderungsnachverfolgung für die Tabelle, und ersetzen Sie your table name dabei durch den Namen der zu überwachenden Tabelle (ändern Sie ggf. das Schema):

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

   Der Trigger benötigt Lesezugriff für die Tabelle, die auf Änderungen überwacht wird, und für die Systemtabellen der Änderungsnachverfolgung. Jeder Funktionstrigger verfügt über eine zugeordnete Änderungsnachverfolgungstabelle und Leasetabelle in einem az_func-Schema. Diese Tabellen werden vom Trigger erstellt, wenn sie noch nicht vorhanden sind. Weitere Informationen zu diesen Datenstrukturen finden Sie in der Dokumentation zur Azure SQL-Bindungsbibliothek.

Aktivieren runtimegesteuerter Skalierung

Optional können Ihre Funktionen basierend auf der Anzahl an Änderungen, deren Bearbeitung in der Benutzertabelle aussteht, automatisch skaliert werden. Damit Ihre Funktionen ordnungsgemäß im Premium-Plan skaliert werden können, wenn Sie SQL-Trigger verwenden, müssen Sie Überwachung der Runtimeskalierung aktivieren.

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

Wiederholungsunterstützung

Weitere Informationen zur Wiederholungsunterstützung von SQL-Triggern und zu Leasetabellen finden Sie im GitHub-Repository.

Startwiederholungen

Wenn während des Startvorgangs eine Ausnahme auftritt, versucht die Hostruntime automatisch, den Triggerlistener mit einer exponentiellen Backoffstrategie neu zu starten. Diese Wiederholungen werden fortgesetzt, bis entweder der Listener erfolgreich gestartet oder der Start abgebrochen wurde.

Wiederholungen bei getrennten Verbindungen

Wenn die Funktion erfolgreich gestartet wird, aber ein Fehler dazu führt, dass die Verbindung unterbrochen wird (z. B. wenn der Server offline geht), versucht die Funktion so lange, die Verbindung erneut zu öffnen, bis die Funktion entweder beendet oder die Verbindung erfolgreich hergestellt wird. Wenn die Verbindung erfolgreich wiederhergestellt wurde, wird die Verarbeitung der Änderungen dort fortgesetzt, wo sie unterbrochen wurde.

Beachten Sie, dass sich diese Wiederholungsversuche außerhalb der integrierten Logik für die Leerlaufverbindung befinden, über die SqlClient verfügt, die mit den ConnectRetryCount Optionen und ConnectRetryInterval Verbindungszeichenfolge konfiguriert werden kann. Die integrierten Verbindungsversuche im Leerlauf werden zuerst durchgeführt, und wenn diese nicht zu einer Wiederherstellung der Verbindung führen, versucht die Triggerbindung, die Verbindung selbst wiederherzustellen.

Wiederholungen bei Funktionsausnahmen

Wenn bei der Verarbeitung von Änderungen eine Ausnahme in der Benutzerfunktion auftritt, wird der Batch der derzeit verarbeiteten Zeilen nach 60 Sekunden wiederholt. Andere Änderungen während dieser Zeit werden normal verarbeitet, aber die Zeilen im Batch, der die Ausnahme verursacht hat, werden ignoriert, bis der Timeoutzeitraum abgelaufen ist.

Wenn die Funktionsausführung für eine bestimmte Zeile fünfmal nacheinander fehlschlägt, wird diese Zeile bei allen zukünftigen Änderungen vollständig ignoriert. Da die Zeilen in einem Batch nicht deterministisch sind, können Zeilen in einem fehlerhaften Batch bei nachfolgenden Aufrufen unterschiedlichen Batches zugeordnet werden. Dies bedeutet, dass nicht alle Zeilen im fehlerhaften Batch wirklich ignoriert werden. Wenn andere Zeilen im Batch die Ursache für die Ausnahme waren, können die fehlerfreien Zeilen einem anderen Batch zugeordnet werden, der bei zukünftigen Aufrufen keine Fehler verursacht.

Nächste Schritte

• Lesen von Daten aus einer Datenbank (Eingabebindung)
• Speichern von Daten in einer Datenbank (Ausgabebindung)