Trigger Azure SQL pro functions

  • Článek

Poznámka:

Ve funkcích plánu Consumption se pro trigger SQL nepodporuje automatické škálování. Pokud proces automatického škálování zastaví funkci, zastaví se veškeré zpracování událostí a bude nutné ji ručně restartovat.

Využijte plány Premium nebo Dedicated pro výhody škálování pomocí triggeru SQL.

Trigger Azure SQL používá funkci sledování změn SQL k monitorování změn v tabulce SQL a aktivaci funkce při vytváření, aktualizaci nebo odstranění řádku. Podrobnosti o konfiguraci pro sledování změn pro použití s triggerem Azure SQL najdete v tématu Nastavení sledování změn. Informace o nastavení rozšíření Azure SQL pro Azure Functions najdete v přehledu vazeb SQL.

Rozhodnutí o škálování pro plány Consumption a Premium aktivují Azure SQL prostřednictvím cílového škálování. Další informace najdete v tématu Škálování na základě cíle.

Přehled funkcí

Vazba triggeru Azure SQL používá smyčku dotazování ke kontrole změn a aktivaci funkce uživatele při zjištění změn. Na vysoké úrovni smyčka vypadá takto:

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
}

Změny se zpracovávají v pořadí, v jakém byly provedeny jejich změny, přičemž nejstarší změny se zpracovávají jako první. Několik poznámek ke zpracování změn:

  1. Pokud jsou změny více řádků provedeny najednou, přesné pořadí, v jakém jsou odeslány do funkce, je založeno na pořadí vrácené funkcí CHANGETABLE.
  2. Změny jsou "dávkové" společně pro řádek. Pokud se mezi jednotlivými iteracemi smyčky provede více změn, pro tento řádek existuje pouze jedna položka změn, která zobrazí rozdíl mezi posledním zpracovaným stavem a aktuálním stavem.
  3. Pokud jsou změny provedené v sadě řádků a další sada změn se provede na polovinu stejných řádků, pak se nejprve zpracuje polovina řádků, které nebyly změněny podruhé. Tato logika zpracování je způsobená výše uvedenou poznámkou se změnami, které jsou dávkové – trigger uvidí jenom poslední provedenou změnu a použije ji pro pořadí, ve které je zpracovává.

Další informace o sledování změn a o tom, jak ji používají aplikace, jako jsou triggery Azure SQL, najdete v tématu práce se sledováním změn .

Příklad využití

Další ukázky triggeru Azure SQL jsou k dispozici v úložišti GitHub.

Příklad odkazuje na ToDoItem třídu a odpovídající tabulku databáze:

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

Sledování změn je povolené v databázi a v tabulce:

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

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

Aktivační událost SQL se sváže se seznamem IReadOnlyList<SqlChange<T>>SqlChange objektů s dvěma vlastnostmi:

  • Položka: položka, která byla změněna. Typ položky by měl následovat podle schématu tabulky, jak je vidět ve ToDoItem třídě.
  • Operace: hodnota z SqlChangeOperation výčtu. Hodnoty pole jsou Insert, Update a Delete.

Následující příklad ukazuje funkci jazyka C#, která se vyvolá, když dojde ke změnám ToDo tabulky:

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

Příklad využití

Další ukázky triggeru Azure SQL jsou k dispozici v úložišti GitHub.

Příklad odkazuje na ToDoItem třídu, SqlChangeToDoItem třídu, SqlChangeOperation výčet a odpovídající tabulku databáze:

V samostatném souboru 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;
    }
}

V samostatném souboru 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;
    }
}

V samostatném souboru 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
);

Sledování změn je povolené v databázi a v tabulce:

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

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

Trigger SQL se sváže s polem SqlChangeToDoItem[]SqlChangeToDoItem objektů s dvěma vlastnostmi:

  • item: položka, která byla změněna. Typ položky by měl následovat podle schématu tabulky, jak je vidět ve ToDoItem třídě.
  • operation: hodnota z SqlChangeOperation výčtu. Hodnoty pole jsou Insert, Update a Delete.

Následující příklad ukazuje funkci Java, která se vyvolá, když dojde ke změnám ToDo tabulky:

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

Příklad využití

Další ukázky triggeru Azure SQL jsou k dispozici v úložišti GitHub.

Příklad odkazuje na ToDoItem tabulku databáze:

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

Sledování změn je povolené v databázi a v tabulce:

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

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

Aktivační událost SQL se sváže se todoChangesseznamem objektů s dvěma vlastnostmi:

  • item: položka, která byla změněna. Struktura položky bude následovat podle schématu tabulky.
  • operace: možné hodnoty jsou Insert, Updatea Delete.

Následující příklad ukazuje funkci PowerShellu, která se vyvolá, když dojde ke změnám ToDo tabulky.

V souboru function.json jsou svázná data:

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

Oddíl konfigurace vysvětluje tyto vlastnosti.

Následuje ukázkový kód PowerShellu pro funkci v run.ps1 souboru:

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"

Příklad využití

Další ukázky triggeru Azure SQL jsou k dispozici v úložišti GitHub.

Příklad odkazuje na ToDoItem tabulku databáze:

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

Sledování změn je povolené v databázi a v tabulce:

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

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

Trigger SQL vytvoří vazbu todoChanges, pole objektů každý se dvěma vlastnostmi:

  • item: položka, která byla změněna. Struktura položky bude následovat podle schématu tabulky.
  • operace: možné hodnoty jsou Insert, Updatea Delete.

Následující příklad ukazuje funkci JavaScriptu, která se vyvolá, když dojde ke změnám ToDo tabulky.

V souboru function.json jsou svázná data:

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

Oddíl konfigurace vysvětluje tyto vlastnosti.

Následuje ukázkový kód JavaScriptu pro funkci v index.js souboru:

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

Příklad využití

Další ukázky triggeru Azure SQL jsou k dispozici v úložišti GitHub.

Příklad odkazuje na ToDoItem tabulku databáze:

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

Sledování změn je povolené v databázi a v tabulce:

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

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

Trigger SQL je vázán na proměnnou todoChanges, seznam objektů každý se dvěma vlastnostmi:

  • item: položka, která byla změněna. Struktura položky bude následovat podle schématu tabulky.
  • operace: možné hodnoty jsou Insert, Updatea Delete.

Následující příklad ukazuje funkci Pythonu, která se vyvolá, když dojde ke změnám ToDo tabulky.

V souboru function.json jsou svázná data:

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

Oddíl konfigurace vysvětluje tyto vlastnosti.

Následuje ukázkový kód Pythonu pro funkci v __init__.py souboru:

import json
import logging

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

Atributy

Knihovna jazyka C# používá atribut SqlTrigger k deklaraci triggeru SQL pro funkci, která má následující vlastnosti:

Vlastnost atributu Popis
TableName Povinný: Název tabulky monitorované triggerem
Připojení ionStringSetting Povinný: Název nastavení aplikace, které obsahuje připojovací řetězec databáze obsahující tabulku monitorovanou pro změny. Název nastavení připojovací řetězec odpovídá nastavení aplikace (pro local.settings.json místní vývoj), které obsahuje připojovací řetězec instanci Azure SQL nebo SQL Serveru.
LeasesTableName Nepovinné. Název tabulky použité k ukládání zapůjčení Pokud není zadaný, název tabulky zapůjčení bude Leases_{FunctionId}_{TableId}. Další informace o tom, jak se generuje, najdete tady.

Poznámky

V knihovně modulu runtime funkcí Java použijte @SQLTrigger anotaci (com.microsoft.azure.functions.sql.annotation.SQLTrigger) u parametrů, jejichž hodnota pochází z Azure SQL. Tato poznámka podporuje následující prvky:

Element (Prvek) Popis
Jméno Požadováno. Název parametru, ke kterému trigger vytvoří vazbu.
Tablename Povinný: Název tabulky monitorované triggerem
connectionStringSetting Povinný: Název nastavení aplikace, které obsahuje připojovací řetězec databáze obsahující tabulku monitorovanou pro změny. Název nastavení připojovací řetězec odpovídá nastavení aplikace (pro local.settings.json místní vývoj), které obsahuje připojovací řetězec instanci Azure SQL nebo SQL Serveru.
LeasesTableName Nepovinné. Název tabulky použité k ukládání zapůjčení Pokud není zadaný, název tabulky zapůjčení bude Leases_{FunctionId}_{TableId}. Další informace o tom, jak se generuje, najdete tady.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json.

vlastnost function.json Popis
Jméno Požadováno. Název parametru, ke kterému trigger vytvoří vazbu.
type Povinný: Musí být nastavena na sqlTriggerhodnotu .
direction Povinný: Musí být nastavena na inhodnotu .
Tablename Povinný: Název tabulky monitorované triggerem
connectionStringSetting Povinný: Název nastavení aplikace, které obsahuje připojovací řetězec databáze obsahující tabulku monitorovanou pro změny. Název nastavení připojovací řetězec odpovídá nastavení aplikace (pro local.settings.json místní vývoj), které obsahuje připojovací řetězec instanci Azure SQL nebo SQL Serveru.
LeasesTableName Nepovinné. Název tabulky použité k ukládání zapůjčení Pokud není zadaný, název tabulky zapůjčení bude Leases_{FunctionId}_{TableId}. Další informace o tom, jak se generuje, najdete tady.

Volitelná konfigurace

Pro trigger SQL je možné nakonfigurovat následující volitelná nastavení:

Tato část popisuje nastavení konfigurace dostupné pro tuto vazbu ve verzích 2.x a novějších. Nastavení v souboru host.json platí pro všechny funkce v instanci aplikace funkcí. Následující příklad host.json souboru obsahuje pouze nastavení verze 2.x+ pro tuto vazbu. Další informace o nastavení konfigurace aplikace funkcí ve verzích 2.x a novějších verzích najdete v host.json referenčních informacích ke službě Azure Functions.

Nastavení Popis
Sql_Trigger_BatchSize Maximální počet změn zpracovaných při každé iteraci smyčky triggeru před odesláním do aktivované funkce. Výchozí hodnota je 100.
Sql_Trigger_PollingIntervalMs Zpoždění v milisekundách mezi zpracováním jednotlivých dávek změn. Výchozí hodnota je 1000 (1 sekunda).
Sql_Trigger_MaxChangesPerWorker Horní limit počtu čekajících změn v tabulce uživatelů, které jsou povolené pro pracovní proces aplikace. Pokud počet změn tento limit překročí, může dojít k horizontálnímu navýšení kapacity. Nastavení platí jenom pro aplikace Funkcí Azure s povoleným škálováním řízeným modulem runtime. Výchozí hodnota je 1000.

Nastavení sledování změn (povinné)

Nastavení sledování změn pro použití s triggerem Azure SQL vyžaduje dva kroky. Tyto kroky je možné provést z libovolného nástroje SQL, který podporuje spouštění dotazů, včetně editoru Visual Studio Code, Azure Data Studia nebo aplikace SQL Server Management Studio.

  1. Povolte sledování změn v databázi SQL a nahraďte your database name názvem databáze, ve které se nachází tabulka, která se má monitorovat:

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

    Možnost CHANGE_RETENTION určuje časové období, pro které se uchovávají informace o sledování změn (historie změn). Uchovávání historie změn v databázi SQL může mít vliv na funkce triggeru. Pokud je například funkce Azure Functions několik dní vypnutá a pak se obnoví, databáze bude obsahovat změny, ke kterým došlo během posledních dvou dnů v příkladu výše uvedeného nastavení.

    Tato AUTO_CLEANUP možnost slouží k povolení nebo zakázání úlohy čištění, která odebere staré informace o sledování změn. Pokud dočasný problém brání spuštění triggeru, může být vypnutí automatického čištění užitečné k pozastavení odebrání informací starších než doba uchovávání, dokud se problém nevyřeší.

    Další informace o možnostech sledování změn najdete v dokumentaci k SQL.

  2. Povolte sledování změn v tabulce a nahraďte your table name názvem tabulky, která se má monitorovat (pokud je to vhodné, změňte schéma):

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

    Trigger musí mít u tabulky monitorované změny a systémové tabulky sledování změn přístup pro čtení. Každá aktivační událost funkce má přidruženou tabulku sledování změn a zapůjčení tabulky ve schématu az_func. Tyto tabulky se vytvoří triggerem, pokud ještě neexistují. Další informace o těchto datových strukturách najdete v dokumentaci ke knihovně vazeb Azure SQL.

Povolení škálování řízeného modulem runtime

Volitelně můžete funkce škálovat automaticky na základě počtu změn, které čekají na zpracování v tabulce uživatelů. Pokud chcete, aby se funkce při použití triggerů SQL správně škálovaly v plánu Premium, musíte povolit monitorování škálování modulu runtime.

Na webu Azure Portal ve vaší aplikaci funkcí zvolte Konfigurace a na kartě Nastavení modulu runtime funkce zapněte monitorování škálování modulu runtime na Zapnuto.

Snímek obrazovky s panelem webu Azure Portal pro povolení škálování za běhu

Podpora opakování

Další informace o podpoře opakování triggeru SQL a tabulkách zapůjčení jsou k dispozici v úložišti GitHub.

Opakované pokusy po spuštění

Pokud při spuštění dojde k výjimce, modul runtime hostitele se automaticky pokusí restartovat naslouchací proces triggeru s exponenciální strategií zpoždování. Tyto opakované pokusy budou pokračovat, dokud se naslouchací proces úspěšně nespustí nebo se zruší spuštění.

Přerušené pokusy o připojení

Pokud se funkce úspěšně spustí, ale pak dojde k chybě, že se připojení přeruší (například server přejde do offline režimu), bude se funkce dál pokoušet a znovu otevřít připojení, dokud se funkce nezastaví nebo připojení proběhne úspěšně. Pokud se připojení úspěšně znovu naváže, převezme zpracování změn tam, kde skončil.

Mějte na paměti, že tyto opakování jsou mimo integrovanou nečinnou logiku opakování připojení, kterou sqlClient má, která se dá nakonfigurovat s možnostmi ConnectRetryCounta ConnectRetryIntervalpřipojovací řetězec. Předdefinované nečinné pokusy o připojení se nejprve pokusí a pokud se nepodaří znovu připojit, pokusí se vazba triggeru znovu navázat samotné připojení.

Opakování výjimek funkce

Pokud při zpracování změn dojde v uživatelské funkci k výjimce, dávka řádků, které se právě zpracovávají, se znovu opakují za 60 sekund. Jiné změny se během této doby zpracovávají jako normální, ale řádky v dávce, které způsobily výjimku, se ignorují, dokud časový limit uplynul.

Pokud provádění funkce selže pětkrát v řádku pro daný řádek, bude tento řádek zcela ignorován pro všechny budoucí změny. Vzhledem k tomu, že řádky v dávce nejsou deterministické, můžou řádky v neúspěšné dávce skončit v různých dávkách v následných vyvolání. To znamená, že ne všechny řádky v neúspěšné dávce budou nutně ignorovány. Pokud byly další řádky v dávce těmi, které výjimku způsobují, můžou se řádky "dobré" skončit v jiné dávce, která v budoucích vyvolání neselže.

Další kroky