GetEvents 操作GetEvents operation

请求订阅客户端使用GetEvents操作从客户端访问服务器中请求通知。The GetEvents operation is used by pull subscription clients to request notifications from the Client Access server. GetEvents操作响应返回自上次通知以来在邮箱中发生的项和事件的数组。The GetEvents operation response returns an array of items and events that have occurred in a mailbox since the last the notification.

重要

DeleteUserConfiguration操作将触发事件通知系统的移动事件。The DeleteUserConfiguration operation will trigger a move event for the event notification system. 用户配置对象将被移动到转储程序。The user configuration object will be moved to the dumpster.

备注Remarks

对日历项目所做的更改可能会导致生成多个事件。Changes to Calendar items may result in the generation of multiple events. 这些事件是在邮箱、忙/闲数据存储项目被更改为常规日历操作的一部分或同时在这两者中创建的临时项目的结果。These events are the result of temporary items being created in the mailbox, free/busy data storage items being changed as part of the normal Calendar operations, or both. 项目类 "IPM." 的事件。Web 服务客户端应忽略 FreeBusy。 SchedulePlus。Events for item class "IPM.SchedulePlus.FreeBusy.BinaryData" should be ignored by Web service clients. 这些临时项目在创建后将被删除;因此,如果尝试检索这些项,则将返回错误,指出找不到该项目。These temporary items are deleted after they are created; therefore, if an attempt is made to retrieve these items, an error will be returned that states that the item was not found.

GetEvents 请求示例GetEvents request example

DescriptionDescription

下面的示例演示如何请求与订阅标识符和水印标识的订阅相关联的事件和项目。The following example shows how to request the events and items that are associated with a subscription that is identified by the subscription identifier and watermark.

代码Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <GetEvents xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <SubscriptionId>f6bc657d-dde1-4f94-952d-143b95d6483d</SubscriptionId>
      <Watermark>AAAAAMAGAAAAAAAAAQ==</Watermark>
    </GetEvents>
  </soap:Body>
</soap:Envelope>

GetEvents 请求元素GetEvents Request Elements

请求中使用以下元素:The following elements are used in the request:

成功的 GetEvents 响应示例Successful GetEvents response example

DescriptionDescription

下面的响应示例显示通知,自上次通知请求发送到服务器后,存在两封新邮件。The following example of a response shows a notification of the existence of two new mail messages since the last notification request was sent to the server.

代码Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="628" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <GetEventsResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                       xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                       xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:GetEventsResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:Notification>
            <t:SubscriptionId>f6bc657d-dde1-4f94-952d-143b95d6483d</t:SubscriptionId>
            <t:PreviousWatermark>AAAAAMAGAAAAAAAAAQ==</t:PreviousWatermark>
            <t:MoreEvents>false</t:MoreEvents>
            <t:NewMailEvent>
              <t:Watermark>AAAAAM4GAAAAAAAAAQ==</t:Watermark>
              <t:TimeStamp>2006-08-22T00:36:29Z</t:TimeStamp>
              <t:ItemId Id="AQApAHR" ChangeKey="CQAAAA==" />
              <t:ParentFolderId Id="AQApAH" ChangeKey="AQAAAA==" />
            </t:NewMailEvent>
            <t:NewMailEvent>
              <t:Watermark>AAAAAOQGAAAAAAAAAQ==</t:Watermark>
              <t:TimeStamp>2006-08-22T01:00:50Z</t:TimeStamp>
              <t:ItemId Id="AQApAHRw" ChangeKey="CQAAAA==" />
              <t:ParentFolderId Id="AQApAH" ChangeKey="AQAAAA==" />
            </t:NewMailEvent>
          </m:Notification>
        </m:GetEventsResponseMessage>
      </m:ResponseMessages>
    </GetEventsResponse>
  </soap:Body>
</soap:Envelope>

备注Comments

备注

项目和文件夹标识符已缩短,以保持可读性。The item and folder identifiers have been shortened to preserve readability.

GetEvents 响应元素GetEvents response elements

响应中使用以下元素:The following elements are used in the response:

若要查找GetEvents操作的响应邮件的其他选项,请浏览架构层次结构。To find other options for the response message of the GetEvents operation, explore the schema hierarchy. 通知元素开始。Start at the Notification element.

GetEvents 错误响应示例GetEvents Error response example

DescriptionDescription

下面的示例演示对GetEvents请求的错误响应。The following example shows an error response to a GetEvents request.

代码Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="628" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <GetEventsResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                         xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:GetEventsResponseMessage ResponseClass="Error">
          <m:MessageText>Access is denied. Only the subscription owner may access the subscription.</m:MessageText>
          <m:ResponseCode>ErrorSubscriptionAccessDenied</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
        </m:GetEventsResponseMessage>
      </m:ResponseMessages>
    </GetEventsResponse>
  </soap:Body>
</soap:Envelope>

备注Remarks

在处理GetEvents请求时,客户端访问服务器将执行以下步骤:When processing a GetEvents request, the Client Access server performs the following steps:

  1. 将请求的 SubscriptionID 确认为在客户端访问服务器上承载的有效订阅。The SubscriptionID of the request is confirmed to be a valid subscription that is hosted on the Client Access server. 如果不是,则GetEvents调用将失败。If it is not, the GetEvents call fails.

  2. 将请求的已通过身份验证的用户的 SMTP 地址与创建订阅的用户的 SMTP 地址进行比较。The SMTP address of the authenticated user for the request is compared to the SMTP address of the user who created the subscription. 如果不匹配, GetEvents请求将失败。If they do not match, the GetEvents request fails.

  3. 将查询订阅队列中等待发送到客户端的事件。The subscription queue is queried for events that are waiting to be sent to the client. 如果队列不为空,则会从队列中提取队列中的前50个事件并将其编码到通知中。If the queue is not empty, the first 50 events from the queue are pulled from the queue and encoded into a notification.

  4. 如果队列中未找到任何事件,则会生成 StatusEvent 并将其编码到通知响应中。If no events are found in the queue, a StatusEvent is generated and encoded into a notification response.

  5. 通知响应将返回到客户端。The notification response is returned to the client.

  6. 通知中包含的事件将从订阅队列中删除,并且订阅的客户端访问服务器本地最后的水印将设置为返回的最后一个事件的水印。The events that are included in the notification are removed from the subscription queue and the Client Access server local last watermark for the subscription is set to the watermark of the last event that is returned.

  7. 订阅的超时计时器将重置。The timeout timer for the subscription is reset.

另请参阅See also

订阅操作Subscribe operation

取消订阅操作Unsubscribe operation

使用请求订阅Using Pull Subscriptions