Подписки на уведомления, события почтовых ящиков и службы EWS в ExchangeNotification subscriptions, mailbox events, and EWS in Exchange

Сведения о подписках на уведомления и событии почтовых ящиков в EWS в Exchange.Find out about notification subscriptions and mailbox event in EWS in Exchange.

Чтобы подписаться на уведомления о событиях, возникающих в почтовом ящике или в одной или нескольких папках почтового ящика, можно использовать управляемый API EWS или веб-службы Exchange (EWS). Доступно три типа подписки: на потоковые уведомления, на уведомления по запросу и на push-уведомления. Каждый тип подписки использует собственные методы для получения уведомлений.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. Three subscription types are available: streaming notifications, pull notifications, and push notifications. Each of these subscription types uses different techniques to receive or retrieve the notifications.

Какие уведомления выбрать?Getting notifications - what are my options?

Службы EWS предлагают три типа подписки, которые независимо друг от друга уведомляют клиента об изменениях на сервере. Не имеет значения, какую именно подписку вы выберете, вы получите те же самые события уведомлений, отличаться будет только способ получения.EWS includes three subscription types that work independently to notify the client of changes on the server. 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.

Таблица 1. Типы подпискиTable 1. Subscription types

ВариантOption ОписаниеDescription Насколько мне это подходит?Is it right for me?
Потоковые уведомленияStreaming notifications
Уведомления, которые сервер отправляет через соединение, открытое в течение определенного периода времени.Notifications that are sent by the server through a connection that remains open for a specified period of time.
Потоковые уведомления рекомендуются для большинства приложений. Они похожи на уведомления по запросу и push-уведомления и объединяют в себе свойства обоих указанных типов. После создания подписки на уведомления соединение остается открытым до 30 минут, чтобы сервер успел передать уведомления клиенту. В данном случае не требуется запрашивать обновления, как при подписке на уведомления по запросу. Кроме того, не требуется создавать приложение прослушивателя для веб-службы, которое необходимо для получения push-уведомлений.Streaming notifications are generally recommended for most applications. They're similar to pull and push notifications, and offer the best of both worlds. 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. 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.
Уведомления по запросуPull notifications
Уведомления, запрашиваемые или извлекаемые клиентом.Notifications that are requested (or pulled) by the client.
Уведомления по запросу больше подходят для слабо связанных клиентов, где клиент ненадежно подключен к сети. Эти уведомления могут создавать дополнительный трафик между клиентом и сервером, так как клиент отправляет частые запросы к серверу для получения уведомлений, не все из которых приносят результат.Pull notifications are generally most appropriate for loosely coupled clients, where the client is not reliably connected to the network. 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.
Push-уведомленияPush notifications
Уведомления, отправляемые (или принудительно отправляемые) сервером в веб-службу на стороне клиента через адрес обратного вызова.Notifications that are sent (or pushed) by the server to a client-side web service via a callback address.
Как правило, push-уведомления приходят быстрее, чем уведомления по запросу. Кроме того, они подходят для сильно связанных клиентов с IP-адресом, к которым у сервера есть надежный доступ. Тем не менее push-уведомления стали реже использовать после появления потоковых уведомлений в Exchange 2010. Мы также рекомендуем использовать потоковые уведомления вместо push-уведомлений, если это возможно. Кроме того, для использования push-уведомлений требуется написать приложение прослушивателя, в котором и происходит принудительная отправка уведомлений. Уменьшение сетевого трафика — это основное, хоть и незначительное, преимущество данного типа уведомлений по сравнению с уведомлениями по запросу, которое, тем не менее, сводится на нет необходимостью создания отдельного приложения.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. However, push notifications have fallen out of favor since the advent of streaming notifications in Exchange 2010. If possible, we recommend that you use streaming notifications instead of push notifications going forward. Push notifications require that you write a listener application, which is where the notifications are pushed to. This has a slight benefit over pull notifications in that it reduces wire traffic, but it adds overhead by requiring a separate application.

На какие события служб EWS можно подписаться?What EWS events can I subscribe to?

Типы событий служб EWS, на которые возможна подписка, определены в статьях "Перечисление EventType" для управляемого API EWS или "Элемент EventType" для служб EWS. Подписка доступна для следующих событий службы 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. The following EWS events are available for subscription:

Еще один тип событий служб EWS, событие Status, определяется элементом EventType. На это событие не надо подписываться. Оно отправляется сервером для проверки состояния клиента (только для потоковых и push-уведомлений). Клиент должен ответить на это событие или он будет отключен по истечении времени ожидания.Another EWS event type, the Status event, is defined by the EventType element, but you don't subscribe to this event. Instead, it's sent by the server to check the status of the client for streaming and push notifications only. The client needs to respond to this event or the client will time out.

Одно действие пользователя может привести к созданию нескольких уведомлений. На рисунке ниже приводится ряд распространенных сценариев и уведомлений, созданных для каждого из них. На получение уведомлений влияют настройки клиента, поэтому приведенный список может быть дополнен другими вариантами конфигураций и соответствующими уведомлениями.A single user action often results in the creation of multiple notifications. To illustrate this, the following figure shows some common scenarios and the notifications created for each one. Client settings have an impact on the notifications received, so this is not an exhaustive list of all the configuration options and resulting notifications.

Рисунок 1. Типы событий, возвращаемые подписками на уведомленияFigure 1. Event types returned by notification subscriptions

Таблица, в которой показаны уведомления, отправляемые пользователям в распространенных ситуациях, например при получении нового сообщения, создании новой папки, перемещении папок и т. д.

На рисунке 1 показан упрощенный процесс создания уведомления. На самом деле, для одного действия пользователя может быть создано несколько уведомлений (даже если они относятся к одному типу). Например, при переносе папки создается три события папки: одно для изменения папки, одно для бывшей родительской папки и еще одно для новой родительской папки. Так как для одной операции может быть создано несколько событий, мы рекомендуем при создании операции синхронизации задать время ожидания в несколько секунд, чтобы синхронизация происходила только после завершения операции.Figure 1 simplifies the notification process. In reality, multiple notifications (even multiple notifications of the same type) can be created for a single user action. 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. 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.

Кроме того, следует принимать во внимание, что параметры конфигурации, задаваемые конкретным пользователем, также влияют на создание уведомлений. Например, сведения о доступности некоторых пользователей обновляются автоматически, поэтому событие FreeBusyChanged создается в момент получения приглашения на собрание, которое пользователь часто еще не успел прочесть. Если же пользователи, не настраивали обновление сведений о доступности, событие FreeBusyChanged создается, только когда приглашение на собрание будет принято. Эти параметры могут оказывать значительное влияние на уведомления, создаваемые сервером.It's also important to realize that the configuration settings that each user chooses will affect which notifications are created. 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. For other users, free busy data isn't updated and the FreeBusyChanged event isn't created until after the meeting has been accepted. These settings can have a considerable impact on the notifications created by the server.

Принципы работы уведомлений служб EWSHow do EWS notifications work?

Уведомления служб EWS обрабатываются на основании подписки. Обычно для одного почтового ящика создается одна подписка, которая позволяет подписаться на все папки или на некоторые из них. Решите на какие уведомления подписываться (потоковые уведомления, уведомления по запросу или push-уведомления), сведения о каких событиях получать (NewMail, Created, Deleted, Modified и т. д.), а затем создайте подписку. После этого сервер почтового ящика будет асинхронно отправлять клиенту события службы EWS. (Для справки: события синхронны в Exchange 2007, а в Exchange 2010 они хранятся на сервере клиентского доступа, но это не относится к более поздним версиям.)EWS notifications are handled on a subscription basis. Typically there's one subscription per mailbox, and within the mailbox subscription you can subscribe to some or all folders. 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. The EWS events are then sent asynchronously from the mailbox server to the client. (History lesson: events are synchronous in Exchange 2007 - and events are stored on the Client Access server in Exchange 2010, but no more!).

Способы отправки уведомлений клиенту отличаются в зависимости от выбранного типа подписки. В этом разделе содержатся дополнительные сведения о принципах работы каждого из них.Depending on the type of subscription you have, the ways in which the notifications are sent to the client vary. This section describes how each type of subscription works in more detail.

Потоковые уведомления служб EWSEWS streaming notifications

Потоковые уведомления используют ожидающий запрос GET для сервера, чтобы соединение для подписки с потоковой передачей оставалось открытым. Таким образом, выполняется немедленная потоковая передача клиенту всех событий, происходящих, пока соединение активно. Во время одного подключения может быть отправлено несколько уведомлений. Соединение остается открытым в течение определенного времени, но не более 30 минут. После чего клиент снова отправляет ожидающий запрос GET. На рисунке 2 показан принцип работы подписок с потоковой передачей и потоковых уведомлений.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. 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. After the connection expires, the client sends the hanging get request again. Figure 2 shows how streaming subscriptions and streaming notifications work.

Рисунок 2. Обзор потоковых уведомленийFigure 2. Streaming notification overview

Иллюстрация, показывающая принцип работы потоковых уведомлений. Чтобы настроить потоковые уведомления, сделайте следующее. 1. Оформите подписку. 2. Откройте соединение. 3. Дождитесь событий 4. Получите события, повторяйте шаги 3 и 4. 5. Закройте или оставьте соединение. 6. Отмените подписку или дождитесь, когда истечет срок ее действия.

Дополнительные сведения по созданию потоковых уведомлений см. в статье Потоковая передача уведомлений о событиях почтовых ящиков с помощью EWS в Exchange.For information about creating streaming notifications, see Stream notifications about mailbox events by using EWS in Exchange.

Уведомления по запросу служб EWSEWS pull notifications

Для получения уведомлений по запросу клиент запрашивает их через определенный, регулируемый им интервал. В результате могут приходить ответы GetEvents без уведомлений. На рисунке 3 показан принцип работы подписок и уведомлений по запросу.Pull notifications rely on the client asking for the notifications on an interval that the client manages. This can result in GetEvents responses with no notifications. Figure 3 shows how pull subscriptions and pull notifications work.

Рисунок 3. Обзор уведомлений по запросуFigure 3. Pull notification overview

Иллюстрация, показывающая принцип работы pull-уведомлений. Чтобы настроить pull-уведомления, сделайте следующее. 1. Оформите подписку. 2. Отправьте события GetEvent. 3. Получив ответ, повторяйте пункты 2 и 3. 4. Закройте и оставьте соединение. 5. Отмените подписку или дождитесь, когда истечет срок ее действия.

Дополнительные сведения по созданию уведомлений по запросу см. в статье Уведомления по запросу о событиях почтовых ящиков с помощью веб-служб Exchange в Exchange.For information about creating pull notifications, see Pull notifications about mailbox events by using EWS in Exchange.

Push-уведомления служб EWSEWS push notifications

Сервер принудительно отправляет push-уведомления обратно клиенту, поэтому трафик используется только при передаче уведомления. На рисунке 4 показан принцип работы принудительных подписок и push-уведомлений.Push notifications rely on the server pushing notifications back to the client. There's only traffic if there's a notification. Figure 4 shows how push subscriptions and push notifications work.

Рисунок 4. Обзор push-уведомленийFigure 4. Push notification overview

Иллюстрация, показывающая принцип работы push-уведомлений. Чтобы настроить push-уведомления, сделайте следующее. 1. Создайте слушателя, 2. Оформите подписку. 3. Дождитесь событий. 4. Получите события. 5. Отправьте ответ "ОК", повторите шаги 3, 4 и 5. 6. Отмените подписку или дождитесь, когда истечет срок ее действия.

Если вы используете push-уведомления в Exchange 2010, рекомендуем перейти к использованию потоковых уведомлений в приложении, в этом случае вам не понадобится отдельное приложение для получения событий.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.

Как подписаться на уведомления?How do I subscribe to notifications?

Существует несколько вариантов подписки на уведомления в зависимости от типа подписки, который нужно создать.Depending on the type of subscription you'd like to create, you have a number of options to choose from for subscribing to notifications.

Таблица 2. Методы подписки на уведомления и необходимые операцииTable 2. Operations and methods for subscribing to notifications

Тип подпискиSubscription type Операция служб EWSEWS operation Методы управляемого API EWSEWS Managed API methods ДействиеWhat it does
Подписка с потоковой передачейStreaming
Операции подпискиSubscribe operation
Метод ExchangeService.BeginSubscribeToStreamingNotificationsExchangeService.BeginSubscribeToStreamingNotifications method
Метод ExchangeService.BeginSubscribeToStreamingNotificationsOnAllFoldersExchangeService.BeginSubscribeToStreamingNotificationsOnAllFolders method
Метод ExchangeService.SubscribeToStreamingNotificationsOnAllFoldersExchangeService.SubscribeToStreamingNotificationsOnAllFolders method
Создает запрос подписки на потоковые уведомления.Creates a request to subscribe to streaming notifications.
Подписка по запросуPull
Операции подпискиSubscribe operation
Метод ExchangeService.BeginSubscribeToPullNotificationsExchangeService.BeginSubscribeToPullNotifications method
Метод ExchangeService.BeginSubscribeToPullNotificationsOnAllFoldersExchangeService.BeginSubscribeToPullNotificationsOnAllFolders method
Метод ExchangeService.SubscribeToPullNotificationsExchangeService.SubscribeToPullNotifications method
Метод ExchangeService.SubscribeToPullNotificationsOnAllFoldersExchangeService.SubscribeToPullNotificationsOnAllFolders method
Создает запрос подписки на уведомления по запросу.Creates a request to subscribe to pull notifications.
Push-уведомлениеPush
Операции подпискиSubscribe operation
Перегруженный метод ExchangeService.BeginSubscribeToPushNotificationsExchangeService.BeginSubscribeToPushNotifications overloaded method
Перегруженный метод ExchangeService.BeginSubscribeToPushNotificationsOnAllFoldersExchangeService.BeginSubscribeToPushNotificationsOnAllFolders overload method
Перегруженный метод ExchangeService.SubscribeToPushNotificationsExchangeService.SubscribeToPushNotifications overloaded method
Перегруженный метод ExchangeService.SubscribeToPushNotificationsOnAllFoldersExchangeService.SubscribeToPushNotificationsOnAllFolders overloaded method
Создает запрос подписки на push-уведомления.Creates a request to subscribe to push notifications.

Как получить события служб EWS?How do I get EWS events?

Способ отправки данных о фактических событиях зависит от типа созданной вами подписки.After the subscription is created, the way in which the actual events are sent to the client depends on the subscription type.

Для потоковых уведомлений необходимо создать соединение для подписки с потоковой передачей, а затем добавить в него нужную подписку.For streaming notifications, a streaming subscription connection must be created, and then the subscription is added to the connection. Больше об этом можно узнать в статье Потоковая передача уведомлений о событиях почтовых ящиков с помощью веб-служб Exchange в Exchange.You can read more about this process in Stream notifications about mailbox events by using EWS in Exchange.

Для уведомлений по запросу объект подписки инициализируется при создании подписки, поэтому для получения событий с сервера достаточно вызвать метод GetEvent или соответствующую операцию.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. Больше об этом можно узнать в статье Уведомления по запросу о событиях почтовых ящиков с помощью веб-служб Exchange в Exchange.You can read more about this in Pull notifications about mailbox events by using EWS in Exchange.

В таблице ниже перечислены операции и классы, необходимые для получения событий.The following table lists the operations and classes required to retrieve events.

Таблица 3. Элементы и классы для создания соединения и получения событийTable 3. Elements and classes for creating a connection and getting events

Тип подпискиSubscription type Операция служб EWSEWS operation Метод управляемого API EWSEWS Managed API method ДействиеWhat it does
Подписка с потоковой передачейStreaming
Операция GetStreamingEventsGetStreamingEvents operation
Метод StreamingSubscriptionConnection.AddSubscriptionStreamingSubscriptionConnection.AddSubscription method
Создает на сервере ожидающий запрос GET, ответ на который приходит при возникновении какого-либо события.Creates a hanging get request on the server, which is responded to when events occur.
Подписка по запросуPull
Операция GetEventsGetEvents operation
Метод PullSubscription.GetEventsPullSubscription.GetEvents method
Получает с сервера уведомления по запросу.Gets pull notification events from the server.
Принудительная подпискаPush
Не применимо.Not applicable.
Не применимо.Not applicable.
Push-уведомления автоматически отправляются на прослушиватель для веб-службы (URL-адрес обратного вызова указывается в запросе на подписку). Не требуется вызывать дополнительные методы или операции.Push notifications are automatically sent to the web service listener (the callback URL specified in the subscription request). No additional methods or operations need to be called.

Как отменить подписку на уведомления?How do I unsubscribe to notifications?

В таблице ниже указаны способы отмены подписки на различные типы уведомлений.The following table lists the ways in which you can unsubscribe to each type of subscription.

Таблица 4. Методы отмены подписки на уведомления и необходимые операцииTable 4. Operations and methods for unsubscribing to notifications

Тип подпискиSubscription type Службы EWSEWS Управляемый API EWSEWS Managed API
Подписка с потоковой передачейStreaming
Операция по отмене подпискиUnsubscribe operation
Метод StreamingSubscription.BeginUnsubscribeStreamingSubscription.BeginUnsubscribe method
Метод StreamingSubscription.EndUnsubscribeStreamingSubscription.EndUnsubscribe method
Метод StreamingSubscription.UnsubscribeStreamingSubscription.Unsubscribe method
Подписка по запросуPull
Операция по отмене подпискиUnsubscribe operation
Метод PullSubscription.BeginUnsubscribePullSubscription.BeginUnsubscribe method
Метод PullSubscription.EndUnsubscribePullSubscription.EndUnsubscribe method
Метод PullSubscription.UnsubscribePullSubscription.Unsubscribe method
Push-уведомлениеPush
Верните значение Unsubscribe в элементе StatusFrequency элемента SendNotificationResponseMessageReturn Unsubscribe in the StatusFrequency element of the SendNotificationResponseMessage
Не применимо. Подождите, пока истечет время ожидания для подписки.Not applicable. Let the subscription time out instead.

Вы также можете дождаться окончания времени ожидания для любой из подписок.Alternatively, you can let each of the subscriptions time out.

Таблица 5. Окончание времени ожидания для подписокTable 5. Subscription time-outs

Тип подпискиSubscription type Значение времени ожидания в службах EWSTimeout value in EWS Значение времени ожидания в управляемом API EWSTimeout value in the EWS Managed API Обработка времени ожиданияTimeout handling
Подписка с потоковой передачейStreaming
Элемент ConnectionTimeoutConnectionTimeout element
Параметр lifetime конструктора StreamingSubscriptionConnectionlifetime parameter of the StreamingSubscriptionConnection constructor
Для управляемого API EWS по истечении заданного значения времени ожидания запускается событие OnDisconnect. Если не вызван метод StreamingSubscriptionConnection.Open соединение прерывается. For the EWS Managed API, after the timeout value elapses, the OnDisconnect event is raised. If the StreamingSubscriptionConnection.Open method is not called, the connection is closed.
Для служб EWS по истечении заданного значения времени ожидания сообщение GetUserConfigurationResponse возвращает для элемента ConnectionStatus значение "Закрыто".For EWS, after the timeout value elapses, the GetUserConfigurationResponse message returns a ConnectionStatus value of Closed.
Подписка по запросуPull
Элемент TimeoutTimeout element
Параметр timeout метода SubscribeToPullNotificationtimeout parameter of the SubscribeToPullNotification method
По истечении заданного значения времени ожидания сервер удаляет подписку.After the timeout value elapses, the server deletes the subscription.
Push-уведомлениеPush
Элемент StatusFrequencyStatusFrequency element
Параметр frequency метода SubscribeToPushNotificationfrequency parameter of the SubscribeToPushNotification method
Если сервер не получает ответ на push-уведомление или проверку состояния связи, он несколько раз пытается отправить уведомление, а затем прекращает отправку. Дополнительные сведения см. в статье StatusFrequency. 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. For more information, see StatusFrequency.

Можно ли ограничить подписки?Can I limit subscriptions?

В локальном развертывании можно ограничить количество подписок для каждого пользователя с помощью параметра регулирования количества запросов EwsMaxSubscriptions политики регулирования. Эту политику можно применить как ко всем пользователям, так и выборочно к некоторым из них. Политику регулирования EwsMaxSubscriptions невозможно настроить для Exchange Online.In an on-premises deployment, you can limit the number of subscriptions per user with the EwsMaxSubscriptions throttling parameter of the throttling policy. That policy can be applied to all users or just specific users. The EwsMaxSubscriptions throttling policy is not configurable for Exchange Online.

В этой статьеIn this section

См. такжеSee also