Azure Database for MySQL-utlösarbindning för Azure Functions

Azure Database for MySQL-utlösarbindningar övervakar användartabellen efter ändringar (infogningar och uppdateringar) och anropar funktionen med uppdaterade raddata.

Azure Database for MySQL-utlösarbindningar använder az_func_updated_at och kolumndata för att övervaka användartabellen för ändringar. Därför måste du ändra tabellstrukturen för att tillåta ändringsspårning i MySQL-tabellen innan du använder utlösarsupporten. Du kan aktivera ändringsspårningen i en tabell via följande fråga. Du kan till exempel aktivera den i Products tabellen:

ALTER TABLE Products
ADD az_func_updated_at TIMESTAMP DEFAULT 
CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP;

Tabellen för lån innehåller alla kolumner som motsvarar den primära nyckeln från användartabellen och ytterligare tre kolumner: az_func_AttemptCount, az_func_LeaseExpirationTimeoch az_func_SyncCompletedTime. Om någon av primärnyckelkolumnerna har samma namn är resultatet ett felmeddelande som visar konflikter. I det här fallet måste de listade primärnyckelkolumnerna byta namn för att utlösaren ska fungera.

Översikt över funktioner

När utlösarfunktionen startar initieras två separata loopar: ändringssökningsloopen och förnyelseloopen för lån. Dessa loopar körs kontinuerligt tills funktionen stoppas.

Azure Database for MySQL-utlösarbindningen använder avsökningsloopen för att söka efter ändringar. Avsökningsloopen utlöser användarfunktionen när den identifierar ändringar. På hög nivå ser loopen ut som i det här exemplet:

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

Ändringar bearbetas i den ordning de görs. De äldsta ändringarna bearbetas först. Tänk på dessa punkter om ändringsbearbetning:

  • Om ändringar sker på flera rader samtidigt baseras den exakta ordning i vilken de skickas till funktionen på kolumnens stigande ordning az_func_updated_at och primärnyckelkolumnerna.
  • Ändringar batchas för en rad. Om flera ändringar sker på en rad mellan varje iteration av loopen beaktas endast den senaste ändringsposten som finns för den raden.

Kommentar

För närvarande stöds inte hanterade identiteter för anslutningar mellan Azure Functions och Azure Database for MySQL.

Exempel på användning

Fler exempel för Azure Database for MySQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en Product klass och en motsvarande databastabell:

namespace AzureMySqlSamples.Common
{
    public class Product
    {
        public int? ProductId { get; set; }

        public string Name { get; set; }

        public int Cost { get; set; }

        public override bool Equals(object obj)
        {
            if (obj is Product)
            {
                var that = obj as Product;
                return this.ProductId == that.ProductId && this.Name == that.Name && this.Cost == that.Cost;
            }
            return false;
        }
    }
DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Du aktiverar ändringsspårning i databasen genom att lägga till en kolumn i tabellen:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Azure Database for MySQL-utlösaren binder till IReadOnlyList<MySqlChange<T>>, som listar MySqlChange objekt. Varje objekt har två egenskaper:

  • Item: Objektet som ändrades. Typen av objekt ska följa tabellschemat, enligt vad som visas i ToDoItem klassen.
  • Operation: Ett värde från MySqlChangeOperation uppräkningen. Det möjliga värdet är Update för både infogningar och uppdateringar.

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

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.MySql;
using Microsoft.Extensions.Logging;
using AzureMySqlSamples.Common;

namespace AzureMySqlSamples.TriggerBindingSamples
{
        private static readonly Action<ILogger, string, Exception> _loggerMessage = LoggerMessage.Define<string>(LogLevel.Information, eventId: new EventId(0, "INFO"), formatString: "{Message}");

        [Function(nameof(ProductsTrigger))]
        public static void Run(
            [MySqlTrigger("Products", "MySqlConnectionString")]
            IReadOnlyList<MySqlChange<Product>> changes, FunctionContext context)
        {
            ILogger logger = context.GetLogger("ProductsTrigger");
            // The output is used to inspect the trigger binding parameter in test methods.
            foreach (MySqlChange<Product> change in changes)
            {
                Product product = change.Item;
                _loggerMessage(logger, $"Change operation: {change.Operation}", null);
                _loggerMessage(logger, $"Product Id: {product.ProductId}, Name: {product.Name}, Cost: {product.Cost}", null);
            }
        }
}

Exempel på användning

Fler exempel för Azure Database for MySQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en Product klass, en MySqlChangeProduct klass, en MySqlChangeOperation uppräkning och en motsvarande databastabell.

I en separat fil med namnet Product.java:

package com.function.Common;

import com.fasterxml.jackson.annotation.JsonProperty;

public class Product {
    @JsonProperty("ProductId")
    private int ProductId;
    @JsonProperty("Name")
    private String Name;
    @JsonProperty("Cost")
    private int Cost;

    public Product() {
    }

    public Product(int productId, String name, int cost) {
        ProductId = productId;
        Name = name;
        Cost = cost;
    }
}

I en separat fil med namnet MySqlChangeProduct.java:

package com.function.Common;

public class MySqlChangeProduct {
    private MySqlChangeOperation Operation;
    private Product Item;

    public MySqlChangeProduct() {
    }

    public MySqlChangeProduct(MySqlChangeOperation operation, Product item) {
        this.Operation = operation;
        this.Item = item;
    }
}

I en separat fil med namnet MySqlChangeOperation.java:

package com.function.Common;

import com.google.gson.annotations.SerializedName;

public enum MySqlChangeOperation {
    @SerializedName("0")
    Update
}
DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Du aktiverar ändringsspårning i databasen genom att lägga till följande kolumn i tabellen:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Azure Database for MySQL-utlösaren binder till MySqlChangeProduct[], vilket är en matris med MySqlChangeProduct objekt. Varje objekt har två egenskaper:

  • item: Objektet som ändrades. Typen av objekt ska följa tabellschemat, enligt vad som visas i Product klassen.
  • operation: Ett värde från MySqlChangeOperation uppräkningen. Det möjliga värdet är Update för både infogningar och uppdateringar.

I följande exempel visas en Java-funktion som anropas när ändringar sker i Product tabellen:

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 */

package com.function;

import com.microsoft.azure.functions.ExecutionContext;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.mysql.annotation.MySqlTrigger;
import com.function.Common.MySqlChangeProduct;
import com.google.gson.Gson;

import java.util.logging.Level;

public class ProductsTrigger {
    @FunctionName("ProductsTrigger")
    public void run(
            @MySqlTrigger(
                name = "changes",
                tableName = "Products",
                connectionStringSetting = "MySqlConnectionString")
                MySqlChangeProduct[] changes,
            ExecutionContext context) {

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

Exempel på användning

Fler exempel för Azure Database for MySQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en Product databastabell:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Du aktiverar ändringsspårning i databasen genom att lägga till en kolumn i tabellen:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Azure Database for MySQL-utlösaren binder till Product, som listar objekt. Varje objekt har två egenskaper:

  • item: Objektet som ändrades. Objektets struktur följer tabellschemat.
  • operation: Det möjliga värdet är Update för både infogningar och uppdateringar.

I följande exempel visas en PowerShell-funktion som anropas när ändringar sker i Product tabellen.

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

{
    "bindings": [
      {
        "name": "changes",
        "type": "mysqlTrigger",
        "direction": "in",
        "tableName": "Products",
        "connectionStringSetting": "MySqlConnectionString"
      }
    ],
    "disabled": false
  }

I avsnittet Konfiguration beskrivs dessa egenskaper.

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

using namespace System.Net

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

Exempel på användning

Fler exempel för Azure Database for MySQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en Product databastabell:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Du aktiverar ändringsspårning i databasen genom att lägga till en kolumn i tabellen:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Azure Database for MySQL-utlösaren binder till Changes, vilket är en matris med objekt. Varje objekt har två egenskaper:

  • item: Objektet som ändrades. Objektets struktur följer tabellschemat.
  • operation: Det möjliga värdet är Update för både infogningar och uppdateringar.

I följande exempel visas en JavaScript-funktion som anropas när ändringar sker i Product tabellen.

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

{
    "bindings": [
      {
        "name": "changes",
        "type": "mysqlTrigger",
        "direction": "in",
        "tableName": "Products",
        "connectionStringSetting": "MySqlConnectionString",
      }
    ],
    "disabled": false
  }

I avsnittet Konfiguration beskrivs dessa egenskaper.

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

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

Exempel på användning

Fler exempel för Azure Database for MySQL-utlösaren finns på GitHub-lagringsplatsen.

Exemplet refererar till en Product databastabell:

DROP TABLE IF EXISTS Products;

CREATE TABLE Products (
  ProductId int PRIMARY KEY,
  Name varchar(100) NULL,
  Cost int NULL
);

Du aktiverar ändringsspårning i databasen genom att lägga till en kolumn i tabellen:

ALTER TABLE <table name>  
ADD COLUMN az_func_updated_at TIMESTAMP 
DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Kommentar

Du måste använda Azure Functions version 1.22.0b4 för Python.

Azure Database for MySQL-utlösaren binder till en variabel med namnet Product, som listar objekt. Varje objekt har två egenskaper:

  • item: Objektet som ändrades. Objektets struktur följer tabellschemat.
  • operation: Det möjliga värdet är Update för både infogningar och uppdateringar.

I följande exempel visas en Python-funktion som anropas när ändringar sker i Product tabellen.

Följande exempel är Python-exempelkod för function_app.py-filen:

import json
import logging
import azure.functions as func

app = func.FunctionApp()

# The function is triggered when a change (insert, update)
# is made to the Products table.
@app.function_name(name="ProductsTrigger")
@app.mysql_trigger(arg_name="products",
table_name="Products",
connection_string_setting="MySqlConnectionString")

def products_trigger(products: str) -> None:
logging.info("MySQL Changes: %s", json.loads(products))

Attribut

Attributegenskap beskrivning
TableName Obligatoriskt. Namnet på tabellen som utlösaren övervakar.
ConnectionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträngen för databasen som innehåller tabellen som övervakas för ändringar. Namnet på inställningen för anslutningssträngen motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträngen till Azure Database for MySQL.
LeasesTableName Valfritt. Namnet på tabellen för lagring av lån. Om det inte anges är Leases_{FunctionId}_{TableId}namnet .

Kommentarer

I Java Functions-körningsbiblioteket använder du anteckningen @MySQLTrigger för parametrar vars värden skulle komma från Azure Database for MySQL. Den här kommentaren stöder följande element:

Komponent beskrivning
name Obligatoriskt. Namnet på parametern som utlösaren binder till.
tableName Obligatoriskt. Namnet på tabellen som utlösaren övervakar.
connectionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträngen för databasen som innehåller tabellen som övervakas för ändringar. Namnet på inställningen för anslutningssträngen motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträngen till Azure Database for MySQL.
LeasesTableName Valfritt. Namnet på tabellen för lagring av lån. Om det inte anges är Leases_{FunctionId}_{TableId}namnet .

Konfiguration

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

Fastighet beskrivning
name Obligatoriskt. Namnet på parametern som utlösaren binder till.
type Obligatoriskt. Måste anges till MysqlTrigger.
direction Obligatoriskt. Måste anges till in.
tableName Obligatoriskt. Namnet på tabellen som utlösaren övervakar.
connectionStringSetting Obligatoriskt. Namnet på en appinställning som innehåller anslutningssträngen för databasen som innehåller tabellen som övervakas för ändringar. Namnet på inställningen för anslutningssträngen motsvarar programinställningen (i local.settings.json för lokal utveckling) som innehåller anslutningssträngen till Azure Database for MySQL.
LeasesTableName Valfritt. Namnet på tabellen för lagring av lån. Om det inte anges är Leases_{FunctionId}_{TableId}namnet .

Valfri konfiguration

Du kan konfigurera följande valfria inställningar för Azure Database for MySQL-utlösaren för lokal utveckling eller för molndistributioner.

host.json

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 host.json-filen gäller för alla funktioner i en funktionsappinstans. Mer information om konfigurationsinställningar för funktionsappar finns ihost.json referens för Azure Functions.

Inställning Standardvärde beskrivning
MaxBatchSize 100 Det maximala antalet ändringar som bearbetas med varje iteration av utlösarloopen innan de skickas till den utlösta funktionen.
PollingIntervalMs 1000 Fördröjningen i millisekunder mellan bearbetningen av varje batch med ändringar. (1 000 ms är 1 sekund.)
MaxChangesPerWorker 1000 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-funktionsappar med körningsdriven skalning aktiverad.

Exempel på host.json fil

Här är ett exempel host.json fil med de valfria inställningarna:

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

local.setting.json

I local.settings.json-filen lagras appinställningar och inställningar som lokala utvecklingsverktyg använder. Inställningar i local.settings.json-filen används endast när du kör projektet lokalt. När du publicerar projektet i Azure måste du också lägga till nödvändiga inställningar i appinställningarna för funktionsappen.

Viktigt!

Eftersom den local.settings.json filen kan innehålla hemligheter, till exempel anslutningssträngar, bör du aldrig lagra den på en fjärrlagringsplats. Verktyg som stöder Azure Functions tillhandahåller sätt att synkronisera inställningar i local.settings.json-filen med appinställningarna i funktionsappen som projektet distribueras till.

Inställning Standardvärde beskrivning
MySql_Trigger_BatchSize 100 Det maximala antalet ändringar som bearbetas med varje iteration av utlösarloopen innan de skickas till den utlösta funktionen.
MySql_Trigger_PollingIntervalMs 1000 Fördröjningen i millisekunder mellan bearbetningen av varje batch med ändringar. (1 000 ms är 1 sekund.)
MySql_Trigger_MaxChangesPerWorker 1000 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-funktionsappar med körningsdriven skalning aktiverad.

Exempel på local.settings.json fil

Här är ett exempel local.settings.json fil med valfria inställningar:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "MySqlConnectionString": "",
    "MySql_Trigger_MaxBatchSize": 300,
    "MySql_Trigger_PollingIntervalMs": 1000,
    "MySql_Trigger_MaxChangesPerWorker": 100
  }
}

Konfigurera ändringsspårning (krävs)

När du konfigurerar ändringsspårning för användning med Azure Database for MySQL-utlösaren måste du lägga till en kolumn i en tabell med hjälp av en funktion. Du kan utföra de här stegen från alla MySQL-verktyg som stöder körning av frågor, inklusive Visual Studio Code eller Azure Data Studio.

Azure Database for MySQL-utlösarbindningar använder az_func_updated_at och kolumndata för att övervaka användartabellen för ändringar. Därför måste du ändra tabellstrukturen för att tillåta ändringsspårning i MySQL-tabellen innan du använder utlösarsupporten. Du kan aktivera ändringsspårningen i en tabell via följande fråga. Du kan till exempel aktivera den i Products tabellen:

ALTER TABLE Products;
ADD az_func_updated_at 
TIMESTAMP DEFAULT CURRENT_TIMESTAMP 
ON UPDATE CURRENT_TIMESTAMP;

Tabellen för lån innehåller alla kolumner som motsvarar primärnyckeln från användartabellen och ytterligare två kolumner: az_func_AttemptCount och az_func_LeaseExpirationTime. Om någon av primärnyckelkolumnerna har samma namn är resultatet ett felmeddelande som visar konflikter. I det här fallet måste de listade primärnyckelkolumnerna byta namn för att utlösaren ska fungera.

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 Azure Database for MySQL-utlösare måste du aktivera skalningsövervakning för körning.

  1. I Azure-portalen går du till funktionsappen och väljer Konfiguration.

  2. På fliken Inställningar för funktionskörning väljer du för Körningsskalningsövervakning.

    Skärmbild av Azure Portal-området för aktivering av körningsskalning.

Återförsöksstöd

Å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.

Återförsök av funktionsfel

Om ett undantag inträffar i användarfunktionen under ändringsbearbetningen görs den batch med rader som för närvarande bearbetas igen om 60 sekunder. Andra ändringar bearbetas som vanligt under den här tiden, men de rader i batchen som orsakade undantaget ignoreras tills tidsgränsen förflutit.

Om funktionskörningen misslyckas fem gånger i följd för en viss rad ignoreras den raden 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 här beteendet innebär att inte alla rader i den misslyckade batchen nödvändigtvis ignoreras. Om andra rader i batchen orsakade undantaget kan de "bra" raderna hamna i en annan batch som inte misslyckas i framtida anrop.