Configurar o streaming de eventos de alteração (versão prévia)

As políticas de acesso compartilhado fornecem autenticação e autorização aos Hubs de Eventos do Azure. Cada política de acesso compartilhado precisa de um nome, um nível de acesso (Manageou SendListen) e uma associação de recursos (namespace dos Hubs de Eventos ou uma instância específica do Hub de Eventos). As políticas de nível de instância oferecem mais segurança seguindo o princípio do privilégio mínimo. O SQL Server 2025 e o Banco de Dados SQL do Azure dão suporte a esse método. No entanto, use a autenticação do Microsoft Entra sempre que possível com o Banco de Dados SQL do Azure, pois ela fornece melhor segurança.

Se você usar uma política de acesso compartilhado para autenticação e autorização, os clientes que enviam dados para um Hub de Eventos do Azure precisarão fornecer o nome da política que desejam usar, juntamente com um token SAS gerado da política ou da chave de serviço da política.

Os tokens SAS têm uma vantagem de segurança em relação às chaves de serviço: se o cliente estiver comprometido, o token SAS só será válido até expirar e o cliente comprometido não poderá criar novos tokens SAS. Por outro lado, as chaves de serviço não expiram automaticamente. Um cliente comprometido com uma chave de serviço pode gerar novos tokens SAS usando a chave.

Para configurar o streaming para os Hubs de Eventos do Azure com o protocolo AMQP (o protocolo padrão dos Hubs de Eventos nativos do Azure), crie ou reutilize uma política de acesso compartilhado com a permissão Enviar e gere um token SAS. Você pode gerar o token programaticamente com qualquer linguagem de programação ou script. O exemplo neste artigo mostra como gerar um token SAS de uma política nova ou existente usando um script do PowerShell.

Instalar os módulos necessários

Para gerenciar recursos dos Hubs de Eventos do Azure com scripts do PowerShell, você precisa dos seguintes módulos:

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

O script a seguir instala os módulos necessários:

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

Se você já tiver os módulos necessários e quiser atualizá-los para a versão mais recente, execute o seguinte script:

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

Conectar-se ao Azure

Você pode usar o Azure Cloud Shell ou entrar e definir seu contexto de assinatura.

Para executar com o Azure Cloud Shell, examine Entrar no Azure.

Definir uma política

Para criar o token SAS, você precisa de uma política com direitos de envio . Você pode:

• Criar uma nova política

  Ou

• Usar uma política existente

Criar token SAS para uma política nova ou existente

Ao criar uma nova política, verifique se ela tem o direito enviar . Se você usar uma política existente, verifique se ela tem o direito enviar .

O script a seguir cria uma nova política ou obtém uma existente e, em seguida, gera um token SAS completo em um formato de cabeçalho de autorização HTTP.

Substitua valores em colchetes angulares (<value>) por valores para seu ambiente.

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

A saída do comando anterior deve ser semelhante ao seguinte texto:

-- 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 todo o valor do token SAS (a linha que começa com SharedAccessSignature) para usá-lo mais tarde quando você configurar o CES, como o exemplo a seguir:

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

Use identidades gerenciadas do Microsoft Entra para controlar o acesso aos Hubs de Eventos do Azure. É a maneira mais simples e segura de conceder acesso aos Hubs de Eventos do Azure. Atualmente, apenas o Banco de Dados SQL do Azure dá suporte à autenticação do Microsoft Entra para CES.

Para permitir que a identidade gerenciada do Banco de Dados SQL do Azure acesse o Hub de Eventos, siga estas etapas:

1. Configure uma identidade gerenciada para o servidor lógico do Banco de Dados SQL do Azure, caso ainda não tenha feito isso.
2. Adicione a Azure Event Hubs Data Sender atribuição de função à identidade gerenciada do servidor lógico para sua instância do Hub de Eventos do Azure. Você pode fazer isso programaticamente com qualquer linguagem de programação ou script ou na página IAM (Controle de Acesso) para sua instância do Hub de Eventos do Azure no portal do Azure.

Para seguir o princípio do privilégio mínimo, conceda acesso à instância específica dos Hubs de Eventos que recebe os eventos de alteração. A concessão de acesso de gravação a todo o namespace dos Hubs de Eventos é tecnicamente permitida, mas não é recomendada, pois se aplica a qualquer instância dos Hubs de Eventos dentro do namespace.

O exemplo nesta seção usa um token SAS para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo AMQP. Se a autenticação do Microsoft Entra não estiver disponível, use um token SAS em vez de um valor de chave de serviço para melhorar a segurança.

Substitua valores em colchetes angulares (<value>) por valores para seu ambiente.

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

O exemplo nesta seção usa a autenticação do Microsoft Entra para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo AMQP. Esse método é o mais seguro, mas atualmente só tem suporte do Banco de Dados SQL do Azure para CES.

Substitua os valores em colchetes angulares (<value>) por valores para seu ambiente.

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

O exemplo nesta seção usa um valor de chave de política de Acesso Compartilhado para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo AMQP. Se a autenticação do Microsoft Entra não estiver disponível, use um token SAS em vez de um valor de chave de serviço para melhorar a segurança.

Substitua os valores em colchetes angulares (<value>) por valores para seu ambiente.

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

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

O exemplo nesta seção usa um token SAS para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo Apache Kafka. Se a autenticação do Microsoft Entra não estiver disponível, use um token SAS em vez de um valor de chave de serviço para melhorar a segurança.

Substitua valores em colchetes angulares (<value>) por valores para seu ambiente.

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

O exemplo nesta seção usa a autenticação do Microsoft Entra para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo Apache Kafka. Esse método é o mais seguro, mas atualmente só tem suporte do Banco de Dados SQL do Azure para CES.

Substitua os valores em colchetes angulares (<value>) por valores para seu ambiente.

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

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

O exemplo nesta seção usa um valor de chave de política de Acesso Compartilhado para autenticar na instância dos Hubs de Eventos do Azure por meio do protocolo Apache Kafka. Se a autenticação do Microsoft Entra não estiver disponível, use um token SAS em vez de um valor de chave de serviço para melhorar a segurança.

Substitua os valores em colchetes angulares (<value>) por valores para seu ambiente.

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

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