Arbeiten mit AbfragebenachrichtigungenWorking with Query Notifications

Gilt für: JaSQL Server JaAzure SQL-Datenbank (nur verwaltete Instanz) NeinAzure Synapse Analytics (SQL DW) NeinParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database (Managed Instance only) noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Abfragebenachrichtigungen wurden in SQL Server 2005 (9.x)SQL Server 2005 (9.x) und SQL ServerSQL Server Native Client eingeführt.Query notifications were introduced in SQL Server 2005 (9.x)SQL Server 2005 (9.x) and SQL ServerSQL Server Native Client. Mit Abfragebenachrichtigungen, die auf der in SQL Server 2005 (9.x)SQL Server 2005 (9.x) eingeführten Service Broker-Infrastruktur aufsetzen, können Anwendungen benachrichtigt werden, wenn sich Daten geändert haben.Built upon the Service Broker infrastructure introduced in SQL Server 2005 (9.x)SQL Server 2005 (9.x), query notifications allow applications to be notified when data has changed. Diese Funktion ist besonders nützlich für Anwendungen, die einen Informationscache aus einer Datenbank zur Verfügung stellen, z. B. eine Webanwendung, und die benachrichtigt werden müssen, wenn die Quelldaten geändert wurden.This feature is particularly useful for applications that provide a cache of information from a database, such as a Web application, and need to be notified when the source data is changed.

Mit Abfragebenachrichtigungen können Sie eine Benachrichtigung innerhalb eines festgelegten Timeoutzeitraums anfordern, wenn sich die einer Abfrage zugrunde liegenden Daten ändern.Query notifications allow you to request notification within a specified time-out period when the underlying data of a query changes. Die Anforderung für die Benachrichtigung gibt die Benachrichtigungsoptionen an. Dazu gehören der Dienstname, der Meldungstext und der Timeoutwert für den Server.The request for notification specifies the notification options, which include the service name, message text, and time-out value to the server. Benachrichtigungen werden durch eine Service Broker-Warteschlange übermittelt, von der Anwendungen verfügbare Benachrichtigungen abrufen können.Notifications are delivered through a Service Broker queue that applications may poll for available notifications.

Die Syntax der Zeichenfolge für die Abfragebenachrichtigungsoptionen lautet:The syntax of the query notifications options string is:

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

Beispiel:For example:

service=mySSBService;local database=mydb

Benachrichtigungsabonnements überdauern den Prozess, mit dem sie initiiert wurden, da eine Anwendung ein Benachrichtigungsabonnement erstellen und anschließend beendet werden kann.Notification subscriptions outlive the process that initiates them, as an application may create a notification subscription and then terminate. Das Abonnement bleibt gültig, und die Benachrichtigung wird gesendet, wenn die Daten innerhalb des während der Erstellung des Abonnements angegebenen Timeoutzeitraums geändert werden.The subscription remains valid, and the notification will occur if the data changes within the time-out period specified when the subscription was created. Eine Benachrichtigung wird durch die ausgeführte Abfrage, die Benachrichtigungsoptionen und den Meldungstext identifiziert und wird möglicherweise abgebrochen, wenn der Timeoutwert auf NULL festgelegt wird.A notification is identified by the query executed, the notification options, and the message text, and may be cancelled by setting its time-out value to zero.

Benachrichtigungen werden nur einmal gesendet.Notifications are sent only once. Für die kontinuierliche Benachrichtigung bei Datenänderungen müssen Sie ein neues Abonnement erstellen, indem Sie die Abfrage nach der Verarbeitung jeder Benachrichtigung erneut ausführen.For continuous notification of data change, a new subscription must be created by re-executing the query after each notification is processed.

SQL ServerSQL Server Native Client-Anwendungen erhalten in der Regel Benachrichtigungen, indem Sie den Transact-SQLTransact-SQL Receive -Befehl verwenden, um Benachrichtigungen aus der Warteschlange zu lesen, die dem in den Benachrichtigungs Optionen angegebenen Dienst zugeordnetNative Client applications typically receive notifications by using the Transact-SQLTransact-SQL RECEIVE command to read notifications from the queue associated with the service specified in the notification options.

Hinweis

Tabellennamen müssen in Abfragen qualifiziert werden, für die Benachrichtigungen erforderlich sind, z. B. dbo.myTable.Table names must be qualified in queries for which notification is required, for example, dbo.myTable. Tabellennamen müssen mit zwei Teilnamen qualifiziert werden.Table names must be qualified with two part names. Das Abonnement ist ungültig, wenn drei oder vier Teilnamen verwendet werden.Subscription is invalid if three- or four-part names are used.

Die Benachrichtigungsinfrastruktur setzt auf einer in SQL Server 2005 (9.x)SQL Server 2005 (9.x) eingeführten Queuing-Funktion auf.The notification infrastructure is built on top of a queuing feature introduced in SQL Server 2005 (9.x)SQL Server 2005 (9.x). Im Allgemeinen werden auf dem Server generierte Benachrichtigungen durch diese Warteschlangen gesendet, um später verarbeitet zu werden.In general, notifications generated at the server are sent through these queues to be processed later.

Für die Verwendung von Abfragebenachrichtigungen ist eine Warteschlange und ein Dienst auf dem Server erforderlich.To use query notifications a queue and a service must exist on the server. Diese können mit Transact-SQLTransact-SQL erstellt werden, wie in folgendem Beispiel veranschaulicht:These can be created using Transact-SQLTransact-SQL similar to the following:

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

Hinweis

Der Dienst muss den vordefinierten Vertrag https://schemas.microsoft.com/SQL/Notifications/PostQueryNotification verwenden wie oben dargestellt.The service must use the predefined contract https://schemas.microsoft.com/SQL/Notifications/PostQueryNotification as shown above.

SQL Server Native Client OLE DB-AnbieterSQL Server Native Client OLE DB Provider

Der SQL ServerSQL Server Native Client OLE DB-Anbieter unterstützt Consumer-Benachrichtigungen bei der Änderung von Rowsets.The SQL ServerSQL Server Native Client OLE DB provider supports consumer notification on rowset modification. Der Consumer erhält in jeder Phase der Rowsetänderung und bei jeder versuchten Änderung eine Benachrichtigung.The consumer receives notification at every phase of rowset modification and on any attempted change.

Hinweis

Das übergeben einer Benachrichtigungs Abfrage an den Server mit ICommand:: Execute ist die einzige gültige Methode zum Abonnieren von Abfrage Benachrichtigungen mit dem SQL ServerSQL Server Native Client OLE DB-Anbieter.Passing a notifications query to the server with ICommand::Execute is the only valid way to subscribe to query notifications with the SQL ServerSQL Server Native Client OLE DB provider.

Die DBPROPSET_SQLSERVERROWSET-EigenschaftsgruppeThe DBPROPSET_SQLSERVERROWSET Property Set

Um Abfrage Benachrichtigungen über OLE DB zu unterstützen, fügt SQL ServerSQL Server Native Client dem DBPROPSET_SQLSERVERROWSET-Eigenschaften Satz die folgenden neuen Eigenschaften hinzu.In order to support query notifications through OLE DB, SQL ServerSQL Server Native Client adds the following new properties to the DBPROPSET_SQLSERVERROWSET property set.

NameName TypType BeschreibungDescription
SSPROP_QP_NOTIFICATION_TIMEOUTSSPROP_QP_NOTIFICATION_TIMEOUT VT_UI4VT_UI4 Die Anzahl der Sekunden, die die Abfragebenachrichtigung aktiv bleiben soll.The number of seconds that the query notification is to remain active.

Der Standardwert ist 432000 Sekunden (5 Tage).The default is 432000 seconds (5 days). Der Mindestwert ist 1 Sekunde und der Höchstwert 2^31-1 Sekunden.The minimum value is 1 second, and the maximum value is 2^31-1 seconds.
SSPROP_QP_NOTIFICATION_MSGTEXTSSPROP_QP_NOTIFICATION_MSGTEXT VT_BSTRVT_BSTR Der Text der Benachrichtigung.The message text of the notification. Dieser ist benutzerdefiniert und weist kein vordefiniertes Format auf.This is user defined, and has no predefined format.

Standardmäßig ist die Zeichenfolge leer.By default, the string is empty. Sie können eine Meldung mit 1-2000 Zeichen angeben.You can specify a message using 1-2000 characters.
SSPROP_QP_NOTIFICATION_OPTIONSSSPROP_QP_NOTIFICATION_OPTIONS VT_BSTRVT_BSTR Die Abfragebenachrichtigungsoptionen.The query notification options. Diese werden in einer Zeichenfolge mit der Syntax name=value angegeben.These are specified in a string with name=value syntax. Der Benutzer ist für das Erstellen des Diensts und Lesen von Benachrichtigungen von der Warteschlange verantwortlich.The user is responsible for creating the service and reading notifications off of the queue.

Der Standardwert ist eine leere Zeichenfolge.The default is an empty string.

Für das Benachrichtigungsabonnement wird immer ein Commit durchgeführt, unabhängig davon, ob die Anweisung in einer Benutzertransaktion oder im Autocommitmodus ausgeführt wurde oder ob für die Transaktion, in der die Anweisung ausgeführt wurde, ein Commit oder Rollback durchgeführt wurde.The notification subscription is always committed, regardless of whether the statement ran in a user transaction or in auto commit or whether the transaction in which the statement ran committed or rolled back. Die Serverbenachrichtigung wird bei einer der folgenden unzulässigen Benachrichtigungsbedingungen ausgelöst: bei einer Änderung der zugrunde liegenden Daten oder des zugrunde liegenden Schemas oder bei Erreichung des Timeoutzeitraums, je nachdem, welches Ereignis früher eintritt.The server notification fires upon any of the following invalid notification conditions: change of underlying data or schema, or when the timeout period is reached; whichever is first. Benachrichtigungsregistrierungen werden gelöscht, sobald sie ausgelöst wurden.Notification registrations are deleted as soon as they are fired. Nach dem Empfang von Benachrichtigungen muss die Anwendung das Abonnement erneuern für den Fall, dass weitere Updates abgerufen werden sollen.Hence upon receiving notifications, the application must subscribe again in case they want to get further updates.

Eine andere Verbindung oder ein Thread kann die Zielwarteschlange auf Benachrichtigungen überprüfen.Another connection or thread can check the destination queue for notifications. Beispiel:For example:

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

Beachten Sie, dass SELECT * den Eintrag in der Warteschlange nicht löscht, RECEIVE * FROM jedoch schon.Note that SELECT * does not delete the entry from the Queue, however RECEIVE * FROM does. Dadurch wird ein Serverthread blockiert, wenn die Warteschlange leer ist.This stalls a server thread if the queue is empty. Wenn zum Zeitpunkt des Aufrufs Warteschlangeneinträge vorhanden sind, werden sie unmittelbar zurückgegeben. Andernfalls wartet der Aufruf, bis ein Warteschlangeneintrag vorgenommen wird.If there are queue entries at the time of the call, they are returned immediately; otherwise the call waits until a queue entry is made.

RECEIVE * FROM MyQueue  

Diese Anweisung gibt unverzüglich ein leeres Resultset zurück, wenn die Warteschlange leer ist. Andernfalls gibt sie alle Warteschlangenbenachrichtigungen zurück.This statement immediately returns an empty result set if the queue is empty; otherwise it returns all queue notifications.

Wenn SSPROP_QP_NOTIFICATION_MSGTEXT und SSPROP_QP_NOTIFICATION_OPTIONS nicht NULL und nicht leer sind, wird der TDS-Abfragebenachrichtigungsheader mit den drei oben definierten Eigenschaften bei jeder Ausführung des Befehls an den Server gesendet.If SSPROP_QP_NOTIFICATION_MSGTEXT and SSPROP_QP_NOTIFICATION_OPTIONS are non-NULL and non-empty, the query notifications TDS header containing the three properties defined above are sent to the server with each execution of the command. Wenn einer der Werte NULL (oder leer) ist, wird der Header nicht gesendet und DB_E_ERRORSOCCURRED ausgelöst (oder DB_S_ERRORSOCCURRED, wenn die Eigenschaften beide als optional gekennzeichnet sind). Der Statuswert wird auf DBPROPSTATUS_BADVALUE festgelegt.If either of them is null (or empty), the header is not sent and DB_E_ERRORSOCCURRED is raised, (or DB_S_ERRORSOCCURRED if the properties are both marked as optional), and the status value is set to DBPROPSTATUS_BADVALUE. Die Überprüfung wird bei Ausführen/Vorbereiten vorgenommen.The validation occurs on Execute/Prepare. Entsprechend wird DB_S_ERRORSOCCURED ausgelöst, wenn die Abfragebenachrichtigungseigenschaften für Verbindungen mit SQL ServerSQL Server-Versionen vor SQL Server 2005 (9.x)SQL Server 2005 (9.x) festgelegt wurden.Similarly, DB_S_ERRORSOCCURED is raised when the query notification properties are set for connections to SQL ServerSQL Server versions before SQL Server 2005 (9.x)SQL Server 2005 (9.x). In diesem Fall ist der Statuswert DBPROPSTATUS_NOTSUPPORTED.The status value in this case is DBPROPSTATUS_NOTSUPPORTED.

Ein Abonnement zu initiieren gewährleistet nicht, dass nachfolgende Meldungen erfolgreich übermittelt werden.Initiating a subscription does not guarantee that subsequent messages will be successfully delivered. Außerdem wird keine Prüfung im Hinblick auf die Gültigkeit des angegebenen Dienstnamens durchgeführt.In addition, no check is made as to the validity of the service name specified.

Hinweis

Durch Vorbereiten der Anweisungen wird nie eine Initiierung des Abonnements ausgelöst. Dies wird nur durch die Ausführung der Anweisung erreicht. Abfragebenachrichtigungen werden von der Verwendung von OLE DB-Basisdiensten nicht beeinflusst.Preparing statements will never cause the subscription to be initiated; only statement execution will achieve this and query notifications are not impacted by the use of OLE DB core services.

Weitere Informationen zum DBPROPSET_SQLSERVERROWSET-Eigenschaften Satz finden Sie unter Eigenschaften und Verhaltensweisen von Rowsets.For more information about the DBPROPSET_SQLSERVERROWSET property set, see Rowset Properties and Behaviors.

ODBC-Treiber für SQL Server Native ClientSQL Server Native Client ODBC Driver

Der SQL ServerSQL Server Native Client ODBC-Treiber unterstützt Abfrage Benachrichtigungen durch das Hinzufügen von drei neuen Attributen zu den Funktionen SQLGetStmtAttr und SQLSetStmtAttr :The SQL ServerSQL Server Native Client ODBC driver supports query notifications through the addition of three new attributes to the SQLGetStmtAttr and SQLSetStmtAttr functions:

  • SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXTSQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT

  • SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONSSQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS

  • SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUTSQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT

Wenn SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT und SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS nicht NULL sind, wird der TDS-Abfragebenachrichtigungsheader mit den drei oben definierten Attributen bei jeder Ausführung des Befehls an den Server gesendet.If SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT and SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS are not NULL, the query notifications TDS header containing the three attributes defined above will be sent to the server each time the command is executed. Wenn eine der Eigenschaften NULL ist, wird der Header nicht gesendet und SQL_SUCCESS_WITH_INFO zurückgegeben.If either of them is null, the header is not sent, and SQL_SUCCESS_WITH_INFO is returned. Die Überprüfung erfolgt auf der SQLPrepare-Funktion, SQLExecDirectund SQLExecute, die alle fehlschlagen, wenn die Attribute nicht gültig sind.The validation occurs on SQLPrepare Function, SqlExecDirect, and SqlExecute, all of which fail if the attributes are not valid. Entsprechend schlägt die Ausführung mit SQL_SUCCESS_WITH_INFO fehl, wenn diese Abfragebenachrichtigungsattribute für SQL ServerSQL Server-Versionen vor SQL Server 2005 (9.x)SQL Server 2005 (9.x) festgelegt werden.Similarly, when these query notification attributes are set for SQL ServerSQL Server versions before SQL Server 2005 (9.x)SQL Server 2005 (9.x), the execution fails with SQL_SUCCESS_WITH_INFO.

Hinweis

Durch Vorbereiten der Anweisungen wird nie eine Initiierung des Abonnements ausgelöst. Das Abonnement kann nur durch die Anweisungsausführung initiiert werden.Prepare statements will never cause the subscription to be initiated; subscription can be initiated by statement execution.

Sonderfälle und EinschränkungenSpecial Cases and Restrictions

Die folgenden Datentypen werden für Benachrichtigungen nicht unterstützt:The following data types are not supported for notifications:

  • texttext

  • ntextntext

  • imageimage

Wenn eine Benachrichtigungsanforderung für eine Abfrage gesendet wird, die einen dieser Typen zurückgibt, wird die Benachrichtigung sofort mit dem Hinweis ausgelöst, dass das Benachrichtigungsabonnement nicht möglich sei.If a notification request is made for a query which returns any of these types, the notification fires immediately, specifying that notification subscription was not possible.

Wenn eine Abonnementanforderung für einen Batch oder eine gespeicherte Prozedur erfolgt, wird für jede Anweisung, die innerhalb des Batches oder der gespeicherten Prozedur ausgeführt wird, eine separate Abonnementanforderung ausgegeben.If a subscription request is made for a batch or stored procedure, a separate subscription request is made for each statement executed within the batch or stored procedure. EXECUTE-Anweisungen registrieren keine Benachrichtigung, sondern senden die Benachrichtigungsanforderung an den ausgeführten Befehl.EXECUTE statements will not register a notification, but will send the notification request to the executed command. Wenn es sich um einen Batch handelt, wird der Kontext auf die ausgeführten Anweisungen angewendet, und es gelten die gleichen Regeln wie oben beschrieben.If it is a batch, the context will be applied to the executed statements and the same rules described above apply.

Die Übermittlung einer Abfrage für eine Benachrichtigung, die vom gleichen Benutzer unter demselben Daten Bank Kontext gesendet wurde und die dieselbe Vorlage, dieselben Parameterwerte, dieselbe Benachrichtigungs-ID und denselben Übermittlungs Speicherort eines vorhandenen aktiven Abonnements aufweist, erneuert die vorhandene Abonnement, das das neue angegebene Timeout zurücksetzt. Dies bedeutet, dass nur eine Benachrichtigung gesendet wird, wenn eine Benachrichtigung für identische Abfragen angefordert wird.Submission of a query for notification that was submitted by the same user under the same database context and has the same template, same parameter values, same notification ID, and same delivery location of an existing active subscription, will renew the existing subscription, resetting the new specified time-out. This means that if notification is requested for identical queries, only one notification will be sent. Dies gilt sowohl für Abfragen, die in einem Batch dupliziert werden, als auch für Abfragen in einer gespeicherten Prozedur, die mehrmals aufgerufen wurde.This would apply to a query duplicated in a batch, or a query in a stored procedure that was called multiple times.

Siehe auchSee Also

SQL Server Native Client-FeaturesSQL Server Native Client Features