Configure change event streaming (preview) to Azure Event Hubs

Richtlinien für den freigegebenen Zugriff bieten Authentifizierung und Autorisierung für Azure Event Hubs. Jede Richtlinie für den freigegebenen Zugriff benötigt einen Namen, eine Zugriffsstufe (Manage, Sendoder Listen) und eine Ressourcenbindung (Event Hubs-Namespace oder eine bestimmte Event Hub-Instanz). Richtlinien auf Instanzebene bieten mehr Sicherheit, indem sie dem Prinzip der geringsten Berechtigungen folgen. Während SQL Datenbank-Engine-Produkte Shared-Access-Richtlinien unterstützen, sollten Sie wann immer möglich Microsoft Entra-Authentifizierung verwenden, da dies eine bessere Sicherheit bietet.

Wenn Sie eine Shared-Access-Richtlinie für Authentifizierung und Autorisierung verwenden, müssen Clients, die Daten an eine Event Hubs-Instanz senden, den Namen der gewünschten Richtlinie sowie entweder ein SAS-Token angeben, das aus der Richtlinie oder deren Service-Schlüssel generiert wird.

SAS-Token haben einen Sicherheitsvorteil gegenüber Dienstschlüsseln: Wenn der Client kompromittiert ist, ist das SAS-Token nur gültig, bis es abläuft, und der kompromittierte Client kann keine neuen SAS-Token erstellen. Im Gegensatz dazu laufen Dienstschlüssel nicht automatisch ab. Ein kompromittierter Client mit einem Dienstschlüssel kann neue SAS-Token mithilfe des Schlüssels generieren.

Um das Streaming zu Azure Event Hubs mit dem AMQP-Protokoll zu konfigurieren, erstellen oder wiederverwenden Sie eine Shared Access Policy mit Send-Berechtigung und generieren Sie ein SAS-Token. Sie können das Token programmgesteuert mit jeder Programmier- oder Skriptsprache generieren. Das Beispiel in diesem Artikel zeigt, wie Sie ein SAS-Token aus einer neuen oder vorhandenen Richtlinie mithilfe eines PowerShell-Skripts generieren.

Installieren der erforderlichen Module

Zum Verwalten von Azure Event Hubs-Ressourcen mit PowerShell-Skripts benötigen Sie die folgenden Module:

• Az PowerShell-Modul
• Az.EventHub PowerShell-Modul

Das folgende Skript installiert die erforderlichen Module:

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

Wenn Sie bereits über die erforderlichen Module verfügen und diese auf die neueste Version aktualisieren möchten, führen Sie das folgende Skript aus:

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

Herstellen einer Verbindung mit Azure

Sie können Entweder Azure Cloud Shell verwenden oder sich anmelden und Ihren Abonnementkontext festlegen.

Um Azure Cloud Shell zu nutzen, sehen Sie sich bitte die Anmeldung bei Azure an.

Definieren einer Richtlinie

Zum Erstellen des SAS-Tokens benötigen Sie eine Richtlinie mit Senderechten . Sie haben folgende Möglichkeiten:

• Erstellen einer neuen Richtlinie

  oder

• Verwenden einer vorhandenen Richtlinie

Erstellen eines SAS-Tokens für eine neue oder vorhandene Richtlinie

Wenn Sie eine neue Richtlinie erstellen, stellen Sie sicher, dass sie über das Recht Senden verfügt. Wenn Sie eine vorhandene Richtlinie verwenden, überprüfen Sie, ob sie das Recht "Senden" besitzt.

Das folgende Skript erstellt eine neue Richtlinie oder ruft eine vorhandene Richtlinie ab, generiert dann ein vollständiges SAS-Token in einem HTTP-Autorisierungsheaderformat.

Ersetzen Sie Werte in spitzen Klammern (<value>) durch Werte für Ihre Umgebung.

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

Die Ausgabe des vorherigen Befehls sollte wie der folgende Text aussehen:

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

Kopieren Sie den gesamten SAS-Tokenwert (die Zeile, die mit SharedAccessSignature) beginnt, um ihn später zu verwenden, wenn Sie CES konfigurieren, z. B. das folgende Beispiel:

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

Verwenden Sie von Microsoft Entra verwaltete Identitäten , um den Zugriff auf Azure Event Hubs zu steuern. Es ist die einfachste und sicherste Möglichkeit, Den Zugriff auf Azure Event Hubs zu gewähren. CES unterstützt Microsoft Entra-Authentifizierung in Azure SQL-Datenbank und Azure SQL Managed Instance. Für SQL Server 2025 wird die Microsoft Entra-Authentifizierung ab Cumulative Update 3 (CU3) für Instanzen unterstützt, die durch Azure Arc aktiviert sind oder auf einer Azure-VM laufen. Microsoft Entra-Authentifizierung ist derzeit nicht für SQL-Datenbanken in Microsoft Fabric verfügbar.

Um Managed Identity-Schreibzugriff auf die Event Hubs-Instanz von Azure SQL-Datenbank, Azure SQL Managed Instance oder SQL Server zu ermöglichen, folgen Sie diesen Schritten:

1. Falls du es noch nicht getan hast, konfiguriere eine verwaltete Identität für deine SQL Datenbank-Engine:

   1. Der logische Server für Azure SQL-Datenbank
   2. Azure SQL Managed Instance
   3. SQL Server auf virtuellen Azure-Computern
   4. SQL Server, aktiviert von Azure Arc

2. Weisen Sie der verwalteten Identität Ihres logischen Servers, Ihrer verwalteten SQL-Instanz oder Ihres SQL Servers für Ihre Event Hubs-Instanz die Azure Event Hubs Data Sender-Rollenzuweisung zu. Sie können dies programmatisch mit jeder Programmier- oder Skriptsprache oder auf der Access Control (IAM)-Seite Ihrer Event Hubs-Instanz im Azure-Portal durchführen.

Um dem Prinzip der geringsten Berechtigung zu folgen, gewähren Sie Zugriff auf die spezifische Event Hubs-Instanz, die die Änderungsereignisse empfängt. Das Gewähren von Schreibzugriff auf den gesamten Event Hubs-Namensraum ist technisch erlaubt, wird aber nicht empfohlen, da dies für jede Event Hubs-Instanz innerhalb des Namensraums gilt.

Im Beispiel in diesem Abschnitt wird ein SAS-Token verwendet, um sich über das AMQP-Protokoll bei Ihrer Azure Event Hubs-Instanz zu authentifizieren. Wenn die Microsoft Entra-Authentifizierung nicht verfügbar ist, verwenden Sie ein SAS-Token anstelle eines Dienstschlüsselwerts für verbesserte Sicherheit.

Ersetzen Sie Werte in spitzen Klammern (<value>) durch Werte für Ihre Umgebung.

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

Im Beispiel in diesem Abschnitt wird die Microsoft Entra-Authentifizierung verwendet, um sich über das AMQP-Protokoll bei Ihrer Azure Event Hubs-Instanz zu authentifizieren. Diese Methode ist am sichersten.

Ersetzen Sie die Werte in eckigen Klammern (<value>) durch Werte für Ihre Umgebung.

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

Das Beispiel in diesem Abschnitt verwendet einen Schlüsselwert für den gemeinsamen Zugriff, um sich über das AMQP-Protokoll bei Ihrer Azure Event Hubs-Instanz zu authentifizieren. Wenn die Microsoft Entra-Authentifizierung nicht verfügbar ist, verwenden Sie ein SAS-Token anstelle eines Dienstschlüsselwerts für verbesserte Sicherheit.

Ersetzen Sie die Werte in eckigen Klammern (<value>) durch Werte für Ihre Umgebung.

USE <database name>

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

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = '<Azure Event Hubs SAS Policy name>',
    SECRET = '<Primary or Secondary key value>'

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

Im Beispiel in diesem Abschnitt wird die Microsoft Entra-Authentifizierung verwendet, um sich über das Apache Kafka-Protokoll bei Ihrer Azure Event Hubs-Instanz zu authentifizieren. Diese Methode ist am sichersten.

Ersetzen Sie die Werte in eckigen Klammern (<value>) durch Werte für Ihre Umgebung.

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

Im Beispiel in diesem Abschnitt wird ein Schlüsselwert für den Gemeinsamen Zugriff verwendet, um sich über das Apache Kafka-Protokoll bei Ihrer Azure Event Hubs-Instanz zu authentifizieren. Für bessere Sicherheit verwenden Sie wann immer möglich Microsoft Entra-Authentifizierung.

Ersetzen Sie die Werte in eckigen Klammern (<value>) durch Werte für Ihre Umgebung.

USE <database name>

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

CREATE DATABASE SCOPED CREDENTIAL <CredentialName>
    WITH IDENTITY = '<Azure Event Hubs SAS Policy name>',
    SECRET = '<Primary or Secondary key value>' -- BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw=

EXEC sys.sp_enable_event_stream

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

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

CES in SQL Server 2025 hat folgende Einschränkungen:

• Du musst die Konfiguration der Vorschau-Funktion in der Datenbank aktivieren.
• Microsoft Entra-Authentifizierung wird ab Cumulative Update 3 (CU3) für Instanzen unterstützt, die durch Azure Arc aktiviert sind oder auf einer Azure-VM laufen.

xEvent-Debugging ist derzeit nicht in der Azure SQL-Datenbank verfügbar.

CES ist nicht für Instanzen verfügbar, die mit der SQL Server 2022-Update-Richtlinie konfiguriert sind.

CES hat folgende Einschränkungen in SQL-Datenbanken in Fabric:

• xEvent-Debugging ist derzeit nicht verfügbar.
• Microsoft Entra-Authentifizierung ist derzeit nicht verfügbar.