Trabalhando com notificações de consulta
Aplica-se a: 
SQL Server Instância Gerenciada de SQL do Azure
Importante
O SQL Server Native Client (SNAC) não é fornecido com:
- SQL Server 2022 (16.x) e versões posteriores
- SQL Server Management Studio 19 e versões posteriores
O SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o provedor OLE DB para SQL Server (SQLOLEDB) da Microsoft herdado não são recomendados para desenvolver um novo aplicativo.
Para novos projetos, use um dos seguintes drivers:
Para SQLNCLI que é fornecido como um componente do Mecanismo de Banco de Dados do SQL Server (versões 2012 a 2019), confira esta exceção de Ciclo de Vida de Suporte.
As notificações de consulta foram introduzidas no SQL Server 2005 (9.x) e no SQL Server Native Client. Criadas com base na infra-estrutura do Service Broker introduzida no SQL Server 2005 (9.x), as notificações de consulta permitem que os aplicativos sejam notificados quando os dados forem alterados. Esse recurso é particularmente útil para aplicativos que fornecem um cache de informações de um banco de dados, como um aplicativo da Web, e precisam ser notificados quando os dados de origem são alterados.
As notificações de consulta permitem que você solicite uma notificação em um tempo limite especificado quando os dados subjacentes de uma consulta são alterados. A solicitação por notificação especifica as opções de notificação, que incluem o nome do serviço, o texto da mensagem e o valor do tempo limite do servidor. As notificações são entregues através de uma fila do Service Broker na qual os aplicativos podem sondar as notificações disponíveis.
A sintaxe da cadeia de caracteres das opções de notificação de consulta é:
service=<service-name>[;(local database=<database> | broker instance=<broker instance>)]
Por exemplo:
service=mySSBService;local database=mydb
As assinaturas de notificação duram mais tempo do que o processo que as inicia, já que um aplicativo pode criar uma assinatura de notificação e, em seguida, ser encerrado. A assinatura permanece válida e a notificação será feita se os dados forem alterados no tempo limite especificado na criação da assinatura. Uma notificação é identificada pela consulta executada, pelas opções de notificação e pelo texto da mensagem, podendo ser cancelada definindo-se o valor de seu tempo limite como zero.
As notificações só são enviadas uma vez. Para que as notificações de alteração de dados sejam contínuas, é preciso criar uma nova assinatura e executar novamente a consulta depois que cada notificação foi processada.
Os aplicativos SQL Server Native Client normalmente recebem notificações usando o comando Transact-SQL RECEIVE para ler notificações da fila associada ao serviço especificado nas opções de notificação.
Observação
Os nomes de tabela devem ser qualificados nas consultas para as quais a notificação é requerida, por exemplo, dbo.myTable. Os nomes de tabela devem ser qualificados com nomes de duas partes. A assinatura é considerada inválida se nomes com três ou quatro partes são usados.
A infraestrutura de notificação baseia-se em um recurso de fila introduzido no SQL Server 2005 (9.x). Em geral, as notificações geradas no servidor são enviadas através dessas filas para serem processadas posteriormente.
Para usar notificações de consulta, uma fila e um serviço devem existir no servidor. Eles podem ser criados usando o Transact-SQL semelhante ao seguinte:
CREATE QUEUE myQueue
CREATE SERVICE myService ON QUEUE myQueue
([http://schemas.microsoft.com/SQL/Notifications/PostQueryNotification])
Observação
O serviço deve usar o contrato predefinido http://schemas.microsoft.com/SQL/Notifications/PostQueryNotification como mostrado acima.
Provedor OLE DB do SQL Server Native Client
O provedor OLE DB do SQL Server Native Client dá suporte à notificação do consumidor na modificação do conjunto de linhas. O consumidor recebe uma notificação em cada fase da modificação do conjunto de linhas e em qualquer tentativa de alteração.
Observação
Passar uma consulta de notificações para o servidor com ICommand::Execute é a única maneira válida de assinar notificações de consulta com o provedor OLE DB do SQL Server Native Client.
O conjunto de propriedades DBPROPSET_SQLSERVERROWSET
Para dar suporte a notificações de consulta por meio do OLE DB, o SQL Server Native Client adiciona as novas propriedades a seguir ao conjunto de propriedades DBPROPSET_SQLSERVERROWSET.
| Nome | Tipo | DESCRIÇÃO |
|---|---|---|
| SSPROP_QP_NOTIFICATION_TIMEOUT | VT_UI4 | O número de segundos que a notificação de consulta permanece ativa. O padrão é 432000 segundos (5 dias). O valor mínimo é 1 segundo e o valor máximo é 2^31-1 segundos. |
| SSPROP_QP_NOTIFICATION_MSGTEXT | VT_BSTR | O texto da mensagem da notificação. É definido pelo usuário e não tem um formato predefinido. Por padrão, a cadeia de caracteres fica vazia. Você pode especificar uma mensagem que contenha entre 1-2000 caracteres. |
| SSPROP_QP_NOTIFICATION_OPTIONS | VT_BSTR | As opções de notificação de consulta. Elas são especificadas em uma cadeia de caracteres com a sintaxe name=value. O usuário é responsável por criar o serviço e ler as notificações da fila. O padrão é uma cadeia de caracteres vazia. |
A assinatura de notificação é sempre confirmada, independentemente do fato de a instrução ter sido executada em uma transação de usuário ou em uma confirmação automática ou se a transação na qual a instrução foi executada tiver sido confirmada ou revertida. A notificação do servidor é acionada mediante uma das seguintes condições inválidas de notificação: alteração dos dados subjacentes ou do esquema ou quando o tempo limite expira; a que ocorrer primeiro. Os registros de notificação são excluídos assim que são disparados. Consequentemente, em caso de recebimento de notificações, o aplicativo deve realizar uma nova assinatura caso queira obter mais atualizações.
Outra conexão ou thread pode verificar se há notificações na fila de destino. Por exemplo:
WAITFOR (RECEIVE * FROM MyQueue); // Where MyQueue is the queue name.
Observe que SELECT * não exclui a entrada da fila, no entanto, RECEIVE * FROM sim. Isso irá interromper um thread de servidor se a fila estiver vazia. Se houver entradas na fila durante o momento da chamada, elas serão retornadas imediatamente; caso contrário, a chamada aguardará até que seja feita a entrada na fila.
RECEIVE * FROM MyQueue
Essa instrução retornará imediatamente um conjunto de resultados vazio se a fila estiver vazia; caso contrário, retornará todas as notificações da fila.
Se SSPROP_QP_NOTIFICATION_MSGTEXT e SSPROP_QP_NOTIFICATION_OPTIONS forem não nulos e não vazios, o cabeçalho do TDS para notificações de consulta que contém as três propriedades definidas acima é enviado ao servidor em cada execução do comando. Se algum deles for nulo (ou vazio), o cabeçalho não será enviado e DB_E_ERRORSOCCURRED será usado, (ou DB_S_ERRORSOCCURRED se as propriedades estiverem marcadas como opcionais), e o valor do status será definido como DBPROPSTATUS_BADVALUE. A validação é feita em Execute/Prepare. Da mesma forma, DB_S_ERRORSOCCURED é gerado quando as propriedades de notificação de consulta são definidas para conexões com versões do SQL Server anteriores ao SQL Server 2005 (9.x). O valor de status nesse caso é DBPROPSTATUS_NOTSUPPORTED.
Iniciar uma assinatura não garante que as mensagens subsequentes sejam entregues com êxito. Além disso, nenhuma verificação é feita em relação à validade do nome de serviço especificado.
Observação
A preparação de assinaturas nunca fará com que a assinatura seja iniciada; somente a execução da instrução iniciará a assinatura e as notificações de consulta não são impactadas pelo uso dos serviços principais do OLE DB.
Para obter mais informações sobre o conjunto de propriedades DBPROPSET_SQLSERVERROWSET, consulte Propriedades e comportamentos do conjunto de linhas.
Driver ODBC do SQL Server Native Client
O driver ODBC do SQL Server Native Client dá suporte a notificações de consulta por meio da adição de três novos atributos às funções SQLGetStmtAttr e SQLSetStmtAttr :
SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT
SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS
SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT
Se SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT e SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS não forem NULOS, o cabeçalho do TDS das notificações de consulta que contém os três atributos definidos acima será enviado para o servidor toda vez que o comando for executado. Se um deles for nulo, o cabeçalho não será enviado e SQL_SUCCESS_WITH_INFO será retornado. A validação ocorre em SQLPrepare Function, SqlExecDirect e SqlExecute, todos os quais falham se os atributos não forem válidos. Da mesma forma, quando esses atributos de notificação de consulta são definidos para versões do SQL Server anteriores ao SQL Server 2005 (9.x), a execução falha com SQL_SUCCESS_WITH_INFO.
Observação
A preparação de instruções nunca iniciará a assinatura; a assinatura pode ser iniciada com a execução da instrução.
Casos especiais e restrições
Os seguintes tipos de dados não são suportados para notificações:
text
ntext
imagem
Se for feita uma solicitação de notificação para um consulta que retorna um desses tipos, a notificação será disparada imediatamente, especificando que não foi possível realizar a assinatura na notificação.
Se uma solicitação de assinatura for feita para um lote ou procedimento armazenado, outra solicitação de assinatura será feita para cada instrução executada no lote ou procedimento armazenado. As instruções EXECUTE não registrarão notificações, mas enviarão a solicitação de notificação para o comando executado. Se for um lote, o contexto será aplicado às instruções executadas e as mesmas regras descritas anteriormente serão aplicadas.
O envio de uma consulta para notificação que foi enviada pelo mesmo usuário no mesmo contexto de banco de dados e tem o mesmo modelo, os mesmos valores de parâmetro, a mesma ID de notificação e o mesmo local de entrega de uma assinatura ativa existente, renovará a assinatura existente, redefinindo o novo tempo limite especificado. Isso significa que, se a notificação for solicitada para consultas idênticas, apenas uma notificação será enviada. Isso se aplica a uma consulta duplicada em um lote ou a uma consulta em um procedimento armazenado chamada várias vezes.