CREATE EVENT NOTIFICATION (Transact-SQL)

Aplica-se a: SQL Server Instância Gerenciada de SQL do Azure

Cria um objeto que envia informações sobre um banco de dados ou evento de servidor para um serviço do Service Broker. As notificações de evento são criadas somente com instruções Transact-SQL.

Convenções de sintaxe de Transact-SQL

Sintaxe

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' }  
[ ; ]  

Argumentos

event_notification_name
É o nome da notificação de eventos. O nome de uma notificação de eventos deve estar em conformidade com as regras para identificadores e deve ser exclusivo no escopo em que é criado: SERVER, DATABASE ou object_name.

SERVER
Aplica o escopo da notificação de eventos à instância atual do SQL Server. Se for especificada, a notificação será acionada sempre que o evento especificado na cláusula FOR ocorrer em qualquer lugar na instância do SQL Server.

DATABASE
Aplica o escopo da notificação de eventos ao banco de dados atual. Se for especificada, a notificação será acionada sempre que o evento especificado na cláusula FOR ocorrer no banco de dados atual.

QUEUE
Aplica o escopo da notificação em uma fila específica no banco de dados atual. QUEUE pode ser especificado somente se FOR QUEUE_ACTIVATION ou FOR BROKER_QUEUE_DISABLED também for especificado.

queue_name
É o nome da fila para a qual a notificação de eventos se aplica. queue_name poderá ser especificado apenas se QUEUE for especificado.

WITH FAN_IN
Instrui o SQL Server a enviar somente uma mensagem por evento para qualquer serviço especificado para todas as notificações de eventos que:

• São criadas no mesmo evento.

• São criadas pelo mesmo principal (conforme identificado pelo mesmo SID).

• Especifique o mesmo serviço e broker_instance_specifier.

• Especificam WITH FAN_IN.

Por exemplo, três notificações de eventos são criadas. Todas as notificações de eventos especificam FOR ALTER_TABLE, WITH FAN_IN, a mesma cláusula TO SERVICE e são criadas pelo mesmo SID. Quando uma instrução ALTER TABLE é executada, as mensagens criadas por essas três notificações de eventos são mescladas em uma. Portanto, o serviço de destino recebe só uma mensagem do evento.

event_type
É o nome de um tipo de evento que faz com que a notificação de eventos seja executada. event_type pode ser um tipo de evento DDL Transact-SQL, um tipo de evento de Rastreamento do SQL ou um tipo de evento Service Broker. Para obter uma lista dos tipos de evento DDL Transact-SQL qualificados, confira DDL Events. Os tipos de evento Service Broker são QUEUE_ACTIVATION e BROKER_QUEUE_DISABLED. Para obter mais informações, consulte Event Notifications.

event_group
É o nome de um grupo predefinido de tipos de evento Transact-SQL ou de Rastreamento do SQL. Uma notificação de eventos pode ser acionada depois da execução de qualquer evento que pertence a um grupo de eventos. Para obter uma lista dos grupos de eventos DDL, os eventos Transact-SQL abrangidos por eles e o escopo em que podem ser definidos, confira DDL Event Groups.

event_group também age como uma macro, quando a instrução CREATE EVENT NOTIFICATION termina, com a adição dos tipos de evento abrangidos à exibição do catálogo sys.events.

' broker_service '
Especifica o serviço de destino que recebe os dados da instância de eventos. O SQL Server abre uma ou mais conversas com o serviço de destino para a notificação de eventos. Esse serviço deve respeitar o mesmo tipo de mensagem de eventos do SQL Server e o contrato usados para enviar a mensagem.

As conversas permanecem abertas até que a notificação de eventos seja descartada. Alguns erros podem fazer as conversas fecharem antes. O encerramento explícito de algumas ou todas as conversas pode impedir que o serviço de destino receba mais mensagens.

{ 'broker_instance_specifier' | 'current database' }
Especifica uma instância do Service Broker na qual broker_service é resolvido. O valor para um agente de serviços específico pode ser adquirido ao consultar a coluna service_broker_guid da exibição do catálogo sys.databases. Use 'current database' para especificar a instância do Service Broker no banco de dados atual. 'current database' é um literal de cadeia de caracteres que não diferencia maiúsculas de minúsculas.

Comentários

O Service Broker inclui um tipo de mensagem e contrato específicos para notificações de eventos. Portanto, um serviço de inicialização do Service Broker não precisa ser criado porque já existe um serviço que especifica o seguinte nome de contrato: https://schemas.microsoft.com/SQL/Notifications/PostEventNotification

O serviço de destino que recebe as notificações de eventos deve honrar esse contrato preexistente.

Se uma transação de eventos que ativa uma notificação for revertida, o envio da notificação de eventos também será revertido. As notificações de eventos não são acionadas por uma ação definida em um gatilho quando a transação é confirmada ou revertida no gatilho. Como os eventos de rastreamento não são associados por transações, as notificações de eventos baseadas nos eventos de rastreamentos são enviadas independentemente de a transação que as acionou estar revertida.

Se a conversa entre o servidor e o serviço de destino for quebrada após o acionamento de uma notificação de eventos, um erro será relatado e a notificação de eventos será descartada.

A transação de eventos que iniciou originalmente a notificação não é afetada pelo êxito ou pela falha do envio da notificação de eventos.

Qualquer falha de envio de uma notificação de eventos é registrada.

Permissões

Para criar uma notificação de eventos com escopo no banco de dados (ON DATABASE), requer a permissão CREATE DATABASE DDL EVENT NOTIFICATION no banco de dados atual.

Para criar uma notificação de eventos em uma instrução DDL com escopo no servidor (ON SERVER), requer a permissão CREATE DDL EVENT NOTIFICATION no servidor.

Para criar uma notificação de eventos em um evento de rastreamento, requer a permissão CREATE TRACE EVENT NOTIFICATION no servidor.

Para criar uma notificação de eventos com escopo em uma fila, requer a permissão ALTER na fila.

Exemplos

a. Criando uma notificação de eventos no escopo do servidor

O exemplo a seguir cria os objetos obrigatórios para configurar um serviço de destino usando o Service Broker. O serviço de destino faz referência ao tipo de mensagem e ao contrato do serviço de inicialização específico para notificações de eventos. Uma notificação de evento é criada nesse serviço de destino, que envia uma notificação sempre que um Object_Createdevento de rastreamento acontece na instância do 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. Criando uma notificação de eventos no escopo do banco de dados

O exemplo a seguir cria uma notificação de eventos no mesmo serviço de destino do exemplo anterior. A notificação de eventos é acionada depois que o evento ALTER_TABLE ocorre no banco de dados de exemplo AdventureWorks2022.

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

C. Obtendo informações sobre uma notificação de eventos no escopo do servidor

O exemplo a seguir consulta a exibição do catálogo sys.server_event_notifications para obter os metadados sobre a notificação de eventos log_ddl1 que foi criada no escopo de servidor.

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

D. Obtendo informações sobre uma notificação de eventos no escopo do banco de dados

O exemplo a seguir consulta a exibição do catálogo sys.event_notifications para obter os metadados sobre a notificação de eventos Notify_ALTER_T1 que foi criada no escopo de banco de dados.

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

Consulte Também

Notificações de eventos
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)