Azure SQL-eseményindító a Functionshez

Feljegyzés

A használati terv függvényeiben az automatikus skálázás nem támogatott az SQL-eseményindítók esetében. Ha az automatikus méretezési folyamat leállítja a függvényt, az események feldolgozása leáll, és manuálisan kell újraindítani.

Prémium vagy dedikált csomagokat használhat az ELŐNYÖK skálázására az SQL-eseményindítóval.

Az Azure SQL-eseményindító sql-változáskövetési funkcióval figyeli az SQL-táblák módosításait, és aktivál egy függvényt egy sor létrehozásakor, frissítésekor vagy törlésekor. Az Azure SQL-eseményindítóval való használatra vonatkozó változáskövetés konfigurációs részleteiért lásd : Változáskövetés beállítása. Az Azure Functions Azure SQL-bővítményének beállítási részleteiről az SQL-kötés áttekintésében olvashat.

Az Azure SQL-eseményindítók skálázási döntései a Használati és Prémium csomagok esetében célalapú skálázással érhetők el. További információ: Célalapú skálázás.

A funkciók áttekintése

Az Azure SQL-eseményindító kötése lekérdezési ciklus használatával ellenőrzi a módosításokat, és aktiválja a felhasználói függvényt a változások észlelésekor. Magas szinten a hurok a következőképpen néz ki:

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
}

A módosítások feldolgozása a módosítások sorrendjében történik, a legrégebbi módosításokat pedig a rendszer dolgozza fel először. Néhány megjegyzés a változásfeldolgozásról:

  1. Ha több sor módosítása egyszerre történik, a függvénynek küldött pontos sorrend a CHANGETABLE függvény által visszaadott sorrenden alapul.
  2. A módosítások "kötegelve" vannak egy sorhoz. Ha a ciklus egyes iterációi között több módosítás is történik, akkor csak egyetlen módosítási bejegyzés létezik az adott sorhoz, amely az utolsó feldolgozott állapot és az aktuális állapot közötti különbséget jeleníti meg
  3. Ha sorkészleten módosítják a módosításokat, és egy másik módosítási halmazt hajtanak végre ugyanannak a sornak a felére, akkor a második alkalommal nem módosított sorok fele lesz először feldolgozva. Ez a feldolgozási logika a fenti megjegyzésnek köszönhető, amely a módosításokat kötegeli – az eseményindító csak az "utolsó" módosítást látja, és azt használja arra a sorrendre, amelyben feldolgozza őket

A változáskövetésről és az alkalmazások, például az Azure SQL-eseményindítók általi használatáról további információt a változáskövetéssel kapcsolatos munka című témakörben talál.

Példa használatra

Az Azure SQL-eseményindítóhoz további minták érhetők el a GitHub-adattárban.

A példa egy ToDoItem osztályra és egy megfelelő adatbázistáblára hivatkozik:

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

A változáskövetés engedélyezve van az adatbázisban és a táblában:

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

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

Az SQL-eseményindító egy IReadOnlyList<SqlChange<T>>, két tulajdonsággal rendelkező objektumlistához SqlChange kapcsolódik:

  • Elem: a módosított elem. Az elem típusának az osztályban látható táblázatsémát kell követnie ToDoItem .
  • Művelet: enumerálási SqlChangeOperation érték. A lehetséges értékek: Insert, Update és Delete.

Az alábbi példa egy C#-függvényt mutat be, amely a tábla módosításakor ToDo lesz meghívva:

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élda használatra

Az Azure SQL-eseményindítóhoz további minták érhetők el a GitHub-adattárban.

A példa egy ToDoItem osztályra, egy osztályra SqlChangeToDoItem , egy SqlChangeOperation számra és egy megfelelő adatbázistáblára hivatkozik:

Egy külön fájlban 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;
    }
}

Egy külön fájlban 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;
    }
}

Egy külön fájlban 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
);

A változáskövetés engedélyezve van az adatbázisban és a táblában:

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

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

Az SQL-eseményindító két SqlChangeToDoItem[]tulajdonsággal rendelkező objektumtömbhöz SqlChangeToDoItem kapcsolódik:

  • elem: a módosított elem. Az elem típusának az osztályban látható táblázatsémát kell követnie ToDoItem .
  • művelet: enumerálási SqlChangeOperation érték. A lehetséges értékek: Insert, Update és Delete.

Az alábbi példa egy Java-függvényt mutat be, amelyet a tábla módosításakor hív meg a ToDo rendszer:

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élda használatra

Az Azure SQL-eseményindítóhoz további minták érhetők el a GitHub-adattárban.

A példa egy ToDoItem adatbázistáblára hivatkozik:

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

A változáskövetés engedélyezve van az adatbázisban és a táblában:

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

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

Az SQL-eseményindító két tulajdonsággal rendelkező objektumlistához kapcsolódik todoChanges:

  • elem: a módosított elem. Az elem struktúrája a táblázatsémát követi.
  • művelet: a lehetséges értékek a következők Insert: , Updateés Delete.

Az alábbi példa egy PowerShell-függvényt mutat be, amely a tábla módosításakor ToDo lesz meghívva.

A következő kötési adatok a function.json fájlban:

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

A konfigurációs szakasz ezeket a tulajdonságokat ismerteti.

A fájlban található függvény powerShell-kódjának mintája a run.ps1 következő:

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élda használatra

Az Azure SQL-eseményindítóhoz további minták érhetők el a GitHub-adattárban.

A példa egy ToDoItem adatbázistáblára hivatkozik:

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

A változáskövetés engedélyezve van az adatbázisban és a táblában:

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

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

Az SQL-eseményindító két tulajdonsággal rendelkező objektumtömböt köt todoChangesössze:

  • elem: a módosított elem. Az elem struktúrája a táblázatsémát követi.
  • művelet: a lehetséges értékek a következők Insert: , Updateés Delete.

Az alábbi példa egy JavaScript-függvényt mutat be, amely a tábla módosításakor ToDo lesz meghívva.

A következő kötési adatok a function.json fájlban:

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

A konfigurációs szakasz ezeket a tulajdonságokat ismerteti.

A fájlban található függvényhez az alábbi JavaScript-mintakód tartozik index.js :

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

Példa használatra

Az Azure SQL-eseményindítóhoz további minták érhetők el a GitHub-adattárban.

A példa egy ToDoItem adatbázistáblára hivatkozik:

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

A változáskövetés engedélyezve van az adatbázisban és a táblában:

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

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

Az SQL-eseményindító egy változóhoz todoChangeskötődik, amely két tulajdonsággal rendelkező objektumok listáját tartalmazza:

  • elem: a módosított elem. Az elem struktúrája a táblázatsémát követi.
  • művelet: a lehetséges értékek a következők Insert: , Updateés Delete.

Az alábbi példa egy Python-függvényt mutat be, amely a tábla módosításakor ToDo lesz meghívva.

A következő kötési adatok a function.json fájlban:

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

A konfigurációs szakasz ezeket a tulajdonságokat ismerteti.

A fájlban található függvényhez az alábbi Python-mintakód tartozik __init__.py :

import json
import logging

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

Attribútumok

A C#-kódtár az SqlTrigger attribútummal deklarálja az SQL-eseményindítót a függvényen, amely a következő tulajdonságokkal rendelkezik:

Attribútumtulajdonság Leírás
TableName Szükséges. Az eseményindító által figyelt tábla neve.
Csatlakozás ionStringSetting Szükséges. Annak az alkalmazásbeállításnak a neve, amely tartalmazza a módosításokat figyelt táblát tartalmazó adatbázis kapcsolati sztring. A kapcsolati sztring beállítás neve megfelel az Azure SQL- vagy SQL Server-példány kapcsolati sztring tartalmazó alkalmazásbeállításnak (local.settings.jsonhelyi fejlesztés esetén).
LeasesTableName Opcionális. A bérletek tárolására használt tábla neve. Ha nincs megadva, a bérlettábla neve Leases_{FunctionId}_{TableId}. A létrehozás módjáról itt talál további információt.

Jegyzetek

A Java-függvények futtatókörnyezeti kódtárában használja a széljegyzetet (com.microsoft.azure.functions.sql.annotation.SQLTrigger) azon @SQLTrigger paramétereken, amelyek értéke az Azure SQL-ből származna. Ez a széljegyzet a következő elemeket támogatja:

Elem Leírás
név Szükséges. Annak a paraméternek a neve, amelyhez az eseményindító kapcsolódik.
tableName Szükséges. Az eseményindító által figyelt tábla neve.
connectionStringSetting Szükséges. Annak az alkalmazásbeállításnak a neve, amely tartalmazza a módosításokat figyelt táblát tartalmazó adatbázis kapcsolati sztring. A kapcsolati sztring beállítás neve megfelel az Azure SQL- vagy SQL Server-példány kapcsolati sztring tartalmazó alkalmazásbeállításnak (local.settings.jsonhelyi fejlesztés esetén).
LeasesTableName Opcionális. A bérletek tárolására használt tábla neve. Ha nincs megadva, a bérlettábla neve Leases_{FunctionId}_{TableId}. A létrehozás módjáról itt talál további információt.

Konfiguráció

Az alábbi táblázat a function.json fájlban beállított kötéskonfigurációs tulajdonságokat ismerteti.

function.json tulajdonság Leírás
név Szükséges. Annak a paraméternek a neve, amelyhez az eseményindító kapcsolódik.
type Szükséges. A beállításnak a sqlTriggerkövetkezőnek kell lennie: .
direction Szükséges. A beállításnak a inkövetkezőnek kell lennie: .
tableName Szükséges. Az eseményindító által figyelt tábla neve.
connectionStringSetting Szükséges. Annak az alkalmazásbeállításnak a neve, amely tartalmazza a módosításokat figyelt táblát tartalmazó adatbázis kapcsolati sztring. A kapcsolati sztring beállítás neve megfelel az Azure SQL- vagy SQL Server-példány kapcsolati sztring tartalmazó alkalmazásbeállításnak (local.settings.jsonhelyi fejlesztés esetén).
LeasesTableName Opcionális. A bérletek tárolására használt tábla neve. Ha nincs megadva, a bérlettábla neve Leases_{FunctionId}_{TableId}. A létrehozás módjáról itt talál további információt.

Választható konfiguráció

Az SQL-eseményindítóhoz a következő választható beállítások konfigurálhatók:

Ez a szakasz a kötéshez elérhető konfigurációs beállításokat ismerteti a 2.x és újabb verziókban. Gépház a host.json fájlban egy függvényalkalmazás-példány összes függvényére vonatkozik. Az alábbi példában host.json fájl csak a kötés 2.x+ verziójának beállításait tartalmazza. A függvényalkalmazások konfigurációs beállításairól a 2.x és újabb verziókban host.json Azure Functionsre vonatkozó hivatkozásban talál további információt.

Beállítás Leírás
Sql_Trigger_BatchSize Az eseményindító ciklus minden iterációjával feldolgozott módosítások maximális száma, mielőtt elküldené őket az aktivált függvénynek. Az alapértelmezett érték 100.
Sql_Trigger_PollingIntervalMs A módosítások egyes kötegeinek feldolgozása közötti ezredmásodpercben bekövetkező késés. Az alapértelmezett érték 1000 (1 másodperc).
Sql_Trigger_MaxChangesPerWorker A felhasználói táblában az alkalmazás-feldolgozónként engedélyezett függőben lévő módosítások számának felső korlátja. Ha a módosítások száma meghaladja ezt a korlátot, az vertikális felskálázást eredményezhet. A beállítás csak olyan Azure-függvényalkalmazásokra vonatkozik, amelyekben engedélyezve van a futtatókörnyezetalapú skálázás. Az alapértelmezett érték 1000.

Változáskövetés beállítása (kötelező)

A változáskövetés beállítása az Azure SQL-eseményindítóval való használatra két lépésből áll. Ezek a lépések bármely olyan SQL-eszközről elvégezhetők, amely támogatja a lekérdezések futtatását, beleértve a Visual Studio Code-ot, az Azure Data Studiót vagy az SQL Server Management Studiót.

  1. A változáskövetés engedélyezése az SQL-adatbázisban annak az adatbázisnak a nevével helyettesítve your database name , amelyben a figyelendő tábla található:

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

    A CHANGE_RETENTION beállítás azt az időszakot határozza meg, amelyre vonatkozóan a változáskövetési információk (változáselőzmények) megmaradnak. Az SQL-adatbázis változáselőzményeinek megőrzése hatással lehet az eseményindító működésére. Ha például az Azure-függvény több napig ki van kapcsolva, majd újraindul, az adatbázis a fenti beállítási példában az elmúlt két napban bekövetkezett módosításokat fogja tartalmazni.

    Ezzel AUTO_CLEANUP a beállítással engedélyezheti vagy letilthatja a régi változáskövetési adatokat eltávolító törlési feladatot. Ha egy ideiglenes probléma megakadályozza az eseményindító futtatását, az automatikus törlés kikapcsolása hasznos lehet a megőrzési időnél régebbi adatok eltávolításának szüneteltetéséhez a probléma megoldásáig.

    A változáskövetési lehetőségekről az SQL dokumentációjában talál további információt.

  2. Engedélyezze a változáskövetést your table name a táblán, és helyettesítse a figyelendő tábla nevével (szükség esetén módosítsa a sémát):

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

    Az eseményindítónak olvasási hozzáféréssel kell rendelkeznie a figyelt táblán a változások és a változáskövetési rendszer táblái számára. Minden függvény-eseményindítóhoz tartozik egy változáskövetési tábla, és egy séma az_funcbérlettáblája. Ezeket a táblákat az eseményindító hozza létre, ha még nem léteznek. Ezekről az adatstruktúrákról további információt az Azure SQL kötéstár dokumentációjában talál.

Futtatókörnyezet-alapú skálázás engedélyezése

Opcionálisan a függvények automatikusan skálázhatók a felhasználói táblában feldolgozandó módosítások száma alapján. Ahhoz, hogy a függvények megfelelően skálázhatók legyenek a Prémium csomagban SQL-eseményindítók használatakor, engedélyeznie kell a futtatókörnyezeti skálázás monitorozását.

Az Azure Portalon a függvényalkalmazásban válassza a Konfiguráció lehetőséget, és a Függvény futtatókörnyezet beállításai lapon kapcsolja be a futtatókörnyezet skálázásának figyelését.

Képernyőkép az Azure Portal panelről a futtatókörnyezet skálázásának engedélyezéséhez.

Újrapróbálkozás támogatása

Az SQL-eseményindító újrapróbálkozási támogatási és bérlettábláival kapcsolatos további információk a GitHub-adattárban érhetők el.

Újrapróbálkozás indítása

Ha az indítás során kivétel történik, akkor a gazdagép futtatókörnyezete automatikusan megkísérli újraindítani az eseményindító figyelőjét exponenciális háttérstratégiával. Ezek az újrapróbálkozások mindaddig folytatódnak, amíg a figyelő sikeresen el nem indul, vagy az indítás megszakad.

Megszakadt kapcsolat újrapróbálkozásai

Ha a függvény sikeresen elindul, de egy hiba miatt megszakad a kapcsolat (például a kiszolgáló offline állapotba kerül), a függvény továbbra is megpróbálja újra megnyitni a kapcsolatot, amíg a függvény leáll vagy a kapcsolat sikeres lesz. Ha a kapcsolat sikeresen újra létrejött, akkor ott veszi fel a feldolgozási módosításokat, ahol abbahagyta.

Vegye figyelembe, hogy ezek az újrapróbálkozások nem tartoznak az SqlClient beépített tétlenségi kapcsolat újrapróbálkozási logikája elé, amely konfigurálható a ConnectRetryCountConnectRetryIntervalkapcsolati sztring beállításokkal. A rendszer először megkísérli a beépített tétlenségi kapcsolat újrapróbálkozási kísérleteit, és ha ezek nem sikerülnek újracsatlakozni, az eseményindító kötése megpróbálja újból létrehozni a kapcsolatot.

Függvénykivétel újrapróbálkozásai

Ha a felhasználói függvény kivételt tapasztal a módosítások feldolgozásakor, a jelenleg feldolgozott sorok kötegét a rendszer 60 másodperc alatt újrapróbálkozza. Ebben az időszakban a rendszer a többi módosítást a szokásos módon dolgozza fel, de a kivételt okozó köteg sorait a rendszer mindaddig figyelmen kívül hagyja, amíg az időtúllépési időszak el nem telik.

Ha a függvény végrehajtása egy adott sor során ötször meghiúsul, akkor a rendszer az összes jövőbeli módosítás esetében teljesen figyelmen kívül hagyja ezt a sort. Mivel a köteg sorai nem determinisztikusak, a sikertelen kötegek sorai a későbbi meghívások során különböző kötegekben végződhetnek. Ez azt jelenti, hogy a sikertelen köteg nem minden sorát hagyja figyelmen kívül. Ha a köteg más sorai okozzák a kivételt, a "jó" sorok egy másik kötegbe kerülhetnek, amely a jövőbeni meghívások során nem hiúsul meg.

Következő lépések