Bekerja dengan Pemberitahuan Kueri

Berlaku untuk:SQL ServerAzure SQL Managed Instance

Penting

SQL Server Native Client (sering disingkat SNAC) telah dihapus dari SQL Server 2022 (16.x) dan SQL Server Management Studio 19 (SSMS). SQL Server Native Client (SQLNCLI atau SQLNCLI11) dan Penyedia Microsoft OLE DB warisan untuk SQL Server (SQLOLEDB) tidak direkomendasikan untuk pengembangan aplikasi baru. Beralih ke Microsoft OLE DB Driver (MSOLEDBSQL) baru untuk SQL Server atau Microsoft ODBC Driver terbaru untuk SQL Server ke depannya. Untuk SQLNCLI yang dikirim sebagai komponen SQL Server Database Engine (versi 2012 hingga 2019), lihat pengecualian Siklus Hidup Dukungan ini.

Pemberitahuan kueri diperkenalkan di SQL Server 2005 (9.x) dan SQL Server Native Client. Dibangun di atas infrastruktur Service Broker yang diperkenalkan di SQL Server 2005 (9.x), pemberitahuan kueri memungkinkan aplikasi untuk diberi tahu ketika data telah berubah. Fitur ini sangat berguna untuk aplikasi yang menyediakan cache informasi dari database, seperti aplikasi Web, dan perlu diberi tahu saat data sumber diubah.

Pemberitahuan kueri memungkinkan Anda meminta pemberitahuan dalam periode batas waktu tertentu saat data yang mendasar kueri berubah. Permintaan pemberitahuan menentukan opsi pemberitahuan, yang mencakup nama layanan, teks pesan, dan nilai waktu habis ke server. Pemberitahuan dikirimkan melalui antrean Service Broker bahwa aplikasi dapat melakukan polling untuk pemberitahuan yang tersedia.

Sintaksis string opsi pemberitahuan kueri adalah:

service=<service-name>[;(local database=<database> | broker instance=<broker instance>)]

Contohnya:

service=mySSBService;local database=mydb

Langganan pemberitahuan lebih lama dari proses yang memulainya, karena aplikasi dapat membuat langganan pemberitahuan lalu mengakhiri. Langganan tetap valid, dan pemberitahuan akan terjadi jika data berubah dalam periode waktu habis yang ditentukan saat langganan dibuat. Pemberitahuan diidentifikasi oleh kueri yang dijalankan, opsi pemberitahuan, dan teks pesan, dan dapat dibatalkan dengan mengatur nilai batas waktunya menjadi nol.

Pemberitahuan dikirim hanya sekali. Untuk pemberitahuan perubahan data berkelanjutan, langganan baru harus dibuat dengan menjalankan ulang kueri setelah setiap pemberitahuan diproses.

Aplikasi Klien Asli SQL Server biasanya menerima pemberitahuan dengan menggunakan perintah Transact-SQL RECEIVE untuk membaca pemberitahuan dari antrean yang terkait dengan layanan yang ditentukan dalam opsi pemberitahuan.

Catatan

Nama tabel harus memenuhi syarat dalam kueri yang pemberitahuannya diperlukan, misalnya, dbo.myTable. Nama tabel harus memenuhi syarat dengan dua nama bagian. Langganan tidak valid jika nama tiga atau empat bagian digunakan.

Infrastruktur pemberitahuan dibangun di atas fitur antrean yang diperkenalkan di SQL Server 2005 (9.x). Secara umum, pemberitahuan yang dihasilkan di server dikirim melalui antrean ini untuk diproses nanti.

Untuk menggunakan pemberitahuan kueri, antrean dan layanan harus ada di server. Ini dapat dibuat menggunakan Transact-SQL yang mirip dengan yang berikut ini:

CREATE QUEUE myQueue  
CREATE SERVICE myService ON QUEUE myQueue   
  
([http://schemas.microsoft.com/SQL/Notifications/PostQueryNotification])  

Catatan

Layanan harus menggunakan kontrak http://schemas.microsoft.com/SQL/Notifications/PostQueryNotification yang telah ditentukan sebelumnya seperti yang ditunjukkan di atas.

Penyedia OLE DB Klien Asli SQL Server

Penyedia SQL Server Native Client OLE DB mendukung pemberitahuan konsumen tentang modifikasi set baris. Konsumen menerima pemberitahuan di setiap fase modifikasi set baris dan pada setiap upaya perubahan.

Catatan

Meneruskan kueri pemberitahuan ke server dengan ICommand::Execute adalah satu-satunya cara yang valid untuk berlangganan pemberitahuan kueri dengan penyedia SQL Server Native Client OLE DB.

Kumpulan Properti DBPROPSET_SQLSERVERROWSET

Untuk mendukung pemberitahuan kueri melalui OLE DB, SQL Server Native Client menambahkan properti baru berikut ke kumpulan properti DBPROPSET_SQLSERVERROWSET.

Nama	Tipe	Deskripsi
SSPROP_QP_NOTIFICATION_TIMEOUT	VT_UI4	Jumlah detik pemberitahuan kueri akan tetap aktif. Defaultnya adalah 432000 detik (5 hari). Nilai minimum adalah 1 detik, dan nilai maksimum adalah 2^31-1 detik.
SSPROP_QP_NOTIFICATION_MSGTEXT	VT_BSTR	Teks pesan pemberitahuan. Ini ditentukan pengguna, dan tidak memiliki format yang telah ditentukan sebelumnya. Secara default, string kosong. Anda dapat menentukan pesan menggunakan 1-2000 karakter.
SSPROP_QP_NOTIFICATION_OPTIONS	VT_BSTR	Opsi pemberitahuan kueri. Ini ditentukan dalam string dengan sintaks nilai nama=. Pengguna bertanggung jawab untuk membuat layanan dan membaca pemberitahuan dari antrean. Defaultnya adalah string kosong.

Langganan pemberitahuan selalu diterapkan, terlepas dari apakah pernyataan berjalan dalam transaksi pengguna atau dalam penerapan otomatis atau apakah transaksi di mana pernyataan dijalankan atau digulung balik. Pemberitahuan server diaktifkan pada salah satu kondisi pemberitahuan yang tidak valid berikut: perubahan data atau skema yang mendasar, atau ketika periode batas waktu tercapai; mana saja yang pertama. Pendaftaran pemberitahuan dihapus segera setelah dipecat. Oleh karena itu setelah menerima pemberitahuan, aplikasi harus berlangganan lagi jika mereka ingin mendapatkan pembaruan lebih lanjut.

Koneksi atau utas lain dapat memeriksa antrean tujuan untuk pemberitahuan. Contohnya:

WAITFOR (RECEIVE * FROM MyQueue);   // Where MyQueue is the queue name.   

Perhatikan bahwa SELECT * tidak menghapus entri dari Antrean, namun RECEIVE * FROM tidak. Ini mengulur utas server jika antrean kosong. Jika ada entri antrean pada saat panggilan, mereka akan segera dikembalikan; jika tidak, panggilan menunggu hingga entri antrean dilakukan.

RECEIVE * FROM MyQueue  

Pernyataan ini segera mengembalikan hasil kosong yang ditetapkan jika antrean kosong; jika tidak, ia mengembalikan semua pemberitahuan antrean.

Jika SSPROP_QP_NOTIFICATION_MSGTEXT dan SSPROP_QP_NOTIFICATION_OPTIONS non-NULL dan tidak kosong, header TDS pemberitahuan kueri yang berisi tiga properti yang ditentukan di atas dikirim ke server dengan setiap eksekusi perintah. Jika salah satunya null (atau kosong), header tidak dikirim dan DB_E_ERRORSOCCURRED dinaikkan, (atau DB_S_ERRORSOCCURRED jika properti ditandai sebagai opsional), dan nilai status diatur ke DBPROPSTATUS_BADVALUE. Validasi terjadi pada Jalankan/Siapkan. Demikian pula, DB_S_ERRORSOCCURED dimunculkan ketika properti pemberitahuan kueri diatur untuk koneksi ke versi SQL Server sebelum SQL Server 2005 (9.x). Nilai status dalam kasus ini DBPROPSTATUS_NOTSUPPORTED.

Memulai langganan tidak menjamin bahwa pesan berikutnya akan berhasil dikirimkan. Selain itu, tidak ada pemeriksaan yang dilakukan mengenai validitas nama layanan yang ditentukan.

Catatan

Menyiapkan pernyataan tidak akan pernah menyebabkan langganan dimulai; hanya eksekusi pernyataan yang akan mencapai ini dan pemberitahuan kueri tidak terpengaruh oleh penggunaan layanan inti OLE DB.

Untuk informasi selengkapnya tentang kumpulan properti DBPROPSET_SQLSERVERROWSET, lihat Properti dan Perilaku Set Baris.

Driver ODBC Klien Asli SQL Server

Driver ODBC SQL Server Native Client mendukung pemberitahuan kueri melalui penambahan tiga atribut baru ke fungsi SQLGetStmtAttr dan SQLSetStmtAttr :

• SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

• SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

• SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

Jika SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT dan SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS bukan NULL, header TDS pemberitahuan kueri yang berisi tiga atribut yang ditentukan di atas akan dikirim ke server setiap kali perintah dijalankan. Jika salah satunya null, header tidak dikirim, dan SQL_SUCCESS_WITH_INFO dikembalikan. Validasi terjadi pada Fungsi SQLPrepare, SqlExecDirect, dan SqlExecute, yang semuanya gagal jika atribut tidak valid. Demikian pula, ketika atribut pemberitahuan kueri ini diatur untuk versi SQL Server sebelum SQL Server 2005 (9.x), eksekusi gagal dengan SQL_SUCCESS_WITH_INFO.

Catatan

Pernyataan persiapan tidak akan pernah menyebabkan langganan dimulai; langganan dapat dimulai dengan eksekusi pernyataan.

Kasus dan Pembatasan Khusus

Jenis data berikut ini tidak didukung untuk pemberitahuan:

• text

• ntext

• gambar

Jika permintaan pemberitahuan dibuat untuk kueri yang mengembalikan salah satu jenis ini, pemberitahuan akan segera diaktifkan, menentukan bahwa langganan pemberitahuan tidak dimungkinkan.

Jika permintaan langganan dibuat untuk prosedur batch atau tersimpan, permintaan langganan terpisah dibuat untuk setiap pernyataan yang dijalankan dalam prosedur batch atau tersimpan. Pernyataan EXECUTE tidak akan mendaftarkan pemberitahuan, tetapi akan mengirim permintaan pemberitahuan ke perintah yang dijalankan. Jika ini adalah batch, konteks akan diterapkan ke pernyataan yang dijalankan dan aturan yang sama seperti yang dijelaskan di atas berlaku.

Pengiriman kueri untuk pemberitahuan yang dikirimkan oleh pengguna yang sama di bawah konteks database yang sama dan memiliki templat yang sama, nilai parameter yang sama, ID pemberitahuan yang sama, dan lokasi pengiriman yang sama dari langganan aktif yang ada, akan memperbarui langganan yang ada, mengatur ulang batas waktu baru yang ditentukan. Ini berarti bahwa jika pemberitahuan diminta untuk kueri yang identik, hanya satu pemberitahuan yang akan dikirim. Ini akan berlaku untuk kueri yang diduplikasi dalam batch, atau kueri dalam prosedur tersimpan yang dipanggil beberapa kali.

Lihat Juga

Fitur Klien Asli SQL Server