Bekerja dengan Pemberitahuan Kueri
Berlaku untuk:
SQL Server Azure SQL Managed Instance
Penting
SQL Server Native Client (SNAC) tidak dikirim dengan:
- SQL Server 2022 (16.x) dan versi yang lebih baru
- SQL Server Management Studio 19 dan versi yang lebih baru
SQL Server Native Client (SQLNCLI atau SQLNCLI11) dan Penyedia Microsoft OLE DB warisan untuk SQL Server (SQLOLEDB) tidak direkomendasikan untuk pengembangan aplikasi baru.
Untuk proyek baru, gunakan salah satu driver berikut:
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.