CREATE EVENT NOTIFICATION (Transact-SQL)

S’applique à :SQL ServerAzure SQL Managed Instance

Crée un objet qui envoie des informations sur un événement de base de données ou de serveur à un service Service Broker. Les notifications d'événements sont créées uniquement au moyen d'instructions Transact-SQL.

Conventions de la syntaxe Transact-SQL

Syntaxe

CREATE EVENT NOTIFICATION event_notification_name   
ON { SERVER | DATABASE | QUEUE queue_name }   
[ WITH FAN_IN ]  
FOR { event_type | event_group } [ ,...n ]  
TO SERVICE 'broker_service' , { 'broker_instance_specifier' | 'current database' }  
[ ; ]  

Arguments

event_notification_name
Nom de la notification d’événement. Un nom de notification d’événements doit être conforme aux règles applicables aux identificateurs et être unique dans l’étendue où il est créé : SERVER, DATABASE ou object_name.

SERVER
Applique l'étendue de la notification d'événement à l'instance actuelle de SQL Server. Si SERVER est spécifié, la notification se déclenche lorsque l'événement spécifié dans la clause FOR se produit n'importe où dans l'instance de SQL Server.

DATABASE
Applique l'étendue de la notification d'événement à la base de données actuelle. Si DATABASE est spécifié, la notification se déclenche lorsque l'événement spécifié dans la clause FOR se produit n'importe où dans la base de données actuelle.

QUEUE
Applique l'étendue de la notification à une file d'attente spécifique dans la base de données actuelle. QUEUE peut être spécifié seulement si FOR QUEUE_ACTIVATION ou FOR BROKER_QUEUE_DISABLED est également spécifié.

queue_name
Nom de la file d'attente à laquelle la notification d'événement s'applique. queue_name peut être spécifié seulement si QUEUE est défini.

WITH FAN_IN
Indique à SQL Server d'envoyer un seul message par événement au service spécifié pour toutes les notifications d'événement qui :

• sont créées pour le même événement ;

• sont créées par le même principal (identifié par le même SID).

• Spécifient le même service et broker_instance_specifier.

• spécifient WITH FAN_IN.

Par exemple, trois notifications d'événements sont créées. Toutes les notifications d'événements spécifient FOR ALTER_TABLE, WITH FAN_IN, la même clause TO SERVICE, et sont créées par le même identificateur de sécurité (SID). Lorsqu'une instruction ALTER TABLE est exécutée, les messages créés par ces trois notifications d'événements sont fusionnés en un message. Par conséquent, le service cible reçoit uniquement un message de l'événement.

event_type
Nom d'un type d'événement qui provoque l'exécution de la notification d'événement. event_type peut être un événement de type DDL Transact-SQL, Trace SQL ou Service Broker. Pour obtenir une liste des types d’événements DDL Transact-SQL éligibles, consultez Événements DDL. Les types d'événements Service Broker sont QUEUE_ACTIVATION et BROKER_QUEUE_DISABLED. Pour plus d'informations, voir Event Notifications.

event_group
Nom d'un groupe prédéfini de types d'événements Transact-SQL ou SQL Trace. Une notification d'événement peut se déclencher après l'exécution d'un événement qui appartient à un groupe d'événements. Pour obtenir une liste des groupes d’événements DDL, des événements Transact-SQL qu’ils couvrent et l’étendue à laquelle ils peuvent être définis, consultez Groupes d’événements DDL.

event_group agit également comme une macro, quand l’exécution de l’instruction CREATE EVENT NOTIFICATION se termine, en ajoutant les types d’événements qu’il couvre à la vue de catalogue sys.events.

'broker_service'
Spécifie le service cible qui reçoit les données de l'instance d'événement. SQL Server ouvre une ou plusieurs conversations avec le service cible de la notification d'événement. Ce service doit respecter le type de message d'événement et de contrat SQL Server utilisé pour envoyer le message.

Les conversations restent ouvertes jusqu'à ce que la notification d'événement soit supprimée. Certaines erreurs peuvent mettre fin aux conversations de manière anticipée. Le fait de mettre fin explicitement à certaines conversations ou à toutes les conversations peut empêcher le service cible de recevoir davantage de messages.

{ 'broker_instance_specifier' | 'current database' }
Spécifie une instance de Service Broker par rapport à laquelle broker_service est résolu. La valeur d’un Service Broker spécifique peut être obtenue en interrogeant la colonne service_broker_guid de la vue de catalogue sys.databases. Utilisez 'current database' pour définir l’instance de Service Broker dans la base de données actuelle. 'current database' est un littéral de chaîne qui tient compte de la casse.

Notes

Service Broker intègre un type de message et un contrat spécialement conçus pour les notifications d'événements. Par conséquent, il n'est pas nécessaire de créer un service d'initialisation Service Broker car il en existe déjà un qui spécifie le nom de contrat suivant :https://schemas.microsoft.com/SQL/Notifications/PostEventNotification

Le service cible qui reçoit les notifications d'événements doit respecter ce contrat préexistant.

Si une transaction d'événement qui active une notification est annulée, l'envoi de la notification d'événement est également annulé. Les notifications d'événements ne se déclenchent pas par une action définie dans un déclencheur lorsque la transaction est validée ou annulée à l'intérieur du déclencheur. Les événements de trace n'étant pas limités par les transactions, les notifications d'événements basées sur des événements de trace sont envoyées, que la transaction qui les active soit annulée ou non.

Si la conversation entre le serveur et le service cible est interrompue après le déclenchement d'une notification d'événement, une erreur est signalée et la notification d'événement est supprimée.

La transaction d'événement qui a démarré la notification n'est pas affectée par le succès ou l'échec de l'envoi de la notification d'événement.

Les échecs d'envoi de notification d'événement sont consignés.

Autorisations

Pour créer une notification d'événement dont l'étendue correspond à la base de données (ON DATABASE), vous devez disposer de l'autorisation CREATE DATABASE DDL EVENT NOTIFICATION sur la base de données.

Pour créer une notification d'événement sur une instruction DDL dont l'étendue correspond au serveur (ON SERVER), vous devez disposer de l'autorisation CREATE DDL EVENT NOTIFICATION sur le serveur.

Pour créer une notification d'événement sur un événement de trace, vous devez disposer de l'autorisation CREATE TRACE EVENT NOTIFICATION sur le serveur.

Pour créer une notification d'événement dont l'étendue correspond à une file d'attente, vous devez disposer de l'autorisation ALTER sur la file d'attente.

Exemples

R. Création d'une notification d'événement dont l'étendue correspond au serveur

L'exemple suivant crée les objets nécessaires pour configurer un service cible à l'aide de Service Broker. Le service cible fait référence au type de message et de contrat du service à l'origine de l'initialisation spécifique aux notifications d'événements La notification d'événement est ensuite créée sur le service cible qui envoie une notification chaque fois qu'un événement de trace Object_Created se produit sur l'instance de SQL Server.

--Create a queue to receive messages.  
CREATE QUEUE NotifyQueue ;  
GO  

--Create a service on the queue that references  
--the event notifications contract.  
CREATE SERVICE NotifyService  
ON QUEUE NotifyQueue  
([https://schemas.microsoft.com/SQL/Notifications/PostEventNotification]);  
GO  

--Create a route on the service to define the address   
--to which Service Broker sends messages for the service.  
CREATE ROUTE NotifyRoute  
WITH SERVICE_NAME = 'NotifyService',  
ADDRESS = 'LOCAL';  
GO 

--Create the event notification.  
CREATE EVENT NOTIFICATION log_ddl1   
ON SERVER   
FOR Object_Created   
TO SERVICE 'NotifyService',  
    '8140a771-3c4b-4479-8ac0-81008ab17984' ;  

B. Création d'une notification d'événement dont l'étendue correspond à une base de données

L'exemple suivant crée une notification d'événement sur le même service cible que l'exemple précédent. La notification d’événement se déclenche après l’occurrence d’un événement ALTER_TABLE dans l’exemple de base de données AdventureWorks2022.

CREATE EVENT NOTIFICATION Notify_ALTER_T1  
ON DATABASE  
FOR ALTER_TABLE  
TO SERVICE 'NotifyService',  
    '8140a771-3c4b-4479-8ac0-81008ab17984';  

C. Obtention d'informations sur une notification d'événement dont l'étendue correspond à un serveur

L'exemple suivant interroge l'affichage catalogue sys.server_event_notifications pour obtenir des métadonnées sur la notification d'événement log_ddl1 créée avec une étendue de serveur.

SELECT * FROM sys.server_event_notifications  
WHERE name = 'log_ddl1';  

D. Obtention d'informations sur une notification d'événement dont l'étendue correspond à une base de données

L'exemple suivant interroge l'affichage catalogue sys.event_notifications pour obtenir des métadonnées sur la notification d'événement Notify_ALTER_T1 créée avec une étendue de base de données.

SELECT * FROM sys.event_notifications  
WHERE name = 'Notify_ALTER_T1';  

Voir aussi

Notifications d'événements
DROP EVENT NOTIFICATION (Transact-SQL)
EVENTDATA (Transact-SQL)
sys.event_notifications (Transact-SQL)
sys.server_event_notifications (Transact-SQL)
sys.events (Transact-SQL)
sys.server_events (Transact-SQL)