Configura lo streaming di eventi di modifica (anteprima) su Hub eventi di Azure

Si applica a: SQL Server 2025 (17.x) Database SQL di AzureIstanza gestita di SQL di AzureDatabase SQL in Microsoft Fabric

Questo articolo descrive come configurare la funzione change event streaming (CES) in SQL Server 2025 (17.x), database SQL di Azure, Istanza gestita di SQL di Azure e SQL database in Microsoft Fabric per lo streaming verso Hub eventi di Azure.

Per configurare CES a Fabric Eventstream, vedi Stream to Fabric Eventstream.

Annotazioni

Lo streaming degli eventi di modifica è attualmente in anteprima e presenta differenze di supportabilità tra i prodotti. Durante l'anteprima, questa funzionalità è soggetta a modifiche.

Procedura per lo streaming degli eventi di cambiamento

  1. Usare un Hub eventi di Azure namespace esistente o crearne uno nuovo, e un'istanza di Event Hubs. L'istanza di Hub eventi riceve gli eventi.
  2. Abilitare lo streaming di eventi di modifica per un database utente.
  3. Crea un gruppo di streaming. Con questo gruppo, configurare la destinazione, le credenziali, i limiti delle dimensioni dei messaggi e lo schema di partizionamento.
  4. Aggiungi una o più tabelle al gruppo di streaming.

Ogni passaggio è descritto in dettaglio nelle sezioni seguenti di questo articolo.

Prerequisiti

Importante

Dal 15 agosto 2026, il protocollo AMQP è deprecato per lo streaming di eventi di cambiamento (CES). Ci sono differenze tra le piattaforme. Per i passaggi e le tempistiche della migrazione, consulta deprecazione del protocollo AMQP.

Per configurare lo streaming di eventi di modifica, sono necessarie le risorse, le autorizzazioni e la configurazione seguenti:

Quando si usa lo streaming di eventi di modifica con Istanza gestita di SQL di Azure, l'istanza deve essere configurata con i criteri di aggiornamento di SQL Server 2025 o Always-up-to-date.

Configurare Hub eventi di Azure

Per informazioni su come creare Hub eventi di Azure, vedere Creare un hub eventi usando il portale di Azure.

Controllo di accesso di Hub eventi di Azure

Configurare il controllo di accesso per la risorsa SQL in Hub eventi di Azure. L'autenticazione di Microsoft Entra è il metodo più sicuro. CES supporta l'autenticazione Microsoft Entra in database SQL di Azure e Istanza gestita di SQL di Azure. Per SQL Server 2025, l'autenticazione Microsoft Entra è supportata a partire da Cumulative Update 3 (CU3) per le istanze abilitate da Azure Arc o su una VM Azure. Sebbene i criteri di accesso condiviso siano supportati, usarli solo se l'autenticazione di Microsoft Entra non è un'opzione.

I criteri di accesso condiviso forniscono l'autenticazione e l'autorizzazione per Hub eventi di Azure. Ogni criterio di accesso condiviso richiede un nome, un livello di accesso (Manage, Sendo Listen) e un'associazione di risorse (spazio dei nomi di Hub eventi o un'istanza specifica di Hub eventi). I criteri a livello di istanza offrono maggiore sicurezza seguendo il principio dei privilegi minimi. Sebbene i prodotti SQL motore di database supportino politiche di accesso condiviso, utilizza l'autenticazione Microsoft Entra ogni volta che è possibile, poiché offre una maggiore sicurezza.

Se usi una policy di accesso condiviso per l'autenticazione e l'autorizzazione, i client che inviano dati a un'istanza Event Hub devono fornire il nome della policy che vogliono utilizzare, insieme alla chiave di servizio della policy.

Per configurare lo streaming su Hub eventi di Azure, crea o riutilizza una policy di accesso condiviso con il permesso di invio. Puoi autenticarti usando una chiave di servizio (chiave primaria o secondaria valore).

Annotazioni

Per una maggiore sicurezza, usare il controllo degli accessi in base a Microsoft Entra quando possibile. Se il controllo degli accessi basato su Microsoft Entra non è possibile e stai usando politiche di accesso condiviso, la buona pratica è ruotare periodicamente la chiave del servizio. Archiviare tutti i segreti in modo sicuro usando Azure Key Vault o un servizio simile.

Definire un criterio

Serve una policy di accesso condiviso con diritti di invio . È possibile:

  • Creare un nuovo criterio

    oppure

  • Usare un criterio esistente

Annotazioni

La politica deve avere diritti di invio.

Una volta definito il criterio, annota il valore della chiave di servizio. Lo usi, insieme al nome della policy, quando crei la credenziale in SQL prima di configurare CES.

Abilitare e configurare lo streaming degli eventi di modifica

Importante

Dal 15 agosto 2026, il protocollo AMQP è deprecato per lo streaming di eventi di cambiamento (CES). Ci sono differenze tra le piattaforme. Per i passaggi e le tempistiche della migrazione, consulta deprecazione del protocollo AMQP.

Per abilitare e configurare lo streaming di eventi di modifica, modificare il contesto del database nel database utente e quindi seguire questa procedura:

  1. Se non è già configurato, imposta il database sul modello di recupero completo.
  2. Creare una chiave master e una credenziale con ambito database.
  3. Abilitare lo streaming di eventi.
  4. Crea il gruppo di streaming.
  5. Aggiungi una o più tabelle al gruppo di streaming.

I seguenti esempi mostrano come abilitare il CES per piattaforma:

La tabella seguente elenca i valori dei parametri di esempio per gli esempi di questa sezione:

Parametro Valore di esempio Notes
@stream_group_name N'myStreamGroup' Nome del gruppo di stream dell'evento.
@destination_location Vedi Note Il FQDN del namespace di Hub eventi di Azure e il nome dell'istanza, compresa la porta 9093. Formato: <namespace>.servicebus.windows.net:9093/<instance>. Per Fabric Eventstream, usa l'endpoint di input personalizzato.
@partition_key_scheme N'None' (Predefinito) Le partizioni vengono selezionate a turno. Altre opzioni sono StreamGroup, Table, e Column.
@max_message_size_kb 256 256 KB è la dimensione massima predefinita del messaggio. Allinea questo valore con i tuoi limiti di destinazione.

Gli esempi utilizzano anche i seguenti valori:

  • [opzionale, se vengono utilizzate politiche di accesso condiviso tramite chiave di servizio] Valore chiave primario o secondario tratto dalla policy di accesso condiviso: Secret = 'BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw='
  • EXEC sys.sp_add_object_to_event_stream_group N'myStreamGroup', N'dbo.myTable'

Esempio: Trasmettere dati in streaming ad Hub eventi di Azure da database SQL di Azure

I seguenti esempi mostrano come trasmettere eventi di cambiamento verso Hub eventi di Azure da database SQL di Azure usando AzureEventHubs come .destination_type Questo valore è l'unico valore accettato per database SQL di Azure e SQL database in Microsoft Fabric.

L'esempio in questa sezione utilizza l'autenticazione Microsoft Entra. Questo metodo è il più sicuro.

Sostituire i valori tra parentesi angolari (<value>) con i valori per l'ambiente in uso.

USE <database name>;

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>';

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'Managed Identity'

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubs',
    @destination_location =   N'<AzureEventHubsHostName>:9093/<EventHubsInstance>',
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,
    @partition_key_scheme =   N'<PartitionKeyScheme>'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>'

Esempio: Trasmettere dati in streaming ad Hub eventi di Azure da Azure SQL MI o SQL Server 2025

I seguenti esempi mostrano come trasmettere eventi di cambiamento su Hub eventi di Azure da Istanza gestita di SQL di Azure o SQL Server 2025 utilizzando AzureEventHubsApacheKafka come .destination_type

Importante

Dal 15 agosto 2026, il protocollo AMQP è deprecato per lo streaming di eventi di cambiamento (CES). Ci sono differenze tra le piattaforme. Per i passaggi e le tempistiche della migrazione, consulta deprecazione del protocollo AMQP.

L'esempio in questa sezione usa l'autenticazione di Microsoft Entra per eseguire l'autenticazione all'istanza di Hub eventi di Azure tramite il protocollo Apache Kafka. Questo metodo è il più sicuro.

Sostituire i valori tra parentesi angolari (<value>) con i valori per l'ambiente in uso.

USE <database name>

-- Create the Master Key with a password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'Managed Identity'

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubsApacheKafka',
    @destination_location =   N'<AzureEventHubsHostName>:<port>/<EventHubsInstance>', -- myEventHubsNamespace.servicebus.windows.net:9093/myEventHubsInstance
    @destination_credential = <CredentialName>,
    @max_message_size_kb =    <MaxMessageSize>,
    @partition_key_scheme =   N'<PartitionKeyScheme>'

EXEC sys.sp_add_object_to_event_stream_group
    N'<EventStreamGroupName>',
    N'<SchemaName>.<TableName>'

Per confermare che lo streaming sia abilitato e per visualizzare le tabelle configurate per un gruppo di streaming, vedi Visualizza configurazione e funzione CES.

Dimensione del messaggio e troncatura delle colonne

Hub eventi di Azure e Fabric Eventstream limitano la dimensione massima di ogni messaggio che ricevono. CES utilizza questa @max_message_size_kb impostazione per suddividere un grande evento in uscita in più blocchi di messaggi che si adattano alla destinazione configurata. Imposta questo valore in modo che si allinei ai limiti della tua destinazione. Per gli attributi JSON che identificano i blocchi del messaggio, vedi Formato messaggio JSON - cambia lo streaming degli eventi.

Se uno o più valori di colonne streamlate sono maggiori di 1 MB, CES tronca ogni valore di colonna interessato a 1 MB prima che formi l'evento in uscita. Il limite di 1 MB si applica separatamente a ogni valore di colonna. Questa troncatura è separata dalla divisione dei messaggi. Dopo aver troncato i valori delle colonne di dimensioni eccessive, CES forma l'evento in uscita, lo suddivide in blocchi, se necessario, in base a @max_message_size_kb, e invia ciascun blocco alla destinazione.

Imposta l'opzione di configurazione del server con dimensione massima di replica di testo per permettere la scrittura di più di 65.536 byte nelle colonne LOB quando CES è abilitato.

Ad esempio, se una riga ha cinque colonne e i primi tre valori delle colonne sono ciascuno maggiori di 1 MB, CES:

  1. Tronca il valore della prima colonna a 1 MB.
  2. Tronca il valore della seconda colonna a 1 MB.
  3. Tronca il valore della terza colonna a 1 MB.
  4. Prepara l'evento in uscita, lo divide nel numero richiesto di blocchi secondo @max_message_size_kb, e invia ogni blocco alla destinazione.

Annotazioni

La troncatura dei dati a colonna è incondizionata. CES tronca ogni valore di colonna trasmesso in streaming superiore a 1 MB e non registra errori o avvisi quando si verifica il troncamento.

Visualizzare la configurazione e la funzione CES

In sys.databases indica is_event_stream_enabled = 1 che lo streaming di eventi di modifica è abilitato per il database.

La query seguente restituisce tutti i database con flusso di eventi di modifica abilitato:

SELECT *
FROM sys.databases
WHERE is_event_stream_enabled = 1;

In sys.tables indica is_replicated = 1 che viene trasmessa una tabella e sp_help_change_feed_table fornisce informazioni sul gruppo di tabelle e sui metadati della tabella per lo streaming degli eventi di modifica.

La query seguente restituisce tutte le tabelle con flusso di eventi di modifica abilitata e fornisce informazioni sui metadati:

SELECT name,
       is_replicated
FROM sys.tables;

EXECUTE sp_help_change_feed_table
    @source_schema = '<schema name>',
    @source_name = '<table name>';

Stored procedure CES, funzioni di sistema e DMV

La tabella seguente elenca le stored procedure, le funzioni di sistema e le DMV che è possibile usare per configurare, disabilitare e monitorare lo streaming di eventi di modifica:

Oggetto di sistema Descrizione
Configurare CES
sys.sp_enable_event_stream Abilita CES per il database utente corrente.
sys.sp_create_event_stream_group Crea un gruppo di flussi, ovvero una configurazione di streaming per un gruppo di tabelle. Il gruppo di flusso definisce anche la destinazione e i dettagli correlati, ad esempio l'autenticazione, le dimensioni dei messaggi, il partizionamento. Il stream_group_id viene generato automaticamente e visualizzato per l'utente finale al termine della procedura.
sys.sp_add_object_to_event_stream_group Aggiunge una tabella al gruppo di stream.
Disabilitare CES
sys.sp_remove_object_from_event_stream_group Rimuove una tabella dal gruppo di flussi.
sys.sp_drop_event_stream_group Elimina il gruppo di flussi. Il gruppo di flussi non deve essere in uso.
sys.sp_disable_event_stream Disabilita CES per il database utente corrente.
Monitora il CES
sys.dm_change_feed_errors Restituisce gli errori di recapito.
sys.dm_change_feed_log_scan_sessions Restituisce informazioni sull'attività di analisi dei log.
sys.sp_help_change_feed_settings Fornisce lo stato e le informazioni dello streaming di eventi di modifica configurati.
sys.sp_help_change_feed Monitora la configurazione corrente del flusso di modifiche.
sys.sp_help_change_feed_table_groups Restituisce i metadati utilizzati per configurare i gruppi di streaming di eventi di modifica.
sys.sp_help_change_feed_table Fornisce lo stato e le informazioni del gruppo di streaming e dei metadati della tabella per lo streaming degli eventi di modifica.

Crescita del log delle transazioni

Poiché il recapito dei messaggi è garantito, il log delle transazioni per un database con ces abilitato può continuare a crescere. Il troncamento del log viene impedito fino a quando sono presenti modifiche CES da trasmettere dal log. Quando le dimensioni del log delle transazioni raggiungono il limite massimo definito, le scritture nel database hanno esito negativo.

Per evitare questo problema nel database SQL di Azure e in Istanza gestita di SQL di Azure, quando le dimensioni del log delle transazioni si avvicinano al limite massimo definito, Microsoft potrebbe disabilitare CES o terminare transazioni a esecuzione prolungata. Per le istanze di SQL Server non gestite, ad esempio in locale o in SQL Server in macchine virtuali di Azure, è necessario monitorare le dimensioni del log delle transazioni e assicurarsi che non raggiunga il limite massimo definito e disabilitare manualmente CES o uccidere transazioni a esecuzione prolungata, se necessario.

Quando ces è disabilitato o viene terminata una transazione a esecuzione prolungata, il log delle transazioni viene troncato per liberare spazio. È necessario abilitare di nuovo manualmente CES dopo che è stato disabilitato o riprovare a eseguire qualsiasi transazione a esecuzione prolungata terminata. Le modifiche apportate ai dati mentre ces è stato disabilitato non vengono acquisite. Vengono trasmessi solo le modifiche apportate dopo il riavvio del ces.

Di seguito è riportato un elenco di scenari tipici che possono portare alla crescita del log delle transazioni con CES abilitato:

  • Errori persistenti. CES tenta di inviare un messaggio che è stato ripetutamente rifiutato e non può continuare. I motivi per gli errori persistenti che possono causare messaggi rifiutati includono:
    • Problemi di rete o configurazione errata.
    • Configurazione errata delle credenziali.
    • Dimensioni massime del messaggio configurate in modo errato che la destinazione rifiuta.
  • La destinazione limita gli eventi in ingresso. Ad esempio, Hub eventi di Azure hanno limiti di frequenza basandosi sul relativo SKU.
  • Transazioni a esecuzione prolungata che generano molti record di log e impediscono il troncamento del log.

Per garantire operazioni senza problemi, monitorare regolarmente le dimensioni del log delle transazioni e degli errori di recapito CES.

Prestazioni

In SQL Server, Istanza gestita di SQL di Azure e pool elastici del database SQL di Azure, è possibile abilitare CES in più database. Ogni database abilitato per CES utilizza le risorse del server e compete con altri carichi di lavoro del server. Assicurati che il server sia dotato di risorse adeguate per il carico di lavoro previsto e monitora regolarmente le prestazioni del server e dei database.

Limitazioni

Change Event Streaming (CES) presenta le limitazioni seguenti:

Limitazioni specifiche della piattaforma

Nei prodotti SQL configurati con un fuso orario non UTC, il committime campo in un messaggio di streaming di evento di modifica include erroneamente un suffisso Z , anche se questo campo mostra l'ora locale del database di pubblicazione. Quando il database utilizza UTC, valore e suffisso concordano. Questo problema è noto e una correzione è in attesa in una futura versione della funzione.

Le seguenti limitazioni si applicano a specifiche piattaforme per il CES:

CES in SQL Server 2025 presenta le seguenti limitazioni:

Limitazioni generali e a livello di server

Il seguente elenco descrive limitazioni a livello di server e generali:

  • CES non è supportato in SQL Server 2025 (17.x) in Linux.
  • CES genera eventi solo per le modifiche ai dati provenienti dalle istruzioni DML INSERT, UPDATE e DELETE.
  • CES non gestisce le modifiche dello schema (operazioni DDL), il che significa che non genera eventi per le operazioni DDL. Tuttavia, le operazioni DDL non vengono bloccate, quindi se vengono eseguite, lo schema degli eventi DML successivi riflette la struttura aggiornata della tabella. Si prevede di gestire correttamente gli eventi con lo schema aggiornato.
  • Attualmente, CES non trasmette dati che esistono in una tabella prima che CES sia attivo. I dati esistenti non vengono precaricati né inviati come snapshot quando CES è abilitato.
  • Se un messaggio supera il limite di dimensioni dei messaggi di Hub eventi di Azure, l'errore è attualmente osservabile solo tramite gli eventi estesi. Gli xEvent CES sono attualmente disponibili solo in SQL Server 2025 e non nel database SQL di Azure.
  • La ridenominazione di tabelle e colonne configurate per CES non è supportata. La ridenominazione di una tabella o di una colonna ha esito negativo. Le ridenominazione del database sono consentite.
  • CES non è disponibile per l'Istanza gestita di SQL di Azure configurata con la policy di aggiornamento di SQL Server 2022. È disponibile solo per le istanze configurate con i criteri di aggiornamento di SQL Server 2025 o Always-up-to-date.
  • Quando si utilizza il protocollo Kafka, il CES non supporta l'autenticazione dei token SAS. Gli unici metodi di autenticazione disponibili sono Microsoft Entra e Shared Access policy key value.

Limitazioni a livello di database

Il seguente elenco descrive le limitazioni a livello di database:

Limitazioni a livello di tabella

Il seguente elenco descrive le limitazioni a livello di tabella:

  • Una tabella può appartenere a un solo gruppo di streaming. Non è possibile trasmettere la stessa tabella a più destinazioni.
  • È possibile configurare solo le tabelle utente per CES. CES non supporta le tabelle di sistema di streaming.
  • Anche se CES è abilitato in una tabella, non è possibile aggiungere o eliminare un vincolo di chiave primaria in tale tabella.
  • I nomi delle tabelle che contengono un punto (.) attualmente non sono supportati.
  • ALTER TABLE SWITCH PARTITION non è supportato nelle tabelle configurate per CES.
  • TRUNCATE TABLE non è supportato nelle tabelle abilitate per CES.
  • CES non supporta le tabelle che usano una delle funzionalità seguenti:
    • Indici columnstore clusterizzati
    • Tabelle storiche temporali o tabelle storiche del libro mastro
    • Sempre Crittografato
    • OLTP in memoria (tabelle ottimizzate per la memoria)
    • Tabelle di grafo
    • Tabelle esterne

Importante

Le operazioni sugli indici online possono generare notevoli quantità di record del log delle transazioni. CES deve elaborare molti più dati, con conseguente aumento della latenza degli eventi.

Limitazioni a livello di colonna

Il seguente elenco descrive le limitazioni a livello di colonna:

  • CES non supporta i tipi di dati seguenti. Lo streaming ignora le colonne di questi tipi:
    • geography
    • geometry
    • image
    • json
    • rowversion / timestamp
    • sql_variant
    • Testo / ntext
    • vector
    • xml
    • Tipi definiti dall'utente (UDT)
  • Se uno o più valori di colonne streamlate sono maggiori di 1 MB, CES tronca ogni valore di colonna interessato a 1 MB prima che formi l'evento in uscita. Questa troncatura è incondizionata e non registra errori o avvisi. Configura l'opzione di configurazione del server max text repl size per consentire di scrivere più di 65.536 byte nelle colonne LOB quando CES è abilitato.

Autorizzazioni nel database di origine e residenza dei dati

Il seguente elenco descrive permessi e limitazioni di residenza dei dati:

  • Per la sicurezza a livello di riga, CES genera modifiche da tutte le righe, indipendentemente dalle autorizzazioni utente.
  • La maschera dati dinamica non si applica ai dati inviati tramite CES. I dati vengono trasmessi senza maschera, anche se la maschera è configurata.
  • CES non genera eventi correlati alle modifiche alle autorizzazioni a livello di oggetto, ad esempio la concessione di autorizzazioni a colonne specifiche.
  • CES trasmette i dati alla destinazione configurata se la configurazione di rete lo consente. Se la destinazione si trova in un'area diversa, CES trasmette i dati tra aree. Assicurarsi che sia conforme ai requisiti di residenza e conformità dei dati.

Rete e connettività

Il seguente elenco descrive una limitazione di rete e connettività:

  • Attualmente, CES può eseguire lo streaming solo agli endpoint pubblici di Hub eventi di Azure. Gli endpoint di servizio e gli endpoint privati non sono attualmente supportati.
  • Quando si utilizza il protocollo AMQP su Istanza gestita di SQL di Azure o SQL Server 2025 (per gruppi di stream esistenti non ancora migrati), imposta l'opzione di configurazione TLS Minimum Hub eventi di Azure su 1.2. CES non funziona con TLS 1.3 tramite il protocollo AMQP.

Contenuti correlati

  • Last updated on