Mengonfigurasi streaming peristiwa perubahan

2025-06-19

Berlaku untuk: Pratinjau SQL Server 2025 (17.x)

Artikel ini menjelaskan cara mengonfigurasi fitur change event streaming (CES) yang diperkenalkan di Pratinjau SQL Server 2025 (17.x).

Nota

Streaming perubahan peristiwa saat ini tersedia dalam versi pratinjau untuk SQL Server 2025.

Gambaran Umum

Untuk mengonfigurasi dan menggunakan streaming peristiwa perubahan, ikuti urutan langkah-langkah ini:

Gunakan namespace Azure Event Hubs yang sudah ada atau buat instans Event Hubs dan namespace baru. Instans Azure Event Hubs menerima peristiwa.
Aktifkan streaming peristiwa perubahan untuk database pengguna.
Membuat grup aliran peristiwa. Dengan grup ini, konfigurasikan tujuan, kredensial, batas ukuran pesan, dan skema partisi.
Tambahkan satu atau beberapa tabel ke grup aliran peristiwa.

Setiap langkah dijelaskan secara rinci di bagian berikut dari artikel ini.

Prasyarat

Untuk mengonfigurasi streaming peristiwa perubahan, Anda memerlukan hal berikut:

Namespace Azure Event Hubs
Instans Azure Event Hubs
Nama host Azure Event Hubs
Kebijakan dengan Tingkat akses Kirim
Masuk dalam peran db_owner atau yang memiliki izin CONTROL DATABASE untuk database tempat Anda ingin mengaktifkan CES.

Mengonfigurasi Azure Event Hubs

Untuk mempelajari cara membuat Azure Event Hubs, tinjau Membuat pusat aktivitas menggunakan portal Microsoft Azure.

Untuk mengonfigurasi streaming ke Azure Event Hubs dengan protokol AMQP (default, protokol Azure Event Hubs asli), buat token SAS untuk namespace layanan dan nama instans Azure Event Hubs Anda. Anda dapat melakukannya secara terprogram dengan bahasa pemrograman atau pembuatan skrip apa pun. Contoh dalam artikel ini menunjukkan cara menghasilkan token SAS dari kebijakan baru atau yang sudah ada dengan menggunakan skrip PowerShell.

Menginstal modul yang diperlukan

Untuk mengelola sumber daya Azure Event Hubs dengan skrip PowerShell, Anda harus memiliki modul berikut:

Modul Az PowerShell
Modul Az.EventHub PowerShell

Skrip berikut menginstal modul yang diperlukan:

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

Jika Anda sudah memiliki modul yang diperlukan, dan ingin memperbaruinya ke versi terbaru, jalankan skrip berikut:

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

Hubungkan ke Azure

Anda dapat menggunakan Azure Cloud Shell atau masuk dan mengatur konteks langganan Anda.

Untuk menjalankan dengan Azure Cloud Shell, tinjau Masuk ke Azure.

Menentukan kebijakan

Untuk membuat token SAS, Anda memerlukan kebijakan. Anda dapat:

Buat kebijakan baru dengan hak tertentu.

Atau
Gunakan kebijakan yang ada dengan hak yang benar.

Membuat token SAS untuk kebijakan baru atau yang sudah ada

Nota

Untuk keamanan yang ditingkatkan, autentikasi token SAS sangat disarankan daripada autentikasi berbasis kunci jika memungkinkan. Praktik terbaik untuk token SAS meliputi: menentukan cakupan akses yang sesuai, mengatur tanggal kedaluwarsa, dan memutar kunci SAS secara teratur. Untuk autentikasi berbasis kunci, pastikan kunci diputar secara berkala. Simpan semua rahasia dengan aman menggunakan Azure Key Vault atau layanan serupa.

Saat membuat kebijakan baru, pastikan kebijakan tersebut memiliki hak Kirim . Jika Anda menggunakan kebijakan yang sudah ada, verifikasi bahwa kebijakan tersebut memiliki hak Kirim .

Skrip berikut akan membuat kebijakan baru, atau mendapatkan yang sudah ada, lalu menghasilkan darinya token SAS lengkap dalam format header otorisasi HTTP.

Ganti nilai dalam tanda kurung sudut (<value>) dengan nilai untuk lingkungan Anda.

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

# 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 * 31 * 6)  # 6 months
    $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

Mengaktifkan dan mengonfigurasi streaming peristiwa perubahan

Untuk mengaktifkan dan mengonfigurasi streaming peristiwa perubahan, ubah konteks database ke database pengguna lalu ikuti langkah-langkah berikut:

Jika belum dikonfigurasi, atur database ke model pemulihan penuh.
Buat kunci master dan kredensial yang dicakup oleh database.
Aktifkan streaming acara.
Buat grup aliran peristiwa.
Tambahkan satu atau beberapa tabel ke grup aliran peristiwa.

Contoh di bagian ini menunjukkan cara mengaktifkan CES untuk protokol AMQP dan protokol Apache Kafka.

Berikut ini adalah contoh nilai parameter untuk contoh di bagian ini:

@stream_group_name = N'myStreamGroup'
@destination_location = N'myEventHubsNamespace.servicebus.windows.net/myEventHubsInstance'
@partition_key_scheme = N'None'
Nilai kunci primer atau sekunder: Secret = 'BVFnT3baC/K6I8xNZzio4AeoFt6nHeK0i+ZErNGsxiw='
EXEC sys.sp_add_object_to_event_stream_group N'myStreamGroup', N'dbo.myTable'

Contoh: Streaming ke Azure Event Hubs melalui protokol AMQP (autentikasi token SAS)

Ganti nilai dalam tanda kurung sudut (<value>) dengan nilai untuk lingkungan Anda.

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

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

Contoh: Streaming ke Azure Event Hubs melalui protokol AMQP (Autentikasi nilai kunci)

Ganti nilai dalam tanda kurung sudut (<value>) dengan nilai untuk lingkungan Anda.

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

Contoh: Streaming ke Azure Event Hubs melalui protokol Apache Kafka (Autentikasi string koneksi)

Ganti nilai dalam tanda kurung sudut (<value>) dengan nilai untuk lingkungan Anda.

USE <database name>

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

CREATE DATABASE SCOPED CREDENTIAL credential1
    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>',
    @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>'

Contoh: Streaming ke Azure Event Hubs melalui protokol Apache Kafka (Autentikasi nilai kunci)

Ganti nilai dalam tanda kurung sudut (<value>) dengan nilai untuk lingkungan Anda.

USE <database name>

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

CREATE DATABASE SCOPED CREDENTIAL credential1
    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

Melihat konfigurasi dan fungsi CES

Dalam sys.databases, is_event_stream_enabled = 1 menunjukkan bahwa streaming peristiwa perubahan diaktifkan untuk database.

Kueri berikut mengembalikan semua database dengan streaming peristiwa perubahan diaktifkan:

SELECT * FROM sys.databases WHERE is_event_stream_enabled = 1

Dalam sys.tables, is_replicated = 1 menunjukkan tabel di-streaming, dan sp_help_change_feed_table menyediakan informasi tentang grup tabel dan metadata tabel untuk streaming perubahan peristiwa.

Kueri berikut mengembalikan semua tabel dengan streaming peristiwa perubahan diaktifkan, dan menyediakan informasi metadata:

SELECT name, is_replicated FROM sys.tables

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

Nota

Saat ini, CES tidak didukung pada basis data yang dikonfigurasi dengan pengambilan data perubahan (CDC), replikasi transaksional, atau Fabric Mirrored Databases untuk SQL Server.

Prosedur tersimpan CES, fungsi sistem, dan DMV

Tabel berikut mencantumkan prosedur tersimpan, fungsi sistem, dan DMV yang digunakan untuk mengonfigurasi, menonaktifkan, dan memantau streaming peristiwa perubahan:

Objek sistem	Deskripsi
Mengonfigurasi CES
sys.sp_enable_event_stream	Mengaktifkan CES untuk database pengguna saat ini.
sys.sp_create_event_stream_group	Membuat grup streaming, yang merupakan konfigurasi streaming untuk sekelompok tabel. Grup aliran juga menentukan tujuan dan detail terkait (seperti autentikasi, ukuran pesan, partisi). stream_group_id dibuat dan ditampilkan secara otomatis untuk pengguna akhir saat prosedur selesai.
sys.sp_add_object_to_event_stream_group	Menambahkan tabel ke grup aliran.
Nonaktifkan CES
Untuk menghapus objek dari grup aliran acara, gunakan fungsi sys.sp_remove_object_from_event_stream_group.	Menghapus tabel dari grup aliran.
sys.sp_drop_event_stream_group	Menjatuhkan grup aliran. Grup aliran tidak boleh digunakan.
sys.sp_disable_event_stream	Menonaktifkan CES untuk database pengguna saat ini.
Memantau CES
sys.dm_change_feed_errors	Mengembalikan kesalahan pengiriman.
sys.dm_change_feed_log_scan_sessions	Mengembalikan informasi tentang aktivitas pemindaian log.
sys.sp_help_change_feed_settings	Menyediakan status dan informasi streaming peristiwa perubahan yang dikonfigurasi.
sys.sp_help_change_feed (sistem.sp_bantu_ubah_umpan)	Memantau konfigurasi aliran perubahan saat ini.
sys.sp_help_change_feed_table_groups	Mengembalikan metadata yang digunakan untuk mengonfigurasi perubahan grup streaming peristiwa.
sys.sp_help_change_feed_table	Menyediakan status dan informasi grup streaming dan metadata tabel untuk mengubah streaming peristiwa.

Keterbatasan

Streaming perubahan acara (CES) memiliki batasan berikut:

Batasan tingkat server dan umum

CES tidak didukung pada SQL Server 2025 di Linux atau edisi SQL Server 2025 Express.
CES memancarkan peristiwa hanya untuk perubahan data dari pernyataan DML INSERT, UPDATE, dan DELETE.
CES tidak menangani perubahan skema (operasi DDL), yang berarti tidak akan memancarkan peristiwa untuk operasi DDL. Namun, operasi DDL tidak diblokir, jadi jika dijalankan, skema peristiwa DML berikutnya mencerminkan struktur tabel yang diperbarui. Pengguna diharapkan untuk menangani peristiwa dengan baik dengan skema yang diperbarui.
Ketika JSON adalah format output yang telah ditentukan, pesan peristiwa besar dapat dibagi sekitar 25% dari ukuran maksimum pesan yang dikonfigurasi per kelompok aliran. Batasan ini tidak berlaku untuk jenis output biner.
Jika pesan melebihi batas ukuran pesan Azure Event Hubs, kegagalan saat ini hanya dapat diamati melalui Peristiwa yang Diperluas.
Penggantian nama tabel dan kolom diblokir untuk tabel yang dikonfigurasi untuk CES. Penggantian nama database diperbolehkan.

Batasan pada tingkat database

CES hanya didukung pada database yang dikonfigurasi dengan model pemulihan penuh.
CES tidak didukung pada database yang dikonfigurasi dengan Database Cermin Fabric untuk SQL Server, replikasi transaksional, perekaman perubahan data, atau Azure Synapse Link. Pelacakan perubahan didukung pada database yang dikonfigurasi dengan CES.
CES hanya dapat melakukan streaming dari database utama yang dapat ditulis. Database sekunder yang merupakan bagian dari grup ketersediaan AlwaysOn atau yang menggunakan Tautan Instans Terkelola tidak dapat dikonfigurasi sebagai sumber streaming.
CES tidak dapat diaktifkan pada tampilan atau tampilan materialisasi.

Batasan pada tingkat tabel

Tabel hanya dapat termasuk dalam satu grup streaming. Streaming tabel yang sama ke beberapa tujuan tidak didukung.
Hanya tabel pengguna yang dapat dikonfigurasi untuk CES. Tabel sistem tidak didukung.
Anda dapat mengonfigurasi hingga 4.096 grup aliran. Setiap grup aliran dapat menyertakan hingga 40.000 tabel.
Saat CES diaktifkan pada tabel, batasan kunci utama tidak dapat ditambahkan ke, atau dihilangkan dari tabel tersebut.
ALTER TABLE SWITCH PARTITION tidak didukung pada tabel yang dikonfigurasi untuk CES.
TRUNCATE TABLE tidak didukung pada tabel yang telah diaktifkan untuk CES.
CES tidak mendukung tabel yang menggunakan salah satu fitur berikut:
- Indeks penyimpan kolom berkluster
- Tabel riwayat temporal atau tabel riwayat ledger
- Selalu Terenkripsi
- OLTP dalam memori (tabel yang dioptimalkan memori)
- Tabel grafik
- Tabel eksternal

Batasan tingkat kolom

Jenis data berikut tidak didukung oleh CES. Kolom jenis ini dilewati oleh streaming:
- json
- image
- text / ntext
- xml
- rowversion / timestamp
- sql_variant
- Jenis yang ditentukan pengguna (UDT)
- geometry
- geography
- vector

Izin dalam database sumber

Untuk keamanan tingkat baris, CES mengeluarkan perubahan dari semua baris, terlepas dari hak akses pengguna.
Masking data dinamis tidak berlaku untuk data yang dikirim melalui CES. Data dikirimkan tanpa penyamaran, bahkan jika masking sudah dikonfigurasi.
CES tidak memancarkan peristiwa yang terkait dengan perubahan izin tingkat objek (misalnya, memberikan izin ke kolom tertentu).

Bagikan melalui

Mengonfigurasi streaming peristiwa perubahan

Gambaran Umum

Prasyarat

Mengonfigurasi Azure Event Hubs

Menginstal modul yang diperlukan

Hubungkan ke Azure

Menentukan kebijakan

Membuat token SAS untuk kebijakan baru atau yang sudah ada

Mengaktifkan dan mengonfigurasi streaming peristiwa perubahan

Contoh: Streaming ke Azure Event Hubs melalui protokol AMQP (autentikasi token SAS)

Contoh: Streaming ke Azure Event Hubs melalui protokol AMQP (Autentikasi nilai kunci)

Contoh: Streaming ke Azure Event Hubs melalui protokol Apache Kafka (Autentikasi string koneksi)

Contoh: Streaming ke Azure Event Hubs melalui protokol Apache Kafka (Autentikasi nilai kunci)

Melihat konfigurasi dan fungsi CES

Prosedur tersimpan CES, fungsi sistem, dan DMV

Keterbatasan

Batasan tingkat server dan umum

Batasan pada tingkat database

Batasan pada tingkat tabel

Batasan tingkat kolom

Izin dalam database sumber

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: