Executar uma pesquisa do AQS usando o EWS no Exchange

Artigo
03/29/2023

Descubra como pesquisar com cadeias de caracteres de consulta e AQS em seu aplicativo EWS Ou API Gerenciado do EWS.

As cadeias de caracteres de consulta fornecem uma alternativa aos filtros de pesquisa para expressar critérios de pesquisa. A maior vantagem de usar cadeias de caracteres de consulta é que você não é obrigado a especificar uma única propriedade para pesquisar. Você pode apenas fornecer um valor e a pesquisa se aplicará a todos os campos comumente usados nos itens. Você também pode refinar sua pesquisa usando a Sintaxe de Consulta Avançada (AQS) em vez de um valor simples. No entanto, as cadeias de caracteres de consulta têm as seguintes limitações que você deve estar ciente antes de adicioná-las à sua caixa de ferramentas:

Capacidade limitada de pesquisar propriedades específicas. Quando você pesquisa com um valor simples em uma cadeia de caracteres de consulta, a pesquisa é executada em todas as propriedades indexadas. Você pode refinar sua pesquisa em propriedades específicas, mas as propriedades disponíveis para usar em uma cadeia de caracteres AQS são limitadas. Se a propriedade que você deseja pesquisar não for uma das propriedades disponíveis para a AQS, considere usar um filtro de pesquisa.
As propriedades personalizadas não são pesquisadas. As pesquisas de cadeia de caracteres de consulta são executadas em um índice e as propriedades personalizadas não estão incluídas nesse índice. Se você precisar pesquisar propriedades personalizadas, use um filtro de pesquisa.
Controle limitado para pesquisas de cadeia de caracteres. As pesquisas de cadeia de caracteres de consulta sempre ignoram o caso e são sempre pesquisas de subconsulta. Se você quiser fazer pesquisas de correspondência exatas, prefixos ou sensíveis a casos, use um filtro de pesquisa.
Não está disponível para pastas ou pastas de pesquisa. As operações EWS para pesquisar pastas não dão suporte ao uso de uma cadeia de caracteres de consulta. Além disso, as pastas de pesquisa não dão suporte a cadeias de caracteres de consulta. Em ambos os casos, um filtro de pesquisa é sua única opção.

Criando uma cadeia de caracteres de consulta

As cadeias de caracteres de consulta na API Gerenciada do EWS e no EWS são interpretadas como um subconjunto de sintaxe do AQS. As cadeias de caracteres AQS são compostas por valores ou pares de palavra-chave/valor, separados por um cólon (:).

keyword:value

Quando um valor é especificado sem uma palavra-chave, todas as propriedades indexadas são pesquisadas pelo valor. Se uma palavra-chave for emparelhada com um valor, a palavra-chave especifica uma propriedade para pesquisar o valor correspondente.

Tabela 1. Palavras-chave do AQS com suporte

Palavra-chave	Value type	Exemplo
assunto	Cadeia de caracteres	subject:project
corpo	Cadeia de caracteres	body:números de vendas
anexo	Cadeia de caracteres	anexo:relatório
para	Cadeia de caracteres	para:"Sadie Daniels"
from	Cadeia de caracteres	from:hope
cc	Cadeia de caracteres	cc:"Ronnie Sturgis"
bcc	Cadeia de caracteres	bcc:mack
participants	Cadeia de caracteres	participantes:sadie
category	Cadeia de caracteres	category:project
importância	Cadeia de caracteres	importance:high
Tipo	Tipo de item	kind:meetings
enviado	Data	sent:12/10/2013
recebido	Data	recebido:ontem
hasattachment	Boolean	Tem anexo:true
isflagged	Boolean	isflagged:true
isread	Boolean	isread:false
size	Número	size:>5000

Vamos dar uma olhada em como os diferentes tipos de valor funcionam.

Usando um tipo de valor de cadeia de caracteres

Os tipos de valor de cadeia de caracteres são pesquisados por padrão como pesquisas de substring de prefixo que não são sensíveis a casos. Isso significa que a pesquisa de subject:project corresponderia a qualquer um dos seguintes assuntos:

Notas da reunião do projeto
Você tem os planos do projeto?
Projeções de vendas de dezembro

Você pode alterar a pesquisa para exigir a palavra inteira em vez de corresponder prefixos, incluindo a cadeia de caracteres entre aspas. Pesquisar o assunto:"project" eliminaria o valor "projeções de vendas de dezembro" da lista de correspondências. Observe que o valor ainda não é sensível a casos.

Se você usar várias palavras em uma cadeia de caracteres de consulta, uma correspondência exigirá que ambas as palavras apareçam nos campos pesquisados. Por exemplo, a pesquisa de subject:project plan corresponderia a qualquer um dos seguintes assuntos:

Plano de projeto
Você tem os planos do projeto?
Envie-me o plano para nosso projeto
Planejamento de marcos do projeto

Se você incluir várias palavras entre aspas, elas serão tratadas como uma única frase. A pesquisa de assunto:"plano de projeto" corresponderia apenas ao assunto "Plano de projeto" da lista anterior.

Usando um tipo de valor de tipo de item

Você pode usar os seguintes valores de tipo de item com a palavra-chave do tipo para limitar os resultados da pesquisa a apenas um tipo específico de item, como solicitações de email ou de reunião:

contacts
documentos
email
Faxes
im (corresponde a mensagens instantâneas)
diários
reuniões (corresponde a compromissos e solicitações de reunião)
notes
postagens
rssfeeds
tarefas
Voicemail

Usando um tipo de valor de data

Você pode pesquisar tipos de valor de data de várias maneiras diferentes. O mais simples é pesquisar uma data específica. A pesquisa com o received:12/11/2013 retornará todos os itens recebidos em 11 de dezembro de 2013. No entanto, você também pode ser menos específico. A pesquisa com o recebido:12/11 retornará todos os itens recebidos em 11 de dezembro do ano atual.

Outra opção é usar os nomes de mês. Você pode pesquisar com o recebimento:11 de dezembro de 2013 ou 11 de dezembro para obter os mesmos resultados recebidos:12/11/2013 e recebidos:12/11, respectivamente. Você também pode pesquisar com o recebido:dezembro para obter todos os itens recebidos no mês de dezembro, no ano atual.

Usar os nomes dos dias da semana também é uma opção. Pesquisar com o recebido:terça-feira retornará todos os itens recebidos na terça-feira da semana atual.

Os tipos de valor de data também dão suporte a um conjunto de palavras-chave para pesquisas relativas à hora atual. Há suporte para as seguintes palavras-chave:

hoje
tomorrow
ontem
esta semana
A semana passada
próximo mês
mês passado
próximo ano

Os tipos de valor de data também podem ser comparados com operadores relacionais como maiores ou menores do que, ou especificados como um intervalo com o operador de intervalo ... Por exemplo, received:>11/30/2013, sent:>=yesterday, and received:12/1/2013..today are all valid query strings.

Usando um tipo de valor booliano

Os tipos de valor booliano podem ser "true" ou "false". Os valores não são sensíveis a casos, portanto, isread:false produzirá os mesmos resultados que isread:FALSE.

Usando um tipo de valor numérico

Os tipos de valor numérico podem ser pesquisados como correspondências exatas, mas também podem ser pesquisados usando operadores relacionais como maiores ou menores do que. Por exemplo, size:10000 só retornará itens com um tamanho exatamente de 10000 bytes, mas tamanho:>=10000 retornará itens que têm um tamanho maior ou igual a 10.000 bytes. Você também pode especificar um intervalo usando o operador de intervalo ( ..). Por exemplo, size:7000..8000 retornará itens que têm um tamanho entre 7000 e 8000.

Usando operadores lógicos

As cadeias de caracteres de consulta dão suporte aos operadores lógicos a seguir.

Tabela 2. Operadores lógicos com suporte

Operator	Exemplos
E	projeto E de:"Sadie Daniels" subject:(project AND plan)
OU	subject:meeting OR from:"Hope Gross" de:("Sadie Daniels" OU "Hope Gross")
NÃO	NÃO de:"Ronnie Sturgis" recebido:NÃO hoje

Observe que você pode usar esses operadores para unir vários critérios ou unir vários valores em um único par de palavras-chave/valor. No entanto, ao unir vários valores em um único par de palavras-chave/valor, você deve usar parênteses para incluir os vários valores. Para entender o porquê, considere pesquisar com:"Sadie Daniels" OU "Hope Gross". Essa pesquisa é realmente interpretada como os seguintes critérios:

O item é de Sadie Daniels, OR
O item tem a frase "Hope Gross" em qualquer uma de suas propriedades indexadas.

Em contraste, de:("Sadie Daniels" OR "Hope Gross") é interpretado como:

O item é de Sadie Daniels, OR
O item é de Hope Gross

O operador padrão quando vários critérios são especificados, mas nenhum operador lógico é incluído é AND. Por exemplo, tem anexo:true subject:project é equivalente a has:attachment:true AND subject:project.

Exemplo: localizar itens usando uma cadeia de caracteres de consulta e a API Gerenciada do EWS

Neste exemplo, um método chamado SearchWithQueryString é definido. Ele usa um objeto ExchangeService , um objeto WellKnownFolderName e um objeto de cadeia de caracteres que representa a cadeia de caracteres de consulta como parâmetros. Este exemplo supõe que o objeto ExchangeService tenha sido inicializado com valores válidos nas propriedades Credentials e URL.

using Microsoft.Exchange.WebServices.Data;
static void SearchWithQueryString(ExchangeService service, WellKnownFolderName folder, string queryString)
{
    // Limit the result set to 10 items.
    ItemView view = new ItemView(10);
    view.PropertySet = new PropertySet(ItemSchema.Subject,
                                       ItemSchema.DateTimeReceived,
                                       ItemSchema.Size,
                                       ItemSchema.Importance,
                                       EmailMessageSchema.IsRead);
    // Item searches do not support Deep traversal.
    view.Traversal = ItemTraversal.Shallow;
    // Sorting
    view.OrderBy.Add(ItemSchema.DateTimeReceived, SortDirection.Descending);
    try
    {
        // Execute the search based on the query string.
        // Example: "subject:project plan"
        FindItemsResults<Item> results = service.FindItems(folder, queryString, view);
        foreach (Item item in results.Items)
        {
            Console.WriteLine("Subject: {0}", item.Subject);
            Console.WriteLine("Received: {0}", item.DateTimeReceived.ToString());
            Console.WriteLine("Size: {0}", item.Size.ToString());
            Console.WriteLine("Importance: {0}", item.Importance.ToString());
            if (item is EmailMessage)
            {
                EmailMessage message = item as EmailMessage;
                Console.WriteLine("Read: {0}", message.IsRead.ToString());
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
    }
}

Você pode usar esse método para pesquisar todos os itens com a frase "plano de projeto" no assunto, conforme mostrado neste exemplo.

string queryString = "subject:\"project plan\"";
SearchWithQueryString(service, WellKnownFolderName.Inbox, queryString);

Exemplo: localizar itens usando uma cadeia de caracteres de consulta e EWS

Neste exemplo, uma solicitação SOAP FindItem encontra todos os itens na caixa de entrada com a frase "plano de projeto" no assunto.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
    xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
    xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:FindItem Traversal="Shallow">
      <m:ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
        <t:AdditionalProperties>
          <t:FieldURI FieldURI="item:Subject" />
          <t:FieldURI FieldURI="item:DateTimeReceived" />
          <t:FieldURI FieldURI="item:Size" />
          <t:FieldURI FieldURI="item:Importance" />
          <t:FieldURI FieldURI="message:IsRead" />
        </t:AdditionalProperties>
      </m:ItemShape>
      <m:IndexedPageItemView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
      <m:SortOrder>
        <t:FieldOrder Order="Descending">
          <t:FieldURI FieldURI="item:DateTimeReceived" />
        </t:FieldOrder>
      </m:SortOrder>
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="inbox" />
      </m:ParentFolderIds>
      <m:QueryString>subject:"project plan"</m:QueryString>
    </m:FindItem>
  </soap:Body>
</soap:Envelope>

O exemplo a seguir mostra a resposta do servidor com os resultados da pesquisa.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15" MinorVersion="0" MajorBuildNumber="712" MinorBuildNumber="22" Version="V2_3" 
        xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns="https://schemas.microsoft.com/exchange/services/2006/types" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <m:FindItemResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:FindItemResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder IndexedPagingOffset="1" TotalItemsInView="1" IncludesLastItemInRange="true">
            <t:Items>
              <t:Message>
                <t:ItemId Id="AAMkAGM2..." ChangeKey="CQAAABYA..." />
                <t:Subject>project plan</t:Subject>
                <t:DateTimeReceived>2013-12-11T15:42:02Z</t:DateTimeReceived>
                <t:Size>7406</t:Size>
                <t:Importance>Normal</t:Importance>
                <t:IsRead>false</t:IsRead>
              </t:Message>
            </t:Items>
          </m:RootFolder>
        </m:FindItemResponseMessage>
      </m:ResponseMessages>
    </m:FindItemResponse>
  </s:Body>
</s:Envelope>