Pesquisa e EWS no Exchange

Descubra como pesquisar itens no Exchange usando a API Gerenciada do EWS ou o EWS.

Significa este som está familiarizado? Você finalmente está iniciando esse projeto que está adiando há semanas e precisa de informações sobre o projeto que seu gerente lhe enviou por email semanas atrás. Sua caixa de entrada tem centenas ou talvez milhares de mensagens nela. O que você faz? Você percorre seu email examinando cada assunto e remetente até encontrá-lo? Ou você usa o recurso de pesquisa em seu cliente de email favorito para zerar rapidamente o que você precisa?

A pesquisa é, sem dúvida, um recurso obrigatório para qualquer cliente de email. Mas a pesquisa pode ser usada para muito mais do que apenas permitir que os usuários pesquisem sua caixa de correio. Seu aplicativo precisa processar compromissos que se enquadram em janelas de tempo específicas? Talvez você precise relatar todos os itens de tarefa com um status específico ou mover todos os contatos com um nome de empresa específico para uma pasta diferente. A pesquisa pode ajudar com todos esses requisitos.

Pesquisar noções básicas

A API Gerenciada do EWS e o EWS oferecem dois métodos básicos para especificar uma pesquisa. Você pode usar um filtro de pesquisa ou uma cadeia de caracteres de consulta. O método usado depende da intenção por trás da pesquisa.

Tabela 1. Cenários para filtros de pesquisa e consultas de pesquisa

Se você quiser...	Use um...	Observações
Limitar sua pesquisa a uma propriedade ou conjunto específico de propriedades	Filtro de pesquisa	Os filtros de pesquisa fornecem o melhor nível de controle sobre quais propriedades são pesquisadas. Embora as cadeias de caracteres de consulta possam atingir um conjunto limitado de propriedades usando a Sintaxe de Consulta Avançada (AQS), os filtros de pesquisa podem atingir qualquer propriedade.
Criar pesquisas com vários critérios	Filtro de pesquisa	Com filtros de pesquisa, vários critérios de pesquisa podem ser unidos com ANDs lógicos ou ORs, permitindo pesquisas como "o assunto contém 'Notas de Reunião' E o remetente é igual a 'Sadie Daniels'". Embora as cadeias de caracteres de consulta também possam ingressar em vários critérios de pesquisa, elas são limitadas ao conjunto de propriedades com suporte por cadeias de caracteres de consulta.
Pesquisar propriedades personalizadas	Filtro de pesquisa	Os filtros de pesquisa podem atingir propriedades personalizadas. As cadeias de caracteres de consulta não pesquisam propriedades personalizadas.
Executar uma pesquisa confidencial de caso de propriedades de cadeia de caracteres	Filtro de pesquisa	As pesquisas de cadeia de caracteres de consulta não são sensíveis a casos.
Controlar o modo de contenção ao pesquisar propriedades de cadeia de caracteres	Filtro de pesquisa	As pesquisas de cadeia de caracteres de consulta são sempre pesquisas de subconsulta. Se você precisar pesquisar prefixos específicos ou exigir correspondências exatas, um filtro de pesquisa será a melhor opção.
Pesquisar pastas	Filtro de pesquisa	O EWS não dá suporte à pesquisa de pastas com uma cadeia de caracteres de consulta.
Criar uma pasta de pesquisa	Filtro de pesquisa	O EWS não dá suporte à criação de pastas de pesquisa com uma cadeia de caracteres de consulta.
Pesquisar em todas as propriedades comumente usadas	Cadeia de caracteres de consulta	As cadeias de caracteres de consulta que não contêm o AQS serão pesquisadas em todas as propriedades comumente usadas. Por exemplo, um valor de cadeia de caracteres de consulta de "Mack Chaves" retornará todas as mensagens enviadas por Mack Chaves, bem como todas as mensagens que tenham "Mack Chaves" no corpo ou no assunto.
Construir uma pesquisa com base na entrada simples do usuário	Cadeia de caracteres de consulta	Uma cadeia de caracteres de consulta é uma ótima opção para permitir que um usuário final faça uma pesquisa rápida digitando em uma cadeia de caracteres simples. Como uma pesquisa de cadeia de caracteres de consulta inclui todas as propriedades comumente usadas, os resultados conterão quaisquer itens que contenham os termos de pesquisa do usuário.

Usando um filtro de pesquisa

Os filtros de pesquisa fornecem uma ampla gama de opções de pesquisa e o maior grau de controle sobre como a pesquisa é executada. Você pode usar filtros de pesquisa para executar pesquisas básicas de igualdade e comparação, mas também pode pesquisar no conteúdo de propriedades de cadeia de caracteres ou fazer comparações de máscara de bit.

Por exemplo, você pode pesquisar o conteúdo do assunto de itens usando a classe SearchFilter.ContainsSubstring na API Gerenciada do EWS. Neste exemplo, um filtro de pesquisa é criado para pesquisar o assunto para a substring "notas de reunião", ignorando o caso.

SearchFilter.ContainsSubstring subjectFilter = new SearchFilter.ContainsSubstring(ItemSchema.Subject,
    "meeting notes", ContainmentMode.Substring, ComparisonMode.IgnoreCase);

Você também pode pesquisar em propriedades personalizadas. Neste exemplo, a propriedade personalizada ItemIndex é pesquisada por valores maiores que 3.

Guid MyAppGuid = new Guid("{AA3DF801-4FC7-401F-BBC1-7C93D6498C2E}");
ExtendedPropertyDefinition customPropDefinition =
    new ExtendedPropertyDefinition(MyAppGuid, "ItemIndex", MapiPropertyType.Integer);
SearchFilter.IsGreaterThan customPropFilter =
    new SearchFilter.IsGreaterThan(customPropDefinition, 3);

Você também pode combinar vários filtros de pesquisa para criar pesquisas mais complexas. Por exemplo, você pode combinar os dois filtros anteriores com um AND lógico usando a classe SearchFilter.SearchFilterCollection .

SearchFilter.SearchFilterCollection compoundFilter =
    new SearchFilter.SearchFilterCollection(LogicalOperator.And, subjectFilter, customPropFilter);

Usando uma cadeia de caracteres de consulta

As cadeias de caracteres de consulta fornecem uma abordagem diferente para pesquisar. Você tem menos controle sobre os campos pesquisados e como a pesquisa é executada quando você usa uma pesquisa de cadeia de caracteres de consulta. Não que isso seja uma coisa ruim! Em alguns casos, talvez você queira lançar uma rede mais ampla, por assim dizer.

Por exemplo, você pode pesquisar "notas de reunião" usando o método exchangeService.FindItems EWS Managed API.

FindItemsResults<Item> results = service.FindItems(folder, "meeting notes", view);

Se você comparar os resultados dessa pesquisa com os resultados do exemplo de pesquisa SearchFilter.ContainsSubstring anteriormente, essa pesquisa conterá mais resultados. A pesquisa de filtro de pesquisa retornará apenas itens que têm "notas de reunião" no assunto, enquanto essa pesquisa retornará itens que têm "notas de reunião" no assunto, no corpo e em outros campos.

Vamos dar uma olhada em como você pode refinar a cadeia de caracteres de consulta para se aproximar dos resultados que você vê no filtro de pesquisa. Usando o AQS, você pode limitar sua pesquisa ao assunto.

FindItemsResults<Item> results = service.FindItems(folder, "subject:meeting notes", view);

Isso está mais próximo, mas os resultados ainda não são exatamente os mesmos. Quando você usa uma cadeia de caracteres de consulta com várias palavras, você receberá correspondências mesmo se as palavras não estiverem na ordem especificada ou mesmo se elas não estiverem adjacentes umas às outras. Com a cadeia de caracteres de consulta "subject:meeting notes", você receberá correspondências para "notas de reunião", "anotações da reunião" e assim por diante. Para refinar ainda mais, você pode envolver os termos de pesquisa em aspas duplas para indicar que deseja apenas essa frase.

FindItemsResults<Item> results = service.FindItems(folder, "subject:\"meeting notes\"", view);

Solicitando propriedades específicas nos resultados da pesquisa

Por padrão, os resultados da pesquisa conterão todas as propriedades nos itens que correspondem à pesquisa. Em alguns casos, isso pode ser o que você deseja, mas, na maioria dos casos, seu aplicativo requer apenas um conjunto discreto de propriedades. Nesse caso, você deve limitar o conjunto de propriedades que são retornadas apenas para as propriedades que seu aplicativo precisa. No exemplo a seguir, a classe ItemView é usada para limitar as propriedades retornadas ao assunto, à data/hora recebida e à ID dos itens.

ItemView view = new ItemView(10);
// Creating a new PropertySet with this constructor includes
// ItemSchema.Id.
view.PropertySet = new PropertySet(ItemSchema.Subject, ItemSchema.DateTimeReceived);

Controlar a profundidade da pesquisa

Definir a travessia no modo de exibição controla a profundidade e o escopo da pesquisa.

Tabela 2. Pesquisar valores de travessia

Valor de travessia	Aplica-se a	Descrição
Superficial	Itens e pastas	Pesquisas rasas são limitadas a direcionar as crianças da pasta que está sendo pesquisada.
Profundo	Itens (somente com pastas de pesquisa) e Pastas	Pesquisas profundas pesquisam recursivamente a pasta que está sendo pesquisada e subpastas.
Associado	Itens	As pesquisas associadas incluem apenas itens associados da pasta que está sendo pesquisada. Os itens associados são itens ocultos dentro da pasta.
SoftDeleted	Itens e pastas	Esse tipo de travessia é preterido. As pesquisas softDeleted incluem apenas itens que estão na lixeira. A lixeira foi substituída pela Pasta de Itens Recuperáveis em Exchange Online, Exchange Online como parte de Office 365 e versões do Exchange a partir do Exchange 2010.

Gerenciando os resultados da pesquisa

A API Gerenciada do EWS e o EWS também permitem que você altere a forma como os resultados da pesquisa são retornados. Você pode usar exibições para especificar quais propriedades estão incluídas nos resultados, classificar resultados e páginar seus resultados para obter apenas um número definido de resultados por resposta. Você também pode agrupar resultados por valores de campo específicos e controlar a profundidade de uma pesquisa especificando um tipo de travessia. Por fim, você pode usar pastas de pesquisa para criar pesquisas persistentes que são atualizadas dinamicamente à medida que novos itens chegam.

Classificação

Você pode fazer com que o servidor retorne resultados classificados, o que pode facilitar a exibição ou o processo de itens em ordem. Neste exemplo, os resultados serão classificados pela data/hora recebida, com os itens mais recentes sendo os primeiros.

view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);

Paginação

Ao enviar uma solicitação de pesquisa usando a API Gerenciada do EWS ou o EWS, você especifica um tamanho de exibição, que controla o número máximo de itens retornados. No entanto, o número de itens no servidor que correspondem à sua pesquisa pode ser maior que o tamanho da exibição. Nesse caso, o servidor indica que há mais itens disponíveis. Você pode usar a paginação para repetir sua pesquisa e obter o próximo conjunto de resultados.

Por exemplo, você pode enviar uma solicitação de pesquisa com um tamanho de exibição de 10. Pode haver 15 itens no servidor que correspondem à sua pesquisa, mas você só receberá de volta os 10 primeiros, juntamente com um indicador (o FindItemsResults<TItem>. Propriedade Mais Disponível se você estiver usando a API Gerenciada do EWS) que há mais resultados no servidor. Em seguida, você pode enviar a mesma pesquisa com um deslocamento de 10 para solicitar os próximos 10 itens que correspondem à sua pesquisa. O servidor retornará os cinco itens restantes.

Figura 1. Exemplo de pesquisa de página

Agrupamento

O Exchange permite agrupar os resultados da pesquisa por um campo específico. Isso pode ajudar a dividir os resultados da pesquisa em conjuntos mais gerenciáveis. Por exemplo, você pode pesquisar por "notas de reunião" e agrupar os resultados por remetente. Conforme mostrado na figura a seguir, os itens retornados serão separados em grupos, com todos os itens que correspondem aos critérios do mesmo remetente em um grupo, todos os itens correspondentes de outro remetente em outro grupo e assim por diante.

Figura 2. Resultados da pesquisa agrupados por remetente

Pastas de pesquisa

Com uma pesquisa regular, a pesquisa é executada, os resultados são retornados ao seu aplicativo para processamento e a pesquisa deixa de existir. As pastas de pesquisa fornecem uma maneira de tornar uma pesquisa persistente. Essa é uma ótima opção para pesquisas que você sabe que deseja executar várias vezes. Em vez de executar a mesma pesquisa repetidamente, fazendo com que o servidor avalie a pesquisa do zero sempre, uma pasta de pesquisa faz uma pesquisa sempre ativada, permitindo que o servidor atualize o conjunto de resultados existente à medida que os itens são adicionados ou removidos do escopo de pesquisa. As pastas de pesquisa agem como pastas regulares, na medida em que aparecem como pastas que têm itens nelas. A diferença é que os únicos itens contidos na pasta são aqueles que correspondem aos critérios de pesquisa associados à pasta. Depois que uma pasta de pesquisa for criada, seu aplicativo poderá obter resultados atualizados da pesquisa apenas verificando o conteúdo da pasta.

Criar uma pasta de pesquisa é simples quando você domina a criação de filtros de pesquisa. No exemplo a seguir, uma pasta de pesquisa é criada para mostrar todos os emails com um assunto que contém "notas de reunião".

static void CreateSearchFolder(ExchangeService service)
{
    SearchFilter.ContainsSubstring subjectFilter = new SearchFilter.ContainsSubstring(ItemSchema.Subject,
        "meeting notes", ContainmentMode.Substring, ComparisonMode.IgnoreCase);
    SearchFolder searchFolder = new SearchFolder(service);
    searchFolder.DisplayName = "Meeting Notes";
    searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
    searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
    searchFolder.SearchParameters.SearchFilter = subjectFilter;
    searchFolder.Save(WellKnownFolderName.SearchFolders);
}

Nesta seção

• Usar filtros de pesquisa com o EWS no Exchange

• Executar uma pesquisa do AQS usando o EWS no Exchange

• Executar pesquisas paginadas usando o EWS no Exchange

• Executar pesquisas agrupadas usando o EWS no Exchange

• Trabalhar com pastas de pesquisa usando o EWS no Exchange

Confira também

• Desenvolver clientes do serviço web para o Exchange

• Pasta Itens Recuperáveis

• ExchangeService.FindItems

• Parâmetros de política de limitação que afetam as operações de pesquisa do EWS