Operação FindItem

Artigo
03/29/2023

Encontre informações sobre a operação FindItem EWS.

A operação FindItem procura itens localizados na caixa de correio de um usuário. Essa operação fornece várias maneiras de filtrar e formatar como os resultados da pesquisa são retornados ao chamador.

Usando a operação FindItem

A solicitação de operação FindItem fornece várias maneiras de pesquisar uma caixa de correio e formatar como os dados são retornados em uma resposta. Você pode especificar o seguinte em uma solicitação FindItem :

Se a pesquisa é uma travessia superficial ou de exclusão suave. Especificar isso é necessário. Observe que uma travessia excluída suavemente combinada com uma restrição de pesquisa resultará em zero itens retornados, mesmo que haja itens que correspondam aos critérios de pesquisa.
A forma de resposta dos itens. Isso identifica as propriedades retornadas na resposta. Especificar isso é necessário.
As pastas das quais executar a pesquisa. Especificar isso é necessário.
O mecanismo de paginação e os tipos de exibição para retornar dados de exibição em páginas. Especificar isso é opcional.
Opções para agrupar e classificar os itens retornados. Especificar isso é opcional.
Restrições de pesquisa ou cadeias de caracteres AQS (Sintaxe de Consulta Avançada) para filtrar os itens retornados. Para obter mais informações sobre como usar o AQS para pesquisas de índice de conteúdo, consulte QueryString (String). Especificar isso é opcional.
A ordem de classificação dos itens retornados na resposta. Especificar isso é opcional.

A operação FindItem retorna apenas os primeiros 512 bytes de qualquer propriedade streamable. Para Unicode, ele retorna os primeiros 255 caracteres usando uma cadeia de caracteres Unicode terminada em nulo. Ele não retorna nenhum dos formatos do corpo da mensagem nem das listas de destinatários. FindItem retornará um resumo do destinatário. Você pode usar a operação GetItem para obter os detalhes de um item.

FindItem retorna apenas o elemento Nome (EmailAddressType) e não retorna o elemento EmailAddress (NonEmptyStringType) no elemento Caixa de Correio para os seguintes campos:

O campo From para mensagens
O campo Remetente para mensagens
O campo Organizador para itens de calendário

Observação

A operação FindItem pode retornar resultados em um elemento CalendarView . O elemento CalendarView retorna itens de calendário único e todas as ocorrências de reuniões recorrentes. Se um elemento CalendarView não for usado, itens de calendário único e itens de calendário mestre recorrentes serão retornados. As ocorrências devem ser expandidas do mestre recorrente se um elemento CalendarView não for usado.

A operação FindItem pode usar os cabeçalhos SOAP listados na tabela a seguir.

Tabela 1. Cabeçalhos SOAP da operação FindItem

Header	Elemento	Descrição
DateTimePrecision	DateTimePrecision	Especifica a resolução de valores de dados/tempo em respostas do servidor, em segundos ou em milissegundos. Isso é aplicável a uma solicitação.
Representação	ExchangeImpersonation	Identifica o usuário que o aplicativo cliente está representando. Isso é aplicável a uma solicitação.
MailboxCulture	MailboxCulture	Identifica a cultura RFC3066 a ser usada para acessar a caixa de correio. Isso é aplicável a uma solicitação.
RequestVersion	RequestServerVersion	Identifica a versão do esquema para a solicitação de operação. Isso é aplicável a uma solicitação.
Serverversion	ServerVersionInfo	Identifica a versão do servidor que respondeu à solicitação. Isso é aplicável a uma resposta.
TimeZoneContext	TimeZoneContext	Identifica o fuso horário a ser usado para todas as respostas do servidor. Isso é aplicável a uma solicitação.

Exemplo de solicitação de operação FindItem

O exemplo a seguir de uma solicitação FindItem mostra como obter o identificador de item definido pela enumeração IdOnly do elemento BaseShape para itens encontrados na pasta Itens Excluídos.

<?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>

Os seguintes elementos são usados na solicitação:

Para obter mais opções para uma mensagem de solicitação FindItem , explore a hierarquia de esquema. Comece no elemento FindItem .

Resposta bem-sucedida da operação FindItem

O exemplo a seguir mostra uma resposta bem-sucedida à solicitação FindItem .

Os elementos de mensagem representam mensagens de email e todos os outros itens que não são fortemente tipados pelo esquema EWS. Itens como IPM. Compartilhamento e IPM. O InfoPath é retornado como elementos de mensagem . O Exchange não retorna o elemento item base em respostas.

<?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>

Os seguintes elementos são usados na resposta:

Para obter mais opções para uma mensagem de resposta FindItem , explore a hierarquia de esquema. Comece no elemento FindItemResponse .

Resposta de erro da operação FindItem

O exemplo a seguir mostra uma resposta de erro a uma solicitação FindItem .

<?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>

Os seguintes elementos são usados na resposta de erro:

Para obter mais opções para uma mensagem de resposta de erro do FindItem , explore a hierarquia de esquema. Comece no elemento FindItemResponse .

Diferenças de versão

Versões do Exchange começando com a versão principal 15 e terminando com o build 15.0.898.11 retornam um valor ErrorInvalidOperation no elemento ResponseCode quando a operação FindItem é usada para pesquisar várias pastas em uma caixa de correio de arquivo.