Assinaturas de notificação, eventos de caixa de correio e EWS no ExchangeNotification subscriptions, mailbox events, and EWS in Exchange

Saiba mais sobre inscrições de notificação e evento de caixa de correio no EWS no Exchange.Find out about notification subscriptions and mailbox event in EWS in Exchange.

Você pode usar a API gerenciada do EWS e o EWS (serviços Web do Exchange) para inscrever-se para receber notificações quando os eventos ocorrerem em uma caixa de correio ou em uma ou mais pastas de uma caixa de correio.You can use both the EWS Managed API and Exchange Web Services (EWS) to subscribe to receive notifications when events occur in a mailbox, or in one or more of the folders in a mailbox. Há três tipos de assinatura disponíveis: notificações de streaming, notificações de recebimento e notificações por push.Three subscription types are available: streaming notifications, pull notifications, and push notifications. Cada um desses tipos de assinatura usa diferentes técnicas para receber ou recuperar as notificações.Each of these subscription types uses different techniques to receive or retrieve the notifications.

Obtendo notificações – quais são as minhas opções?Getting notifications - what are my options?

O EWS inclui três tipos de assinatura que funcionam de forma independente para notificar o cliente sobre as alterações no servidor.EWS includes three subscription types that work independently to notify the client of changes on the server. Independentemente do tipo de assinatura escolhido, você terá acesso a todos os mesmos eventos de notificação no final-é apenas uma questão de como obtê-los.No matter which subscription type you choose, you'll have access to all the same notification events in the end - it's just a matter of how you get them.

Tabela 1. Tipos de assinaturaTable 1. Subscription types

OpçãoOption DescriçãoDescription Está certo para mim?Is it right for me?
Notificações de streamingStreaming notifications
Notificações enviadas pelo servidor por meio de uma conexão que permanece aberta por um período de tempo especificado.Notifications that are sent by the server through a connection that remains open for a specified period of time.
As notificações de streaming geralmente são recomendadas para a maioria dos aplicativos.Streaming notifications are generally recommended for most applications. Eles são semelhantes às notificações pull e push e oferecem o melhor de ambos os mundos.They're similar to pull and push notifications, and offer the best of both worlds. Após estabelecer sua assinatura de notificação, a conexão permanecerá aberta por até 30 minutos para permitir que o servidor envie notificações de volta para o cliente.After you establish your notification subscription, the connection remains open for up to 30 minutes to allow the server to push notifications back to the client. Não é necessário solicitar atualizações, como faria com uma assinatura pull, e você não precisa criar um aplicativo de ouvinte de serviço Web como faria com uma assinatura push.No need to request updates, like you would with a pull subscription, and you don't have to create a web service listener application like you would with a push subscription.
Notificações de recepçãoPull notifications
Notificações que são solicitadas (ou puxadas) pelo cliente.Notifications that are requested (or pulled) by the client.
As notificações de recebimento são geralmente mais apropriadas para clientes com rigidez de acoplamento, onde o cliente não está conectado à rede com segurança.Pull notifications are generally most appropriate for loosely coupled clients, where the client is not reliably connected to the network. As notificações de recepção podem criar tráfego em excesso entre o cliente e o servidor porque o cliente está enviando solicitações frequentes ao servidor para recuperar notificações, e nem todas as solicitações resultam em notificações recuperadas.Pull notifications can create excess traffic between the client and the server because the client is sending frequent requests to the server to retrieve notifications, and not all requests result in notifications retrieved.
Notificações de PushPush notifications
Notificações enviadas (ou enviadas) pelo servidor para um serviço Web no lado do cliente por meio de um endereço de retorno de chamada.Notifications that are sent (or pushed) by the server to a client-side web service via a callback address.
Geralmente, as notificações por push fornecem latência de notificação menor do que as notificações de recebimento e são adequadas para clientes com acoplamento rígido para os quais o servidor tem acesso confiável e o cliente é endereçável por IP.Generally, push notifications provide for smaller notification latency than pull notifications and are suited for tightly coupled clients to which the server has reliable access and the client is IP addressable. No entanto, as notificações por push foram retiradas do favor desde o surgimento de notificações de streaming no Exchange 2010.However, push notifications have fallen out of favor since the advent of streaming notifications in Exchange 2010. Se possível, recomendamos que você use as notificações de streaming em vez de notificações por push no futuro.If possible, we recommend that you use streaming notifications instead of push notifications going forward. As notificações por push exigem que você crie um aplicativo de ouvinte, onde as notificações são enviadas.Push notifications require that you write a listener application, which is where the notifications are pushed to. Isso tem um ligeiro benefício sobre as notificações de recebimento, pois reduz o tráfego de conexão, mas adiciona sobrecarga solicitando um aplicativo separado.This has a slight benefit over pull notifications in that it reduces wire traffic, but it adds overhead by requiring a separate application.

Quais eventos do EWS posso me inscrever?What EWS events can I subscribe to?

Os tipos de eventos EWS nos quais os clientes se inscrevem são definidos pela enumeração EventType para a API gerenciada do EWS ou o elemento EventType do EWS.The types of EWS events that clients subscribe to are defined by the EventType enumeration for the EWS Managed API or the EventType element for EWS. Os eventos EWS a seguir estão disponíveis para assinatura:The following EWS events are available for subscription:

Outro tipo de evento do EWS, o evento status, é definido pelo elemento EventType , mas você não assina esse evento.Another EWS event type, the Status event, is defined by the EventType element, but you don't subscribe to this event. Em vez disso, ele é enviado pelo servidor para verificar o status do cliente somente para notificações por push e streaming.Instead, it's sent by the server to check the status of the client for streaming and push notifications only. O cliente precisa responder a essas necessidades de evento ou o cliente expirará.The client needs to respond to this event needs or the client will time out.

Uma ação única do usuário com frequência resulta na criação de várias notificações.A single user action often results in the creation of multiple notifications. Para ilustrar isso, a figura a seguir mostra alguns cenários comuns e as notificações criadas para cada um.To illustrate this, the following figure shows some common scenarios and the notifications created for each one. As configurações do cliente têm um impacto nas notificações recebidas, portanto, esta não é uma lista completa de todas as opções de configuração e notificações resultantes.Client settings have an impact on the notifications received, so this is not an exhaustive list of all the configuration options and resulting notifications.

Figura 1. Tipos de eventos retornados por assinaturas de notificaçãoFigure 1. Event types returned by notification subscriptions

A table that shows the notifications sent in common user scenarios, such as receiving new email, creating a new folder, moving a folder, and so on.

A Figura 1 simplifica o processo de notificação.Figure 1 simplifies the notification process. Na realidade, várias notificações (mesmo várias notificações do mesmo tipo) podem ser criadas para uma única ação do usuário.In reality, multiple notifications (even multiple notifications of the same type) can be created for a single user action. Por exemplo, no caso de uma operação de movimentação de pasta, três eventos de pasta são criados: um para a pasta que está sendo modificada, um para a pasta pai antiga e outro para a nova pasta pai.For example, in the case of a folder move operation, three folder events are created: one for the folder being modified, one for the old parent folder, and one for the new parent folder. Como numerosos eventos podem ser disparados para uma única operação, recomendamos que você crie um tempo de espera de alguns segundos em suas operações de sincronização, para que você só sincronize quando a ação for concluída, em vez de partway por meio da operação.Because numerous events can be fired for a single operation, we recommend that you build a wait time of a few seconds into your synchronization operations, so that you only synchronize when the action is complete, instead of partway through the operation.

Também é importante perceber que as definições de configuração que cada usuário escolhe irão afetar as notificações criadas.It's also important to realize that the configuration settings that each user chooses will affect which notifications are created. Por exemplo, os dados de disponibilidade de alguns usuários são atualizados automaticamente e o evento FreeBusyChanged é criado quando uma nova solicitação de reunião é recebida, mesmo antes de ler o item.For example, some users' free busy data is updated automatically and the FreeBusyChanged event is created when a new meeting request is received, even before they've read the item. Para outros usuários, os dados de disponibilidade não são atualizados e o evento FreeBusyChanged não é criado até que a reunião tenha sido aceita.For other users, free busy data isn't updated and the FreeBusyChanged event isn't created until after the meeting has been accepted. Essas configurações podem ter um impacto considerável sobre as notificações criadas pelo servidor.These settings can have a considerable impact on the notifications created by the server.

Como funcionam as notificações do EWS?How do EWS notifications work?

As notificações do EWS são tratadas de acordo com a assinatura.EWS notifications are handled on a subscription basis. Normalmente, há uma assinatura por caixa de correio e dentro da assinatura da caixa de correio você pode inscrever-se em algumas ou em todas as pastas.Typically there's one subscription per mailbox, and within the mailbox subscription you can subscribe to some or all folders. Você decide que tipo de notificação inscrever (transmitir, puxar ou enviar) e que tipo de eventos você gostaria de receber (NewMail, Created, Deleted, Modified etc.) e, em seguida, criar uma assinatura.You decide what kind of notification to subscribe to (streaming, pull, or push) and what kind of events you'd like to receive (NewMail, Created, Deleted, Modified, etc.), and then you create a subscription. Os eventos do EWS são enviados de forma assíncrona do servidor de caixa de correio para o cliente.The EWS events are then sent asynchronously from the mailbox server to the client. (Lição de histórico: os eventos são síncronos no Exchange 2007-e os eventos são armazenados no servidor de acesso para cliente no Exchange 2010, mas não mais!).(History lesson: events are synchronous in Exchange 2007 - and events are stored on the Client Access server in Exchange 2010, but no more!).

Dependendo do tipo de assinatura que você tem, as maneiras nas quais as notificações são enviadas para o cliente variam.Depending on the type of subscription you have, the ways in which the notifications are sent to the client vary. Esta seção descreve como cada tipo de assinatura funciona em mais detalhes.This section describes how each type of subscription works in more detail.

Notificações de streaming do EWSEWS streaming notifications

As notificações de streaming contam com uma solicitação de Get suspensa no servidor para manter uma conexão de assinatura de streaming aberta, para que qualquer evento que ocorra enquanto a conexão estiver ativa será transmitido para o cliente imediatamente.Streaming notifications rely on a hanging get request on the server to keep a streaming subscription connection open, so that any events that occur while the connection is active are streamed to the client immediately. Várias notificações podem ser enviadas durante uma única conexão, e a conexão permanece aberta até que o intervalo expire, ou por um máximo de 30 minutos.Multiple notifications can be sent over the course of a single connection, and the connection stays open until the interval expires, or for a maximum of 30 minutes. Depois que a conexão expirar, o cliente enviará a solicitação de obtenção suspensa novamente.After the connection expires, the client sends the hanging get request again. A Figura 2 mostra como as assinaturas de streaming e as notificações de streaming funcionam.Figure 2 shows how streaming subscriptions and streaming notifications work.

Figura 2. Visão geral da notificação de streamingFigure 2. Streaming notification overview

An illustration that shows how streaming notifications work. To set up streaming notifications: 1. Subscribe, 2. Open connection, 3. Wait for events, 4. Receive events, repeat 3 and 4, 5. Close or keep connection, 6. Unsubscribe or timeout.

Para obter informações sobre a criação de notificações de streaming, consulte Stream notifications about Mailbox Events by using EWS in Exchange.For information about creating streaming notifications, see Stream notifications about mailbox events by using EWS in Exchange.

Notificações pull do EWSEWS pull notifications

As notificações de recebimento dependem do cliente que solicita as notificações em um intervalo que o cliente gerencia.Pull notifications rely on the client asking for the notifications on an interval that the client manages. Isso pode resultar em respostas GetEvents sem notificações.This can result in GetEvents responses with no notifications. A Figura 3 mostra como funcionam as assinaturas pull e as notificações de recepção.Figure 3 shows how pull subscriptions and pull notifications work.

Figura 3. Visão geral da notificação pullFigure 3. Pull notification overview

An illustration that shows how pull notifications work. To set up pull notifications: 1. Subscribe, 2. Send GetEvents, 3. Receive response, repeat 2 and 3, 4. Close or keep connection, 5. Unsubscribe or timeout.

Para obter informações sobre como criar notificações pull, consulte pull notifications about Mailbox Events by using EWS in Exchange.For information about creating pull notifications, see Pull notifications about mailbox events by using EWS in Exchange.

Notificações por push do EWSEWS push notifications

As notificações por push dependem do servidor enviando notificações de volta para o cliente.Push notifications rely on the server pushing notifications back to the client. Há apenas tráfego se houver uma notificação.There's only traffic if there's a notification. A Figura 4 mostra como as assinaturas push e as notificações por push funcionam.Figure 4 shows how push subscriptions and push notifications work.

Figura 4. Visão geral da notificação por pushFigure 4. Push notification overview

An illustration that shows how push notifications work. To setup push notifications: 1. Create listener, 2. Subscribe, 3. Wait for events, 4. Receive events, 5. Send "OK" response, repeat 3, 4, and 5, 6. Unsubscribe or timeout.

Se você estiver usando notificações por push com o Exchange 2010, considere atualizar seu aplicativo para usar notificações de streaming, para que você não precise de um aplicativo separado para receber os eventos.If you are using push notifications with Exchange 2010, consider upgrading your application to use streaming notifications, so that you don't need a separate application to receive the events.

Como eu assino as notificações?How do I subscribe to notifications?

Dependendo do tipo de assinatura que você gostaria de criar, você tem várias opções para optar por assinar as notificações.Depending on the type of subscription you'd like to create, you have a number of options to choose from for subscribing to notifications.

Tabela 2. Operações e métodos para assinar notificaçõesTable 2. Operations and methods for subscribing to notifications

Tipo de assinaturaSubscription type Operação do EWSEWS operation Métodos da API gerenciada do EWSEWS Managed API methods FunçãoWhat it does
StreamingStreaming
Operação SubscribeSubscribe operation
Método ExchangeService. BeginSubscribeToStreamingNotificationsExchangeService.BeginSubscribeToStreamingNotifications method
Método ExchangeService. BeginSubscribeToStreamingNotificationsOnAllFoldersExchangeService.BeginSubscribeToStreamingNotificationsOnAllFolders method
Método ExchangeService. SubscribeToStreamingNotificationsOnAllFoldersExchangeService.SubscribeToStreamingNotificationsOnAllFolders method
Cria uma solicitação para assinar notificações de streaming.Creates a request to subscribe to streaming notifications.
ReceberPull
Operação SubscribeSubscribe operation
Método ExchangeService. BeginSubscribeToPullNotificationsExchangeService.BeginSubscribeToPullNotifications method
Método ExchangeService. BeginSubscribeToPullNotificationsOnAllFoldersExchangeService.BeginSubscribeToPullNotificationsOnAllFolders method
Método ExchangeService. SubscribeToPullNotificationsExchangeService.SubscribeToPullNotifications method
Método ExchangeService. SubscribeToPullNotificationsOnAllFoldersExchangeService.SubscribeToPullNotificationsOnAllFolders method
Cria uma solicitação para inscrever-se nas notificações de recepção.Creates a request to subscribe to pull notifications.
ColocaPush
Operação SubscribeSubscribe operation
Método sobrecarregado ExchangeService. BeginSubscribeToPushNotificationsExchangeService.BeginSubscribeToPushNotifications overloaded method
Método de sobrecarga ExchangeService. BeginSubscribeToPushNotificationsOnAllFoldersExchangeService.BeginSubscribeToPushNotificationsOnAllFolders overload method
Método sobrecarregado ExchangeService. SubscribeToPushNotificationsExchangeService.SubscribeToPushNotifications overloaded method
Método sobrecarregado ExchangeService. SubscribeToPushNotificationsOnAllFoldersExchangeService.SubscribeToPushNotificationsOnAllFolders overloaded method
Cria uma solicitação para inscrever-se nas notificações por push.Creates a request to subscribe to push notifications.

Como obtenho eventos do EWS?How do I get EWS events?

Após a criação da assinatura, a maneira como os eventos reais são enviados para o cliente depende do tipo de assinatura.After the subscription is created, the way in which the actual events are sent to the client depends on the subscription type.

Para notificações de streaming, uma conexão de assinatura de streaming deve ser criada e, em seguida, a assinatura é adicionada à conexão.For streaming notifications, a streaming subscription connection must be created, and then the subscription is added to the connection. Você pode ler mais sobre esse processo em notificações de fluxo sobre eventos de caixa de correio usando o EWS no Exchange.You can read more about this process in Stream notifications about mailbox events by using EWS in Exchange.

Para notificações de recebimento, o objeto Subscription foi inicializado quando a assinatura foi criada, de modo que você só precisa chamar o método GetEvent ou a operação para recuperar os eventos do servidor.For pull notifications, the subscription object was initialized when the subscription was created, so you just have to call the GetEvent method or operation to retrieve the events from the server. Você pode ler mais sobre isso em notificações pull sobre eventos de caixa de correio usando o EWS no Exchange.You can read more about this in Pull notifications about mailbox events by using EWS in Exchange.

A tabela a seguir lista as operações e as classes necessárias para recuperar eventos.The following table lists the operations and classes required to retrieve events.

Tabela 3. Elementos e classes para criar uma conexão e obter eventosTable 3. Elements and classes for creating a connection and getting events

Tipo de assinaturaSubscription type Operação do EWSEWS operation Método de API gerenciada do EWSEWS Managed API method FunçãoWhat it does
StreamingStreaming
Operação GetStreamingEventsGetStreamingEvents operation
Método StreamingSubscriptionConnection. AddSubscriptionStreamingSubscriptionConnection.AddSubscription method
Cria uma solicitação get suspensa no servidor, que é respondida quando ocorre um evento.Creates a hanging get request on the server, which is responded to when events occur.
ReceberPull
Operação GetEventsGetEvents operation
Método PullSubscription. GetEventsPullSubscription.GetEvents method
Obtém eventos de notificação pull do servidor.Gets pull notification events from the server.
ColocaPush
Não aplicável.Not applicable.
Não aplicável.Not applicable.
As notificações por push são enviadas automaticamente para o ouvinte do serviço Web (a URL de retorno de chamada especificada na solicitação de assinatura).Push notifications are automatically sent to the web service listener (the callback URL specified in the subscription request). Nenhum método ou operação adicional precisa ser chamado.No additional methods or operations need to be called.

Como cancelar a assinatura de notificações?How do I unsubscribe to notifications?

A tabela a seguir lista as maneiras nas quais você pode cancelar a assinatura de cada tipo de assinatura.The following table lists the ways in which you can unsubscribe to each type of subscription.

Tabela 4. Operações e métodos para inscrever-se em notificaçõesTable 4. Operations and methods for unsubscribing to notifications

Tipo de assinaturaSubscription type EWSEWS API gerenciada do EWSEWS Managed API
StreamingStreaming
Cancelar a operaçãoUnsubscribe operation
Método StreamingSubscription. BeginUnsubscribeStreamingSubscription.BeginUnsubscribe method
Método StreamingSubscription. EndUnsubscribeStreamingSubscription.EndUnsubscribe method
Método StreamingSubscription. unsubscribeStreamingSubscription.Unsubscribe method
ReceberPull
Cancelar a operaçãoUnsubscribe operation
Método PullSubscription. BeginUnsubscribePullSubscription.BeginUnsubscribe method
Método PullSubscription. EndUnsubscribePullSubscription.EndUnsubscribe method
Método PullSubscription. unsubscribePullSubscription.Unsubscribe method
ColocaPush
Retornar unsubscribe no elemento StatusFrequency do SendNotificationResponseMessageReturn Unsubscribe in the StatusFrequency element of the SendNotificationResponseMessage
Não aplicável.Not applicable. Em vez disso, deixe o tempo limite da assinatura.Let the subscription time out instead.

Como alternativa, você pode deixar o tempo limite de cada assinatura.Alternatively, you can let each of the subscriptions time out.

Tabela 5. Tempo limite de assinaturaTable 5. Subscription time-outs

Tipo de assinaturaSubscription type Valor de tempo limite no EWSTimeout value in EWS Valor de tempo limite na API gerenciada do EWSTimeout value in the EWS Managed API Tratamento de tempo limiteTimeout handling
StreamingStreaming
Elemento connectionTimeoutConnectionTimeout element
parâmetro Lifetime do construtor StreamingSubscriptionConnectionlifetime parameter of the StreamingSubscriptionConnection constructor
Para a API gerenciada do EWS, após o valor de tempo limite ser decorrido, o evento OnDisconnect é gerado.For the EWS Managed API, after the timeout value elapses, the OnDisconnect event is raised. Se o método StreamingSubscriptionConnection. Open não for chamado, a conexão será fechada.If the StreamingSubscriptionConnection.Open method is not called, the connection is closed.
Para o EWS, após o valor de tempo limite ser decorrido, a mensagem GetUserConfigurationResponse retorna um valor de ConnectionStatus de Closed.For EWS, after the timeout value elapses, the GetUserConfigurationResponse message returns a ConnectionStatus value of Closed.
ReceberPull
Elemento TimeoutTimeout element
parâmetro Timeout do método SubscribeToPullNotificationtimeout parameter of the SubscribeToPullNotification method
Depois que o valor de tempo limite expirar, o servidor excluirá a assinatura.After the timeout value elapses, the server deletes the subscription.
ColocaPush
Elemento StatusFrequencyStatusFrequency element
parâmetro Frequency do método SubscribeToPushNotificationfrequency parameter of the SubscribeToPushNotification method
Se o servidor não receber uma resposta a uma notificação por Push ou o ping de status, ele tentará enviar a notificação várias vezes antes de parar de enviar as notificações.If the server does not receive a response to a push notification or status ping, it retries sending the notification several times before it stops sending the notifications. Para obter mais informações, consulte StatusFrequency.For more information, see StatusFrequency.

Posso limitar as assinaturas?Can I limit subscriptions?

Em uma implantação local, você pode limitar o número de assinaturas por usuário com o parâmetro EwsMaxSubscriptions throttling da política de limitação.In an on-premises deployment, you can limit the number of subscriptions per user with the EwsMaxSubscriptions throttling parameter of the throttling policy. Essa política pode ser aplicada a todos os usuários ou apenas a usuários específicos.That policy can be applied to all users or just specific users. A política de limitação do EwsMaxSubscriptions não é configurável para o Exchange Online.The EwsMaxSubscriptions throttling policy is not configurable for Exchange Online.

Nesta seçãoIn this section

Confira tambémSee also