Partekatu bidez

Configuración del streaming de eventos de cambio (versión preliminar)

Se aplica a: SQL Server 2025 (17.x) Azure SQL Database

En este artículo se describe cómo configurar la característica de streaming de eventos de cambio (CES) introducida en SQL Server 2025 (17.x) y Azure SQL Database.

Nota:

El streaming de eventos de cambio se encuentra actualmente en versión preliminar para:

Durante la versión preliminar, esta característica está sujeta a cambios. Para obtener compatibilidad actual, consulte Limitaciones.

Información general

Para configurar y usar el streaming de eventos de cambio, siga estos pasos:

  1. Use un espacio de nombres existente o cree un nuevo espacio de nombres de Azure Event Hubs y una instancia de Event Hubs. La instancia de Event Hubs recibe eventos.
  2. Habilite el streaming de eventos de cambio para una base de datos de usuario.
  3. Cree un grupo de secuencias de eventos. Con este grupo, configure el destino, las credenciales, los límites de tamaño del mensaje y el esquema de creación de particiones.
  4. Agregue una o varias tablas al grupo de secuencias de eventos.

Cada paso se describe en detalle en las secciones siguientes de este artículo.

Prerrequisitos

Para configurar el streaming de eventos de cambio, necesita los siguientes recursos, permisos y configuración:

Configuración de Azure Event Hubs

Para aprender a crear Azure Event Hubs, consulte Creación de un centro de eventos mediante Azure Portal.

Control de acceso de Azure Event Hubs

Configure el control de acceso para el recurso de SQL en Azure Event Hubs. La autenticación de Microsoft Entra es el método más seguro, pero actualmente solo es compatible con Azure SQL Database para CES. Aunque el uso de una directiva de acceso compartido es compatible con Azure SQL Database y SQL Server 2025, úselo solo en Azure SQL Database si la autenticación de Microsoft Entra no es una opción.

Las directivas de acceso compartido proporcionan autenticación y autorización a Azure Event Hubs. Cada directiva de acceso compartido necesita un nombre, un nivel de acceso (Manage, Sendo Listen) y un enlace de recursos (espacio de nombres de Event Hubs o una instancia específica del centro de eventos). Las directivas de nivel de instancia ofrecen más seguridad siguiendo el principio de privilegios mínimos. Tanto SQL Server 2025 como Azure SQL Database admiten este método. Sin embargo, use la autenticación de Microsoft Entra siempre que sea posible con Azure SQL Database, ya que proporciona una mejor seguridad.

Si usa una directiva de acceso compartido para la autenticación y autorización, los clientes que envían datos a un centro de eventos de Azure deben proporcionar el nombre de la directiva que quieren usar, junto con un token de SAS generado a partir de la directiva o la clave de servicio de la directiva.

Los tokens de SAS tienen una ventaja de seguridad sobre las claves de servicio: si el cliente está en peligro, el token de SAS solo es válido hasta que expire y el cliente en peligro no puede crear nuevos tokens de SAS. Por el contrario, las claves de servicio no expiran automáticamente. Un cliente en peligro con una clave de servicio puede generar nuevos tokens de SAS mediante la clave .

Para configurar el streaming en Azure Event Hubs con el protocolo AMQP (el protocolo nativo de Azure Event Hubs predeterminado), cree o reutilice una directiva de acceso compartido con el permiso Enviar y genere un token de SAS. Puede generar el token mediante programación con cualquier lenguaje de programación o scripting. En el ejemplo de este artículo se muestra cómo generar un token de SAS a partir de una directiva nueva o existente mediante un script de PowerShell.

Nota:

Para mejorar la seguridad, se recomienda encarecidamente usar el control de acceso basado en Microsoft Entra siempre que sea posible. Si el control de acceso basado en Microsoft Entra no es posible y usa directivas de acceso compartido, use la autenticación de token de SAS en lugar de la autenticación basada en claves de servicio siempre que sea posible. Entre los procedimientos recomendados para los tokens de SAS se incluye definir un ámbito de acceso mínimo necesario, establecer una fecha de expiración corta y rotar la clave SAS con regularidad. Para la autenticación basada en claves, gire las claves periódicamente. Almacene todos los secretos de forma segura mediante Azure Key Vault o un servicio similar.

Instalación de los módulos necesarios

Para administrar recursos de Azure Event Hubs con scripts de PowerShell, necesita los siguientes módulos:

  • Módulo de Az PowerShell
  • Módulo Az.EventHub de PowerShell

El siguiente script instala los módulos necesarios:

Install-Module -Name Az -AllowClobber -Scope CurrentUser -Repository PSGallery -Force
Install-Module -Name Az.EventHub -Scope CurrentUser -Force

Si ya tiene los módulos necesarios y quiere actualizarlos a la versión más reciente, ejecute el siguiente script:

Update-Module -Name Az -Force
Update-Module -Name Az.EventHub -Force

Conexión con Azure

Puede usar Azure Cloud Shell o iniciar sesión y establecer el contexto de suscripción.

Para ejecutar con Azure Cloud Shell, consulte Inicio de sesión en Azure.

Definición de una directiva

Para crear el token de SAS, necesita una directiva con derechos de envío . Puede hacer lo siguiente:

  • Crear una nueva directiva

    O bien,

  • Uso de una directiva existente

Nota:

La directiva debe tener derechos de envío .

Creación de un token de SAS para una directiva nueva o existente

Al crear una nueva directiva, asegúrese de que tiene el derecho Enviar . Si usa una directiva existente, compruebe que tiene el derecho Enviar .

El script siguiente crea una nueva directiva o obtiene una existente y, a continuación, genera un token saS completo en un formato de encabezado de autorización HTTP.

Reemplace los valores entre corchetes angulares (<value>) por los valores de su entorno.

function Generate-SasToken {
$subscriptionId = "<Azure-Subscription-ID>"
$resourceGroupName = "<Resource-group-name>"
$namespaceName = "<Azure-Event-Hub-Namespace-name>"
$eventHubName = "<Azure-Event-Hubs-instance-name>"
$policyName = "<Policy-name>"
$tokenExpireInDays = "<number-of-days-token-will-be-valid>"

# Modifying the rest of the script is not necessary.

# Login to Azure and set Azure Subscription.
Connect-AzAccount

# Get current context and check subscription
$currentContext = Get-AzContext
if ($currentContext.Subscription.Id -ne $subscriptionId) {
    Write-Host "Current subscription is $($currentContext.Subscription.Id), switching to $subscriptionId..."
    Set-AzContext -SubscriptionId $subscriptionId | Out-Null
} else {
    Write-Host "Already using subscription $subscriptionId."
}

# Try to get the authorization policy (it should have Send rights)
$rights = @("Send")
$policy = Get-AzEventHubAuthorizationRule -ResourceGroupName $resourceGroupName -NamespaceName $namespaceName -EventHubName $eventHubName -AuthorizationRuleName $policyName -ErrorAction SilentlyContinue

# If the policy does not exist, create it
if (-not $policy) {
    Write-Output "Policy '$policyName' does not exist. Creating it now..."

    # Create a new policy with the Manage, Send and Listen rights
    $policy = New-AzEventHubAuthorizationRule -ResourceGroupName $resourceGroupName -NamespaceName $namespaceName -EventHubName $eventHubName -AuthorizationRuleName $policyName -Rights $rights
    if (-not $policy) {
        throw "Error. Policy was not created."
    }
    Write-Output "Policy '$policyName' created successfully."
} else {
    Write-Output "Policy '$policyName' already exists."
}

if ("Send" -in $policy.Rights) {
    Write-Host "Authorization rule has required right: Send."
} else {
    throw "Authorization rule is missing Send right."
}

$keys = Get-AzEventHubKey -ResourceGroupName $resourceGroupName -NamespaceName $namespaceName -EventHubName $eventHubName -AuthorizationRuleName $policyName

if (-not $keys) {
    throw "Could not obtain Azure Event Hub Key. Script failed and will end now."
}
if (-not $keys.PrimaryKey) {
    throw "Could not obtain Primary Key. Script failed and will end now."
}

# Get the Primary Key of the Shared Access Policy
$primaryKey = ($keys.PrimaryKey)
Write-Host $primaryKey

## Check that the primary key is not empty.

# Define a function to create a SAS token (similar to the C# code provided)
function Create-SasToken {
    param (
        [string]$resourceUri, [string]$keyName, [string]$key
    )

$sinceEpoch = [datetime]::UtcNow - [datetime]"1970-01-01"
    $expiry = [int]$sinceEpoch.TotalSeconds + ((60 * 60 * 24) * [int]$tokenExpireInDays) # seconds since Unix epoch
    $stringToSign = [System.Web.HttpUtility]::UrlEncode($resourceUri) + "`n" + $expiry
    $hmac = New-Object System.Security.Cryptography.HMACSHA256
    $hmac.Key = [Text.Encoding]::UTF8.GetBytes($key)
    $signature = [Convert]::ToBase64String($hmac.ComputeHash([Text.Encoding]::UTF8.GetBytes($stringToSign)))
    $sasToken = "SharedAccessSignature sr=$([System.Web.HttpUtility]::UrlEncode($resourceUri))&sig=$([System.Web.HttpUtility]::UrlEncode($signature))&se=$expiry&skn=$keyName"
    return $sasToken
}

# Construct the resource URI for the SAS token
$resourceUri = "https://$namespaceName.servicebus.windows.net/$eventHubName"

# Generate the SAS token using the primary key from the new policy
$sasToken = Create-SasToken -resourceUri $resourceUri -keyName $policyName -key $primaryKey

# Output the SAS token
Write-Output @"
-- Generated SAS Token --
$sasToken
-- End of generated SAS Token --
"@
}

Generate-SasToken

La salida del comando anterior debe tener un aspecto similar al texto siguiente:

-- Generated SAS Token --
SharedAccessSignature sr=https%3a%2f%YourEventHubNamespace.servicebus.windows.net%2fYourEventHub&sig=xxxxxxxxxxxxxxxxxxxxxxx&se=2059133074&skn=SharedKeyNameIsHERE
-- End of generated SAS Token --

Copie el valor completo del token de SAS (la línea que comienza por SharedAccessSignature) para usarlo más adelante al configurar CES, como el ejemplo siguiente:

SharedAccessSignature sr=https%3a%2f%YourEventHubNamespace.servicebus.windows.net%2fYourEventHub&sig=xxxxxxxxxxxxxxxxxxxxxxx&se=2059133074&skn=SharedKeyNameIsHERE

Habilitación y configuración del streaming de eventos de cambio

Para habilitar y configurar el streaming de eventos de cambio, cambie el contexto de la base de datos a la base de datos de usuario y siga estos pasos:

  1. Si aún no está configurado, establezca la base de datos en el modelo de recuperación completa.
  2. Cree una clave maestra y una credencial con ámbito en la base de datos.
  3. Habilite el streaming de eventos.
  4. Cree el grupo de secuencias de eventos.
  5. Agregue una o varias tablas al grupo de secuencias de eventos.

En los ejemplos de esta sección se muestra cómo habilitar CES para el protocolo AMQP y el protocolo Apache Kafka:

A continuación se muestran los valores de parámetro de ejemplo para los ejemplos de esta sección:

  • @stream_group_name = N'myStreamGroup'

  • @destination_location = N'myEventHubsNamespace.servicebus.windows.net/myEventHubsInstance' : este valor es el FQDN del nombre de instancia y azure Event Hubs específico.

  • @partition_key_scheme = N'None' - (valor predeterminado) las particiones se eligen round robin. Otras opciones posibles son:

    • StreamGroup : creación de particiones por el grupo de flujos
    • Table : creación de particiones por tabla
    • Column : creación de particiones por columnas

  • [opcional, si se usan directivas de acceso compartido a través de la clave de servicio]

    • Valor de clave principal o secundaria tomado de la directiva de acceso compartido: Secret = 'BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw='

  • EXEC sys.sp_add_object_to_event_stream_group N'myStreamGroup', N'dbo.myTable'

  • @max_message_size_kb = 256 - 256 KB es el tamaño de mensaje máximo predeterminado, pero este valor debe alinearse con los límites de Azure Event Hubs de destino.

Ejemplo: Transmisión a Azure Event Hubs mediante el protocolo AMQP

Los ejemplos de esta sección muestran cómo transmitir eventos de cambio a Azure Event Hubs mediante el protocolo AMQP. AMQP es el protocolo nativo de Azure Event Hubs predeterminado.

En el ejemplo de esta sección se usa un token de SAS para autenticarse en la instancia de Azure Event Hubs mediante el protocolo AMQP. Si la autenticación de Microsoft Entra no está disponible, use un token de SAS en lugar de un valor de clave de servicio para mejorar la seguridad.

Reemplace los valores entre corchetes angulares (<value>) por los valores de su entorno.

USE <database name>;

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

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<Generated SAS Token>' -- Be sure to copy the entire token. The SAS token starts with "SharedAccessSignature sr="

EXEC sys.sp_enable_event_stream

EXEC sys.sp_create_event_stream_group
    @stream_group_name =      N'<EventStreamGroupName>',
    @destination_type =       N'AzureEventHubsAmqp',
    @destination_location =   N'<AzureEventHubsHostName>/<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>'

Ejemplo: Transmisión a Azure Event Hubs mediante el protocolo Apache Kafka

En los ejemplos de esta sección se muestra cómo transmitir eventos de cambio a Azure Event Hubs mediante el protocolo Apache Kafka.

En el ejemplo de esta sección se usa un token de SAS para autenticarse en la instancia de Azure Event Hubs mediante el protocolo Apache Kafka. Si la autenticación de Microsoft Entra no está disponible, use un token de SAS en lugar de un valor de clave de servicio para mejorar la seguridad.

Reemplace los valores entre corchetes angulares (<value>) por los valores de su entorno.

USE <database name>

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

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<Event Hubs Namespace – Primary or Secondary connection string>'

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'<PatitionKeyScheme>'

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

Ver la configuración y función del CES

En sys.databases, is_event_stream_enabled = 1 indica que el streaming de eventos de cambio está habilitado para la base de datos.

La consulta siguiente devuelve todas las bases de datos con el streaming de eventos de cambio habilitado:

SELECT *
FROM sys.databases
WHERE is_event_stream_enabled = 1;

En sys.tables, is_replicated = 1 indica que se transmite una tabla y sp_help_change_feed_table proporciona información sobre el grupo de tablas y los metadatos de tabla para el streaming de eventos de cambio.

La consulta siguiente devuelve todas las tablas con el streaming de eventos de cambio habilitado y proporciona información de metadatos:

SELECT name,
       is_replicated
FROM sys.tables;

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

Procedimientos almacenados ces, funciones del sistema y DMV

En la tabla siguiente se enumeran los procedimientos almacenados, las funciones del sistema y las DMV que puede usar para configurar, deshabilitar y supervisar el streaming de eventos de cambio:

System (objeto) Descripción
Configurar CES
sys.sp_enable_event_stream Habilita CES para la base de datos de usuario actual.
sys.sp_create_event_stream_group Crea un grupo de flujos, que es una configuración de transmisión para un grupo de tablas. El grupo de secuencias también define el destino y los detalles relacionados (como la autenticación, el tamaño del mensaje, la creación de particiones). El stream_group_id se genera automáticamente y se muestra para el usuario final cuando se completa el procedimiento.
sys.sp_add_object_to_event_stream_group Agrega una tabla al grupo de secuencias.
Deshabilitar CES
sys.sp_remove_object_from_event_stream_group Quita una tabla del grupo de flujos.
sys.sp_drop_event_stream_group Elimina el grupo de flujos. El grupo de secuencias no debe estar en uso.
sys.sp_disable_event_stream Deshabilita CES para la base de datos de usuario actual.
Supervisión de CES
sys.dm_change_feed_errors Devuelve los errores de entrega.
sys.dm_change_feed_log_scan_sessions Devuelve información sobre la actividad del escaneo de registros.
sys.sp_help_change_feed_settings Proporciona el estado e información del streaming de eventos de cambio configurado.
sys.sp_help_change_feed Supervisa la configuración actual del flujo de cambios.
sys.sp_help_change_feed_table_groups Devuelve metadatos que se usan para configurar los grupos de streaming de eventos modificados.
sys.sp_help_change_feed_table Proporciona el estado y la información del grupo de streaming y los metadatos de tabla para el streaming de eventos de cambio.

Limitaciones

El streaming de eventos de cambio (CES) tiene las siguientes limitaciones:

Azure SQL Database

Se aplican las limitaciones siguientes al usar CES con Azure SQL Database:

  • La depuración de eventos extendidos (xEvent) en Azure SQL Database no está disponible actualmente.

Limitaciones generales y de nivel de servidor

  • CES no se admite en SQL Server 2025 (17.x) en Linux.
  • CES emite eventos solo para los cambios en los datos a partir de las instrucciones DML de INSERT, UPDATE, y DELETE.
  • CES no controla los cambios de esquema (operaciones DDL), lo que significa que no emite eventos para las operaciones DDL. Sin embargo, las operaciones DDL no están bloqueadas, por lo que, si las ejecuta, el esquema de eventos DML posteriores refleja la estructura de tabla actualizada. Se espera que controle correctamente los eventos con el esquema actualizado.
  • Actualmente, CES no transmite datos que existen en una tabla antes de habilitar CES. Los datos existentes no se inicializarán ni se enviarán como instantáneas cuando CES está habilitado.
  • Cuando JSON es el formato de salida especificado, los mensajes de eventos grandes pueden dividirse en aproximadamente 25% del tamaño máximo de mensaje configurado por grupo de secuencias. Esta limitación no se aplica al tipo de salida binario.
  • Si un mensaje supera el límite de tamaño de mensaje de Azure Event Hubs, el error solo se puede observar actualmente a través de eventos extendidos. CES xEvents solo está disponible actualmente en SQL Server 2025 y no en Azure SQL Database.
  • No se admite el cambio de nombre de tablas y columnas para CES. Se produce un error al cambiar el nombre de una tabla o columna. Se permiten los cambios de nombre de la base de datos.
  • La autenticación de Microsoft Entra para CES no está disponible actualmente en SQL Server 2025.

Limitaciones de nivel de base de datos

Limitaciones de nivel de tabla

  • Una tabla solo puede pertenecer a un grupo de streaming. No se puede transmitir la misma tabla a varios destinos.

  • Solo puede configurar tablas de usuario para CES. CES no admite tablas del sistema de streaming.

  • Puede configurar hasta 4096 grupos de flujos. Cada grupo de secuencias puede incluir hasta 40 000 tablas.

  • No se admiten las operaciones de índice en línea

  • Aunque CES está habilitado en una tabla, no se puede agregar ni quitar una restricción de clave principal en esa tabla.

  • ALTER TABLE SWITCH PARTITION no es compatible con las tablas configuradas para CES.

  • TRUNCATE TABLE no está soportado en tablas habilitadas para CES.

  • CES no admite tablas que usen ninguna de las siguientes características:

    • Índices de almacén de columnas en clúster
    • Tablas de historial temporal o tablas de historial de libro de contabilidad
    • Siempre Cifrado
    • OLTP en memoria (tablas optimizadas para memoria)
    • Tablas de grafos
    • Tablas externas

Limitaciones de nivel de columna

  • CES no admite los siguientes tipos de datos. El streaming omite las columnas de estos tipos:
    • geography
    • geometry
    • image
    • json
    • rowversion / Timestamp
    • sql_variant
    • Mensaje de texto / ntext
    • vector
    • xml
    • Tipos definidos por el usuario (UDT)

Permisos en la base de datos de origen

  • Para seguridad de nivel de fila, CES emite cambios en todas las filas, independientemente de los permisos de usuario.
  • El enmascaramiento dinámico de datos no se aplica a los datos enviados a través de CES. Los datos se transmiten sin máscara, incluso si está configurado el enmascaramiento.
  • CES no emite eventos relacionados con los cambios de permisos de nivel de objeto (por ejemplo, conceder permisos a columnas específicas).

Contenido relacionado

  • Last updated on