FindItem 操作FindItem operation

查找有关FindItem EWS 操作的信息。Find information about the FindItem EWS operation.

FindItem操作将搜索位于用户邮箱中的项目。The FindItem operation searches for items that are located in a user's mailbox. 此操作提供了多种方法来筛选和设置搜索结果返回给呼叫者的方式。This operation provides many ways to filter and format how search results are returned to the caller.

使用 FindItem 操作Using the FindItem operation

FindItem操作请求提供了多种方法来搜索邮箱并设置数据在响应中的返回方式。The FindItem operation request provides many ways for you to search a mailbox and format how the data is returned in a response. 您可以在FindItem请求中指定以下内容:You can specify the following in a FindItem request:

  • 搜索是浅表遍历还是软删除遍历。Whether the search is a shallow or soft-deleted traversal. 指定此属性是必需的。Specifying this is required. 请注意,与搜索限制组合在一起的软删除的遍历将导致返回零个项目,即使存在与搜索条件匹配的项目也是如此。Note that a soft-deleted traversal combined with a search restriction will result in zero items returned, even if there are items that match the search criteria.

  • 项目的响应形状。The response shape of items. 这标识响应中返回的属性。This identifies the properties that are returned in the response. 指定此属性是必需的。Specifying this is required.

  • 要从中执行搜索的文件夹。The folders from which to perform the search. 指定此属性是必需的。Specifying this is required.

  • 页面中返回视图数据的分页机制和视图类型。The paging mechanism and view types for returning view data in pages. 指定此参数是可选的。Specifying this is optional.

  • 用于对返回的项进行分组和排序的选项。Options for grouping and sorting the items that are returned. 指定此参数是可选的。Specifying this is optional.

  • 用于筛选返回的项目的搜索限制或高级查询语法(AQS)字符串。Search restrictions or Advanced Query Syntax (AQS) strings for filtering the items that are returned. 有关使用 AQS 进行内容索引搜索的详细信息,请参阅QueryString (String)For more information about using AQS for content index searches, see QueryString (String). 指定此参数是可选的。Specifying this is optional.

  • 响应中返回的项目的排序顺序。The sort order for items returned in the response. 指定此参数是可选的。Specifying this is optional.

FindItem操作仅返回任何 streamable 属性的前512个字节。The FindItem operation returns only the first 512 bytes of any streamable property. 对于 Unicode,它通过使用以 null 结尾的 Unicode 字符串返回前255个字符。For Unicode, it returns the first 255 characters by using a null-terminated Unicode string. 它不会返回任何邮件正文格式或收件人列表。It does not return any of the message body formats or the recipient lists. FindItem将返回收件人摘要。FindItem will return a recipient summary. 您可以使用GetItem 操作来获取项目的详细信息。You can use the GetItem operation to get the details of an item.

FindItem仅返回Name (EmailAddressType)元素,并且不会返回以下字段的邮箱元素中的EmailAddress (NonEmptyStringType)元素:FindItem returns only the Name (EmailAddressType) element and does not return the EmailAddress (NonEmptyStringType) element in the Mailbox element for the following fields:

备注

FindItem操作可以返回CalendarView元素中的结果。The FindItem operation can return results in a CalendarView element. CalendarView元素返回单个日历项目和定期会议的所有事件。The CalendarView element returns single calendar items and all occurrences of recurring meetings. 如果未使用CalendarView元素,则将返回单个日历项目和定期主日历项目。If a CalendarView element is not used, single calendar items and recurring master calendar items are returned. 如果未使用CalendarView元素,则必须从定期母版展开此事件。The occurrences must be expanded from the recurring master if a CalendarView element is not used.

FindItem操作可以使用下表中列出的 SOAP 标头。The FindItem operation can use the SOAP headers that are listed in the following table.

表1。FindItem 操作 SOAP 标头Table 1. FindItem operation SOAP headers

HeaderHeader 元素Element 说明Description
DateTimePrecisionDateTimePrecision
DateTimePrecisionDateTimePrecision
指定对来自服务器的响应中的数据/时间值的解析(以秒或毫秒为单位)。Specifies the resolution of data/time values in responses from the server, either in seconds or in milliseconds. 这适用于请求。This is applicable to a request.
模拟Impersonation
ExchangeImpersonationExchangeImpersonation
标识客户端应用程序模拟的用户。Identifies the user whom the client application is impersonating. 这适用于请求。This is applicable to a request.
MailboxCultureMailboxCulture
MailboxCultureMailboxCulture
标识要用于访问邮箱的 RFC3066 区域性。Identifies the RFC3066 culture to be used to access the mailbox. 这适用于请求。This is applicable to a request.
RequestVersionRequestVersion
RequestServerVersionRequestServerVersion
标识操作请求的架构版本。Identifies the schema version for the operation request. 这适用于请求。This is applicable to a request.
ServerVersionServerVersion
ServerVersionInfoServerVersionInfo
标识响应请求的服务器版本。Identifies the version of the server that responded to the request. 这适用于响应。This is applicable to a response.
TimeZoneContextTimeZoneContext
TimeZoneContextTimeZoneContext
标识要用于来自服务器的所有响应的时区。Identifies the time zone to be used for all responses from the server. 这适用于请求。This is applicable to a request.

FindItem 操作请求示例FindItem operation request example

下面的FindItem请求示例演示如何获取由BaseShape元素的IdOnly枚举定义的项标识符,这些项是在 "已删除的项目" 文件夹中找到的项。The following example of a FindItem request shows how to obtain the item identifier that is defined by the IdOnly enumeration of the BaseShape element for items that are found in the Deleted Items folder.

<?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>
    <FindItem xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
              Traversal="Shallow">
      <ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
      </ItemShape>
      <ParentFolderIds>
        <t:DistinguishedFolderId Id="deleteditems"/>
      </ParentFolderIds>
    </FindItem>
  </soap:Body>
</soap:Envelope>

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

有关FindItem请求消息的更多选项,请浏览架构层次结构。For more options for a FindItem request message, explore the schema hierarchy. FindItem元素开始。Start at the FindItem element.

成功的 FindItem 操作响应Successful FindItem operation response

下面的示例演示对FindItem请求的成功响应。The following example shows a successful response to the FindItem request.

Message元素表示由 EWS 架构不强类型化的电子邮件和其他所有项目。Message elements represent email messages and all other items that are not strongly typed by the EWS schema. 项目,如 IPM。共享和 IPM. InfoPath 以邮件元素的形式返回。Items such as IPM.Sharing and IPM.InfoPath are returned as Message elements. Exchange 不会在响应中返回基本项目元素。Exchange does not return the base Item element in responses.

<?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="595" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder TotalItemsInView="10" IncludesLastItemInRange="true">
            <t:Items>
              <t:Message>
                <t:ItemId Id="AS4AUn=" ChangeKey="fsVU4==" />
              </t:Message>
              <t:Message>
                <t:ItemId Id="AS4AUM=" ChangeKey="fsVUA==" />
              </t:Message>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </FindItemResponse>
  </soap:Body>
</soap:Envelope>

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

有关FindItem响应消息的更多选项,请浏览架构层次结构。For more options for a FindItem response message, explore the schema hierarchy. FindItemResponse元素开始。Start at the FindItemResponse element.

FindItem 操作错误响应FindItem operation error response

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

<?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="595" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindItemResponse 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:FindItemResponseMessage ResponseClass="Error">
          <m:MessageText>Id is malformed.</m:MessageText>
          <m:ResponseCode>ErrorInvalidIdMalformed</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </FindItemResponse>
  </soap:Body>
</soap:Envelope>

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

有关FindItem错误响应消息的更多选项,请浏览架构层次结构。For more options for a FindItem error response message, explore the schema hierarchy. FindItemResponse元素开始。Start at the FindItemResponse element.

版本差异Version differences

如果使用FindItem操作在存档邮箱中搜索多个文件夹,则在ResponseCode元素中,从主要版本15开始并以 "生成 15.0.898.11" 结尾的 Exchange 版本将返回 ErrorInvalidOperation 值。Versions of Exchange starting with major version 15 and ending with build 15.0.898.11 return an ErrorInvalidOperation value in the ResponseCode element when the FindItem operation is used to search multiple folders in an archive mailbox.

另请参阅See also