Pemicu Azure SQL untuk Functions

  • Artikel

Catatan

Dalam fungsi rencana konsumsi, penskalaan otomatis tidak didukung untuk pemicu SQL. Jika proses penskalaan otomatis menghentikan fungsi, semua pemrosesan peristiwa akan berhenti dan perlu dimulai ulang secara manual.

Gunakan paket premium atau khusus untuk menskalakan manfaat dengan pemicu SQL.

Pemicu Azure SQL menggunakan fungsionalitas pelacakan perubahan SQL untuk memantau tabel SQL untuk perubahan dan memicu fungsi saat baris dibuat, diperbarui, atau dihapus. Untuk detail konfigurasi untuk pelacakan perubahan untuk digunakan dengan pemicu Azure SQL, lihat Menyiapkan pelacakan perubahan. Untuk informasi tentang detail penyiapan ekstensi Azure SQL untuk Azure Functions, lihat gambaran umum pengikatan SQL.

Keputusan penskalaan pemicu Azure SQL untuk paket Konsumsi dan Premium dilakukan melalui penskalaan berbasis target. Untuk informasi selengkapnya, lihat Penskalaan berbasis target.

Gambaran Umum Fungsionalitas

Pengikatan pemicu Azure SQL menggunakan perulangan polling untuk memeriksa perubahan, memicu fungsi pengguna saat perubahan terdeteksi. Pada tingkat tinggi, perulangan terlihat seperti ini:

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
}

Perubahan diproses dalam urutan perubahannya dilakukan, dengan perubahan terlama sedang diproses terlebih dahulu. Beberapa catatan tentang pemrosesan perubahan:

  1. Jika perubahan pada beberapa baris dilakukan sekaligus, urutan yang tepat bahwa baris dikirim ke fungsi didasarkan pada urutan yang dikembalikan oleh fungsi CHANGETABLE
  2. Perubahan "di-batch" bersama-sama untuk baris. Jika beberapa perubahan dilakukan pada baris antara setiap iterasi perulangan, maka hanya satu entri perubahan yang ada untuk baris tersebut yang akan menampilkan perbedaan antara status terakhir yang diproses dan status saat ini
  3. Jika perubahan dilakukan pada sekumpulan baris, lalu kumpulan perubahan lain dilakukan pada setengah dari baris yang sama tersebut, maka setengah dari baris yang tidak diubah untuk kedua kalinya diproses terlebih dahulu. Logika pemrosesan ini disebabkan oleh catatan di atas dengan perubahan yang di-batch - pemicu hanya akan melihat perubahan "terakhir" yang dibuat dan menggunakannya untuk urutan pemrosesannya

Untuk informasi selengkapnya tentang pelacakan perubahan dan cara penggunaannya oleh aplikasi seperti pemicu Azure SQL, lihat bekerja dengan pelacakan perubahan .

Contoh penggunaan

Sampel lainnya untuk pemicu Azure SQL tersedia di repositori GitHub.

Contoh mengacu pada ToDoItem kelas dan tabel database terkait:

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

Pelacakan perubahan diaktifkan pada database dan pada tabel:

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

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

Pemicu SQL mengikat ke IReadOnlyList<SqlChange<T>>, daftar SqlChange objek masing-masing dengan dua properti:

  • Item: item yang diubah. Jenis item harus mengikuti skema tabel seperti yang terlihat di ToDoItem kelas .
  • Operasi: nilai dari SqlChangeOperation enum. Nilai yang mungkin adalah Insert, Update, dan Delete.

Contoh berikut menunjukkan fungsi C# yang dipanggil saat ada perubahan pada ToDo tabel:

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

Contoh penggunaan

Sampel lainnya untuk pemicu Azure SQL tersedia di repositori GitHub.

Contohnya mengacu pada ToDoItem kelas, SqlChangeToDoItem kelas, SqlChangeOperation enum, dan tabel database terkait:

Dalam file ToDoItem.javaterpisah :

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

Dalam file SqlChangeToDoItem.javaterpisah :

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

Dalam file SqlChangeOperation.javaterpisah :

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

Pelacakan perubahan diaktifkan pada database dan pada tabel:

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

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

Pemicu SQL mengikat ke SqlChangeToDoItem[], array SqlChangeToDoItem objek masing-masing dengan dua properti:

  • item: item yang diubah. Jenis item harus mengikuti skema tabel seperti yang terlihat di ToDoItem kelas .
  • operation: nilai dari SqlChangeOperation enum. Nilai yang mungkin adalah Insert, Update, dan Delete.

Contoh berikut menunjukkan fungsi Java yang dipanggil saat ada perubahan pada ToDo tabel:

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

Contoh penggunaan

Sampel lainnya untuk pemicu Azure SQL tersedia di repositori GitHub.

Contoh mengacu pada ToDoItem tabel database:

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

Pelacakan perubahan diaktifkan pada database dan pada tabel:

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

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

Pemicu SQL mengikat ke todoChanges, daftar objek masing-masing dengan dua properti:

  • item: item yang diubah. Struktur item akan mengikuti skema tabel.
  • operasi: nilai yang mungkin adalah Insert, Update, dan Delete.

Contoh berikut menunjukkan fungsi PowerShell yang dipanggil saat ada perubahan pada ToDo tabel.

Berikut ini adalah mengikat data dalam file function.json:

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

Bagian konfigurasi menjelaskan properti ini.

Berikut ini adalah contoh kode PowerShell untuk fungsi dalam run.ps1 file:

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"

Contoh penggunaan

Sampel lainnya untuk pemicu Azure SQL tersedia di repositori GitHub.

Contoh mengacu pada ToDoItem tabel database:

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

Pelacakan perubahan diaktifkan pada database dan pada tabel:

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

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

Pemicu SQL mengikat todoChanges, array objek masing-masing dengan dua properti:

  • item: item yang diubah. Struktur item akan mengikuti skema tabel.
  • operasi: nilai yang mungkin adalah Insert, Update, dan Delete.

Contoh berikut menunjukkan fungsi JavaScript yang dipanggil saat ada perubahan pada ToDo tabel.

Berikut ini adalah mengikat data dalam file function.json:

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

Bagian konfigurasi menjelaskan properti ini.

Berikut ini adalah contoh kode JavaScript untuk fungsi dalam index.js file:

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

Contoh penggunaan

Sampel lainnya untuk pemicu Azure SQL tersedia di repositori GitHub.

Contoh mengacu pada ToDoItem tabel database:

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

Pelacakan perubahan diaktifkan pada database dan pada tabel:

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

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

Pemicu SQL mengikat ke variabel todoChanges, daftar objek masing-masing dengan dua properti:

  • item: item yang diubah. Struktur item akan mengikuti skema tabel.
  • operasi: nilai yang mungkin adalah Insert, Update, dan Delete.

Contoh berikut menunjukkan fungsi Python yang dipanggil saat ada perubahan pada ToDo tabel.

Berikut ini adalah mengikat data dalam file function.json:

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

Bagian konfigurasi menjelaskan properti ini.

Berikut ini adalah contoh kode Python untuk fungsi dalam __init__.py file:

import json
import logging

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

Atribut

Pustaka C# menggunakan atribut SqlTrigger untuk mendeklarasikan pemicu SQL pada fungsi , yang memiliki properti berikut:

Properti atribut Deskripsi
TableName Harus diisi. Nama tabel yang dipantau oleh pemicu.
ConnectionStringSetting Harus diisi. Nama pengaturan aplikasi yang berisi string koneksi untuk database yang berisi tabel yang dipantau untuk perubahan. Nama pengaturan string koneksi sesuai dengan pengaturan aplikasi (di local.settings.json untuk pengembangan lokal) yang berisi string koneksi ke instans Azure SQL atau SQL Server.
LeasesTableName Opsional. Nama tabel yang digunakan untuk menyimpan sewa. Jika tidak ditentukan, nama tabel sewa akan Leases_{FunctionId}_{TableId}. Informasi lebih lanjut tentang bagaimana ini dihasilkan dapat ditemukan di sini.

Anotasi

Di pustaka runtime fungsi Java, gunakan @SQLTrigger anotasi (com.microsoft.azure.functions.sql.annotation.SQLTrigger) pada parameter yang nilainya akan berasal dari Azure SQL. Anotasi ini mendukung elemen berikut:

Elemen Deskripsi
nama Harus diisi. Nama parameter yang diikat pemicu.
tableName Harus diisi. Nama tabel yang dipantau oleh pemicu.
connectionStringSetting Harus diisi. Nama pengaturan aplikasi yang berisi string koneksi untuk database yang berisi tabel yang dipantau untuk perubahan. Nama pengaturan string koneksi sesuai dengan pengaturan aplikasi (di local.settings.json untuk pengembangan lokal) yang berisi string koneksi ke instans Azure SQL atau SQL Server.
LeasesTableName Opsional. Nama tabel yang digunakan untuk menyimpan sewa. Jika tidak ditentukan, nama tabel sewa akan Leases_{FunctionId}_{TableId}. Informasi lebih lanjut tentang bagaimana ini dihasilkan dapat ditemukan di sini.

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json Deskripsi
nama Harus diisi. Nama parameter yang diikat pemicu.
jenis Harus diisi. Harus diatur ke sqlTrigger.
arah Harus diisi. Harus diatur ke in.
tableName Harus diisi. Nama tabel yang dipantau oleh pemicu.
connectionStringSetting Harus diisi. Nama pengaturan aplikasi yang berisi string koneksi untuk database yang berisi tabel yang dipantau untuk perubahan. Nama pengaturan string koneksi sesuai dengan pengaturan aplikasi (di local.settings.json untuk pengembangan lokal) yang berisi string koneksi ke instans Azure SQL atau SQL Server.
LeasesTableName Opsional. Nama tabel yang digunakan untuk menyimpan sewa. Jika tidak ditentukan, nama tabel sewa akan Leases_{FunctionId}_{TableId}. Informasi lebih lanjut tentang bagaimana ini dihasilkan dapat ditemukan di sini.

Konfigurasi Opsional

Pengaturan opsional berikut dapat dikonfigurasi untuk pemicu SQL:

Bagian ini menjelaskan pengaturan konfigurasi yang tersedia untuk pengikatan ini dalam versi 2.x dan yang lebih tinggi. Pengaturan dalam file host.json berlaku untuk semua fungsi dalam instans aplikasi fungsi. Contohnya file host.json di bawah ini hanya berisi pengaturan versi 2.x+ untuk pengikatan ini. Untuk informasi selengkapnya tentang pengaturan konfigurasi aplikasi fungsi dalam versi 2.x dan seterusnya, lihat referensi host.json untuk Azure Functions.

Pengaturan Deskripsi
Sql_Trigger_BatchSize Jumlah maksimum perubahan yang diproses dengan setiap iterasi perulangan pemicu sebelum dikirim ke fungsi yang dipicu. Nilai default adalah 100.
Sql_Trigger_PollingIntervalMs Penundaan dalam milidetik antara memproses setiap batch perubahan. Nilai defaultnya adalah 1000 (1 detik).
Sql_Trigger_MaxChangesPerWorker Batas atas jumlah perubahan yang tertunda dalam tabel pengguna yang diizinkan per pekerja aplikasi. Jika jumlah perubahan melebihi batas ini, hal ini dapat mengakibatkan peluasan skala. Pengaturan hanya berlaku untuk Azure Function Apps dengan penskalaan berbasis runtime diaktifkan. Nilai defaultnya adalah 1000.

Menyiapkan pelacakan perubahan (diperlukan)

Menyiapkan pelacakan perubahan untuk digunakan dengan pemicu Azure SQL memerlukan dua langkah. Langkah-langkah ini dapat diselesaikan dari alat SQL apa pun yang mendukung menjalankan kueri, termasuk Visual Studio Code, Azure Data Studio, atau SQL Server Management Studio.

  1. Aktifkan pelacakan perubahan pada database SQL, ganti your database name dengan nama database tempat tabel yang akan dipantau berada:

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

    Opsi CHANGE_RETENTION menentukan periode waktu di mana informasi pelacakan perubahan (riwayat perubahan) disimpan. Retensi riwayat perubahan oleh database SQL dapat memengaruhi fungsionalitas pemicu. Misalnya, jika Fungsi Azure dinonaktifkan selama beberapa hari lalu dilanjutkan, database akan berisi perubahan yang terjadi dalam dua hari terakhir dalam contoh penyiapan di atas.

    Opsi AUTO_CLEANUP ini digunakan untuk mengaktifkan atau menonaktifkan tugas pembersihan yang menghapus informasi pelacakan perubahan lama. Jika masalah sementara yang mencegah pemicu berjalan, menonaktifkan pembersihan otomatis dapat berguna untuk menjeda penghapusan informasi yang lebih lama dari periode retensi hingga masalah diselesaikan.

    Informasi selengkapnya tentang opsi pelacakan perubahan tersedia dalam dokumentasi SQL.

  2. Aktifkan pelacakan perubahan pada tabel, ganti your table name dengan nama tabel yang akan dipantau (mengubah skema jika sesuai):

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

    Pemicu harus memiliki akses baca pada tabel yang dipantau untuk perubahan dan tabel sistem pelacakan perubahan. Setiap pemicu fungsi memiliki tabel pelacakan perubahan terkait dan tabel sewa dalam skema az_func. Tabel ini dibuat oleh pemicu jika belum ada. Informasi selengkapnya tentang struktur data ini tersedia dalam dokumentasi pustaka pengikatan Azure SQL.

Aktifkan penskalakan berbasis runtime

Secara opsional, fungsi Anda dapat menskalakan secara otomatis berdasarkan jumlah perubahan yang tertunda untuk diproses dalam tabel pengguna. Untuk memungkinkan fungsi Anda menskalakan dengan benar pada paket Premium saat menggunakan pemicu SQL, Anda perlu mengaktifkan pemantauan skala runtime.

Di portal Azure, di aplikasi fungsi Anda, pilih Konfigurasi dan pada tab Pengaturan runtime fungsi, aktifkan Pemantauan skala runtime menjadi Aktif.

Cuplikan layar panel portal Azure untuk mengaktifkan penskalaan runtime.

Coba lagi dukungan

Informasi lebih lanjut tentang dukungan coba lagi pemicu SQL dan tabel sewa tersedia di repositori GitHub.

Percobaan ulang startup

Jika pengecualian terjadi selama startup, maka runtime host secara otomatis mencoba memulai ulang listener pemicu dengan strategi backoff eksponensial. Percobaan ulang ini berlanjut hingga pendengar berhasil dimulai atau pengaktifan dibatalkan.

Percobaan ulang koneksi yang rusak

Jika fungsi berhasil dimulai tetapi kemudian kesalahan menyebabkan koneksi terputus (seperti server offline) maka fungsi terus mencoba dan membuka kembali koneksi sampai fungsi dihentikan atau koneksi berhasil. Jika koneksi berhasil dibuat ulang, koneksi akan mengambil perubahan pemrosesan yang ditinggalkannya.

Perhatikan bahwa percobaan ulang ini berada di luar logika coba lagi koneksi menganggur bawaan yang dimiliki SqlClient yang dapat dikonfigurasi dengan ConnectRetryCount opsi dan ConnectRetryIntervalstring koneksi. Percobaan ulang koneksi menganggur bawaan dicoba terlebih dahulu dan jika mereka gagal terhubung kembali maka pengikatan pemicu mencoba untuk membangun kembali koneksi itu sendiri.

Percobaan ulang pengecualian fungsi

Jika pengecualian terjadi dalam fungsi pengguna saat memproses perubahan, maka batch baris yang saat ini sedang diproses dicoba lagi dalam 60 detik. Perubahan lain diproses seperti biasa selama waktu ini, tetapi baris dalam batch yang menyebabkan pengecualian diabaikan sampai periode batas waktu telah berlalu.

Jika eksekusi fungsi gagal lima kali berturut-turut untuk baris tertentu, baris tersebut sepenuhnya diabaikan untuk semua perubahan di masa mendatang. Karena baris dalam batch tidak deterministik, baris dalam batch yang gagal mungkin berakhir dalam batch yang berbeda dalam pemanggilan berikutnya. Ini berarti bahwa tidak semua baris dalam batch yang gagal harus diabaikan. Jika baris lain dalam batch adalah baris yang menyebabkan pengecualian, baris "baik" mungkin berakhir di batch yang berbeda yang tidak gagal dalam pemanggilan di masa mendatang.

Langkah berikutnya