Azure SQL-utlösare för Functions

  • Artikel

Kommentar

I funktioner för förbrukningsplan stöds inte automatisk skalning för SQL-utlösare. Om den automatiska skalningsprocessen stoppar funktionen stoppas all bearbetning av händelser och den måste startas om manuellt.

Använd premium- eller dedikerade planer för skalningsfördelar med SQL-utlösare.

Azure SQL-utlösaren använder sql-ändringsspårningsfunktioner för att övervaka en SQL-tabell för ändringar och utlösa en funktion när en rad skapas, uppdateras eller tas bort. Konfigurationsinformation för ändringsspårning för användning med Azure SQL-utlösaren finns i Konfigurera ändringsspårning. Information om konfigurationsinformation om Azure SQL-tillägget för Azure Functions finns i översikten över SQL-bindning.

Skalningsbeslut för Azure SQL-utlösare för förbruknings- och Premium-abonnemangen görs via målbaserad skalning. Mer information finns i Målbaserad skalning.

Funktionsöversikt

Azure SQL-utlösarbindningen använder en avsökningsloop för att söka efter ändringar, vilket utlöser användarfunktionen när ändringar identifieras. På en hög nivå ser loopen ut så här:

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
}

Ändringarna bearbetas i den ordning ändringarna har gjorts, och de äldsta ändringarna bearbetas först. Några kommentarer om ändringsbearbetning:

  1. Om ändringar i flera rader görs samtidigt baseras den exakta ordning som de skickas till funktionen på den ordning som returneras av funktionen CHANGETABLE
  2. Ändringarna "batchas" tillsammans för en rad. Om flera ändringar görs i en rad mellan varje iteration av loopen finns det bara en enda ändringspost för den raden som visar skillnaden mellan det senast bearbetade tillståndet och det aktuella tillståndet
  3. Om ändringar görs i en uppsättning rader, och sedan en annan uppsättning ändringar görs till hälften av samma rader, bearbetas hälften av de rader som inte ändrades en andra gång först. Den här bearbetningslogiken beror på ovanstående anteckning med de ändringar som batchas . Utlösaren ser bara den "sista" ändringen som gjorts och använder den för den ordning som den bearbetar dem i

Mer information om ändringsspårning och hur den används av program som Azure SQL-utlösare finns i Arbeta med ändringsspårning .

Exempel på användning

Fler exempel för Azure SQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en ToDoItem klass och en motsvarande databastabell:

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

Ändringsspårning är aktiverat i databasen och i tabellen:

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

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

SQL-utlösaren binder till en , en lista över SqlChange objekt var och en IReadOnlyList<SqlChange<T>>med två egenskaper:

  • Objekt: objektet som ändrades. Typen av objekt ska följa tabellschemat enligt vad som visas i ToDoItem klassen.
  • Åtgärd: ett värde från SqlChangeOperation uppräkningen. De möjliga värden är Insert, Update och Delete.

I följande exempel visas en C#-funktion som anropas när det finns ändringar i ToDo tabellen:

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

Exempel på användning

Fler exempel för Azure SQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en ToDoItem klass, en SqlChangeToDoItem klass, en SqlChangeOperation uppräkning och en motsvarande databastabell:

I en separat fil ToDoItem.java:

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

I en separat fil SqlChangeToDoItem.java:

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

I en separat fil SqlChangeOperation.java:

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

Ändringsspårning är aktiverat i databasen och i tabellen:

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

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

SQL-utlösaren binder till en , en matris med SqlChangeToDoItem objekt var och en SqlChangeToDoItem[]med två egenskaper:

  • item: objektet som ändrades. Typen av objekt ska följa tabellschemat enligt vad som visas i ToDoItem klassen.
  • åtgärd: ett värde från SqlChangeOperation uppräkningen. De möjliga värden är Insert, Update och Delete.

I följande exempel visas en Java-funktion som anropas när det finns ändringar i ToDo tabellen:

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

Exempel på användning

Fler exempel för Azure SQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en ToDoItem databastabell:

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

Ändringsspårning är aktiverat i databasen och i tabellen:

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

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

SQL-utlösaren binder till todoChanges, en lista över objekt var och en med två egenskaper:

  • item: objektet som ändrades. Objektets struktur följer tabellschemat.
  • åtgärd: möjliga värden är Insert, Updateoch Delete.

I följande exempel visas en PowerShell-funktion som anropas när det finns ändringar i ToDo tabellen.

Följande är bindningsdata i function.json-filen:

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

I konfigurationsavsnittet förklaras dessa egenskaper.

Följande är exempel på PowerShell-kod för funktionen i run.ps1 filen:

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"

Exempel på användning

Fler exempel för Azure SQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en ToDoItem databastabell:

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

Ändringsspårning är aktiverat i databasen och i tabellen:

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

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

SQL-utlösaren binder todoChanges, en matris med objekt var och en med två egenskaper:

  • item: objektet som ändrades. Objektets struktur följer tabellschemat.
  • åtgärd: möjliga värden är Insert, Updateoch Delete.

I följande exempel visas en JavaScript-funktion som anropas när det finns ändringar i ToDo tabellen.

Följande är bindningsdata i function.json-filen:

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

I konfigurationsavsnittet förklaras dessa egenskaper.

Följande är JavaScript-exempelkod för funktionen i index.js filen:

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

Exempel på användning

Fler exempel för Azure SQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en ToDoItem databastabell:

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

Ändringsspårning är aktiverat i databasen och i tabellen:

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

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

SQL-utlösaren binder till en variabel todoChanges, en lista över objekt var och en med två egenskaper:

  • item: objektet som ändrades. Objektets struktur följer tabellschemat.
  • åtgärd: möjliga värden är Insert, Updateoch Delete.

I följande exempel visas en Python-funktion som anropas när det finns ändringar i ToDo tabellen.

Följande är bindningsdata i function.json-filen:

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

I konfigurationsavsnittet förklaras dessa egenskaper.

Följande är python-exempelkod för funktionen i __init__.py filen:

import json
import logging

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

Attribut

C#-biblioteket använder attributet SqlTrigger för att deklarera SQL-utlösaren för funktionen, som har följande egenskaper:

Attributegenskap beskrivning
TableName Obligatoriskt. Namnet på tabellen som övervakas av utlösaren.
Anslut ionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträng för databasen som innehåller tabellen som övervakas för ändringar. Det anslutningssträng inställningsnamnet motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträng till Azure SQL- eller SQL Server-instansen.
LeasesTableName Valfritt. Namnet på tabellen som används för att lagra lån. Om det inte anges blir namnet på lånetabellen Leases_{FunctionId}_{TableId}. Mer information om hur detta genereras finns här.

Kommentarer

I Java Functions-körningsbiblioteket använder du anteckningen @SQLTrigger (com.microsoft.azure.functions.sql.annotation.SQLTrigger) för parametrar vars värde skulle komma från Azure SQL. Den här kommentaren stöder följande element:

Element Description
Namn Obligatoriska. Namnet på parametern som utlösaren binder till.
Tablename Obligatoriskt. Namnet på tabellen som övervakas av utlösaren.
connectionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträng för databasen som innehåller tabellen som övervakas för ändringar. Det anslutningssträng inställningsnamnet motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträng till Azure SQL- eller SQL Server-instansen.
LeasesTableName Valfritt. Namnet på tabellen som används för att lagra lån. Om det inte anges blir namnet på lånetabellen Leases_{FunctionId}_{TableId}. Mer information om hur detta genereras finns här.

Konfiguration

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i function.json-filen.

function.json egenskap beskrivning
Namn Obligatoriska. Namnet på parametern som utlösaren binder till.
typ Obligatoriska. Måste anges till sqlTrigger.
riktning Obligatoriskt. Måste anges till in.
Tablename Obligatoriskt. Namnet på tabellen som övervakas av utlösaren.
connectionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträng för databasen som innehåller tabellen som övervakas för ändringar. Det anslutningssträng inställningsnamnet motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträng till Azure SQL- eller SQL Server-instansen.
LeasesTableName Valfritt. Namnet på tabellen som används för att lagra lån. Om det inte anges blir namnet på lånetabellen Leases_{FunctionId}_{TableId}. Mer information om hur detta genereras finns här.

Valfri konfiguration

Följande valfria inställningar kan konfigureras för SQL-utlösaren:

I det här avsnittet beskrivs de konfigurationsinställningar som är tillgängliga för den här bindningen i version 2.x och senare. Inställningar i filen host.json gäller för alla funktioner i en funktionsappinstans. Exemplet host.json filen nedan innehåller endast version 2.x+-inställningarna för den här bindningen. Mer information om konfigurationsinställningar för funktionsappar i version 2.x och senare versioner finns i host.json referens för Azure Functions.

Inställning beskrivning
Sql_Trigger_BatchSize Det maximala antalet ändringar som bearbetas med varje iteration av utlösarloopen innan de skickas till den utlösta funktionen. Standardvärdet är 100.
Sql_Trigger_PollingIntervalMs Fördröjningen i millisekunder mellan bearbetningen av varje batch med ändringar. Standardvärdet är 1 000 (1 sekund).
Sql_Trigger_MaxChangesPerWorker Den övre gränsen för antalet väntande ändringar i användartabellen som tillåts per programarbetare. Om antalet ändringar överskrider den här gränsen kan det resultera i en utskalning. Inställningen gäller endast för Azure Function Apps med körningsdriven skalning aktiverad. Standardvärdet är 1000.

Konfigurera ändringsspårning (krävs)

Att konfigurera ändringsspårning för användning med Azure SQL-utlösaren kräver två steg. De här stegen kan utföras från alla SQL-verktyg som stöder frågor som körs, inklusive Visual Studio Code, Azure Data Studio eller SQL Server Management Studio.

  1. Aktivera ändringsspårning i SQL-databasen och ersätt your database name med namnet på databasen där tabellen som ska övervakas finns:

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

    Alternativet CHANGE_RETENTION anger den tidsperiod för vilken ändringsspårningsinformation (ändringshistorik) sparas. Kvarhållningen av ändringshistoriken i SQL-databasen kan påverka utlösarfunktionen. Om Azure-funktionen till exempel är avstängd i flera dagar och sedan återupptas innehåller databasen de ändringar som har inträffat under de senaste två dagarna i installationsexemplet ovan.

    Alternativet AUTO_CLEANUP används för att aktivera eller inaktivera rensningsaktiviteten som tar bort gammal ändringsspårningsinformation. Om ett tillfälligt problem som hindrar utlösaren från att köras kan det vara användbart att inaktivera automatisk rensning för att pausa borttagningen av information som är äldre än kvarhållningsperioden tills problemet har lösts.

    Mer information om alternativ för ändringsspårning finns i SQL-dokumentationen.

  2. Aktivera ändringsspårning i tabellen och ersätt your table name med namnet på tabellen som ska övervakas (ändra schemat om det är lämpligt):

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

    Utlösaren måste ha läsåtkomst i tabellen som övervakas för ändringar och till systemtabellerna för ändringsspårning. Varje funktionsutlösare har en associerad tabell för ändringsspårning och lån i ett schema az_func. Dessa tabeller skapas av utlösaren om de ännu inte finns. Mer information om dessa datastrukturer finns i dokumentationen för Azure SQL-bindningsbiblioteket.

Aktivera körningsdriven skalning

Om du vill kan dina funktioner skalas automatiskt baserat på antalet ändringar som väntar på att bearbetas i användartabellen. För att dina funktioner ska kunna skalas korrekt på Premium-planen när du använder SQL-utlösare måste du aktivera körningsskalningsövervakning.

I Azure-portalen går du till funktionsappen och väljer Konfiguration och på fliken Funktionskörningsinställningar aktiverar du Körningsskalningsövervakning till På.

Skärmbild av Panelen i Azure-portalen för att aktivera körningsskalning.

Återförsöksstöd

Mer information om sql-utlösarens återförsöksstöd och lånetabeller finns på GitHub-lagringsplatsen.

Återförsök vid start

Om ett undantag inträffar under starten försöker värdkörningen automatiskt starta om utlösarlyssningen med en exponentiell backoff-strategi. Dessa återförsök fortsätter tills lyssnaren har startats eller så avbryts starten.

Brutna anslutningsförsök

Om funktionen startar men sedan ett fel gör att anslutningen bryts (till exempel att servern går offline) fortsätter funktionen att försöka öppna anslutningen igen tills funktionen antingen stoppas eller anslutningen lyckas. Om anslutningen har återupprättats tar den upp bearbetningsändringar där den slutade.

Observera att dessa återförsök ligger utanför den inbyggda inaktiva anslutningslogik som SqlClient har som kan konfigureras med ConnectRetryCount alternativen och ConnectRetryIntervalanslutningssträng. De inbyggda inaktiva anslutningsförsöken görs först och om de misslyckas med att återansluta försöker utlösarbindningen att återupprätta själva anslutningen.

Återförsök av funktionsfel

Om ett undantag inträffar i användarfunktionen när ändringar bearbetas görs en ny batch med rader som bearbetas om 60 sekunder. Andra ändringar bearbetas som vanligt under den här tiden, men de rader i batchen som orsakade undantaget ignoreras tills tidsgränsperioden har gått ut.

Om funktionskörningen misslyckas fem gånger i rad för en viss rad ignoreras den raden helt för alla framtida ändringar. Eftersom raderna i en batch inte är deterministiska kan rader i en misslyckad batch hamna i olika batchar i efterföljande anrop. Det innebär att inte alla rader i den misslyckade batchen nödvändigtvis ignoreras. Om andra rader i batchen var de som orsakade undantaget kan de "bra" raderna hamna i en annan batch som inte misslyckas i framtida anrop.

Nästa steg