Trabalhar com pastas de pesquisa usando o EWS no Exchange
Descubra como criar, obter, atualizar e excluir pastas de pesquisa usando a API Gerenciada do EWS ou o EWS no Exchange.
Uma pasta de pesquisa representa uma pesquisa persistente "always-on" na caixa de correio de um usuário. Uma pasta de pesquisa parece e age como uma pasta de caixa de correio regular. No entanto, em vez de conter itens, ele contém uma cópia "virtual" de itens de todas as pastas em seu escopo de pesquisa que correspondam aos critérios de pesquisa definidos na pasta. Aplicativos e usuários finais podem usar pastas de pesquisa. Seu aplicativo precisa executar a mesma pesquisa 14h? As pastas de pesquisa são uma ótima ferramenta para essa tarefa. Ou talvez você só queira dar aos seus usuários a capacidade de acessar e gerenciar pastas de pesquisa em seu cliente. Qualquer que seja o cenário, a API Gerenciada do EWS e o EWS permitem que seu aplicativo interaja totalmente com pastas de pesquisa.
Observação
Este artigo se aplica somente ao usar o Outlook no modo online. As pastas de pesquisa não são sincronizadas; Portanto, as pastas de pesquisa criadas no modo online não serão exibidas no modo armazenado em cache.
Tabela 1. Métodos de API Gerenciada do EWS e operações EWS para trabalhar com pastas de pesquisa
| Se você quiser... | Na API Gerenciada do EWS, use... | No EWS, use... |
|---|---|---|
| Criar uma pasta de pesquisa |
SearchFolder.Save |
Operação CreateFolder |
| Obter uma pasta de pesquisa |
SearchFolder.Bind |
Operação GetFolder |
| Atualizar uma pasta de pesquisa |
SearchFolder.Update |
Operação UpdateFolder |
| Excluir uma pasta de pesquisa |
SearchFolder.Delete |
Operação DeleteFolder |
Conceitos principais a serem conhecidos por trabalhar com pastas de pesquisa
Antes de começar a trabalhar com pastas de pesquisa, você deseja estar familiarizado com como os filtros de pesquisa funcionam. As pastas de pesquisa dependem de filtros de pesquisa para expressar seus critérios. Os filtros de pesquisa para pastas de pesquisa são construídos da mesma forma que os filtros de pesquisa para operações de pesquisa são construídos .
Criar uma pasta de pesquisa usando a API Gerenciada do EWS
Basicamente, você cria uma pasta de pesquisa usando a API Gerenciada do EWS da mesma forma que cria uma pasta regular. No entanto, em vez de usar a classe Pasta, use a classe SearchFolder e defina a propriedade SearchParameters para configurar os critérios de pesquisa.
No exemplo a seguir, uma pasta de pesquisa é criada para localizar todas as mensagens na caixa de entrada e suas subpastas enviadas pelo gerente do usuário, sadie@contoso.com. A pasta é criada como filho da pasta Pastas de Pesquisa na caixa de correio do usuário.
Observação
Você pode criar uma pasta de pesquisa como filho de qualquer pasta na caixa de correio do usuário. No entanto, se você quiser que a pasta recém-criada apareça em Pastas de Pesquisa no Outlook, crie-a na pasta Pastas de Pesquisa bem conhecida, usando o valor SearchFolders da enumeração WellKnownFolderName.
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 CreateSearchFolder(ExchangeService service)
{
// Create the folder.
SearchFolder searchFolder = new SearchFolder(service);
searchFolder.DisplayName = "From Manager";
// Create a search filter to express the criteria
// for the folder.
EmailAddress manager = new EmailAddress("sadie@contoso.com");
SearchFilter.IsEqualTo fromManagerFilter =
new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, manager);
// Set the search filter.
searchFolder.SearchParameters.SearchFilter = fromManagerFilter;
// Set the folder to search.
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
// Set the search traversal. Deep will search all subfolders.
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
// Call Save to make the EWS call to create the folder.
searchFolder.Save(WellKnownFolderName.SearchFolders);
}
Criar uma pasta de pesquisa usando o EWS
Se você estiver usando o EWS, use a operação CreateFolder com um elemento SearchFolder para criar uma pasta de pesquisa. No exemplo de solicitação a seguir, uma pasta de pesquisa é criada para localizar todas as mensagens na caixa de entrada e suas subpastas enviadas pelo gerente do usuário, sadie@contoso.com. A pasta é criada na pasta Pastas de Pesquisa na caixa de correio do usuário.
Observação
Você pode criar uma pasta de pesquisa como filho de qualquer pasta na caixa de correio do usuário. No entanto, se você quiser que a pasta recém-criada apareça em Pastas de Pesquisa no Outlook, crie-a na pasta Pastas de Pesquisa bem conhecida, usando o valor das pastas de pesquisa no atributo Id do elemento DistinguishedFolderId .
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:CreateFolder>
<m:ParentFolderId>
<t:DistinguishedFolderId Id="searchfolders" />
</m:ParentFolderId>
<m:Folders>
<t:SearchFolder>
<t:DisplayName>From Manager</t:DisplayName>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="sadie@contoso.com" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</m:Folders>
</m:CreateFolder>
</soap:Body>
</soap:Envelope>
O servidor responde com uma mensagem CreateFolderResponse que inclui um valor ResponseCode de NoError, que indica êxito.
Obter uma pasta de pesquisa usando a API Gerenciada do EWS
Use o método de API Gerenciada do ExchangeService.FindFolders EWS para encontrar pastas de pesquisa. Observe, no entanto, que você não pode limitar seus resultados a incluir apenas pastas de pesquisa; você vai querer ter isso em mente quando processar os resultados. Use o método SearchFolder.Bind para obter pastas de pesquisa.
O exemplo a seguir encontra as primeiras 10 pastas na pasta Pastas de Pesquisa. Ele verifica se cada uma é uma pasta de pesquisa e, se for o caso, obtém a pasta de pesquisa e exibe quantas pastas de destino ela pesquisa.
using Microsoft.Exchange.WebServices.Data;
static void GetSearchFolders(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You can't request only search folders in
// a FindFolders request, so other search folders might also be present.
if (folder is SearchFolder)
{
Console.WriteLine("{0} is a search folder.", folder.DisplayName);
// In order to access the SearchParameters property,
// you have to bind to the folder. SearchParameters are not
// returned in FindFolders results.
SearchFolder searchFolder = SearchFolder.Bind(service, folder.Id);
Console.WriteLine("Number of folders searched: {0}.",
searchFolder.SearchParameters.RootFolderIds.Count);
}
else
{
Console.WriteLine("{0} is NOT a search folder.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
Obter uma pasta de pesquisa usando o EWS
Se você estiver usando o EWS, use a operação FindFolder para localizar pastas de pesquisa e a operação GetFolder para obter pastas de pesquisa. Uma resposta getfolder bem-sucedida para uma pasta de pesquisa conterá um elemento SearchFolder . O exemplo de solicitação a seguir encontra as primeiras 10 pastas na pasta Pastas de Pesquisa.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:FindFolder Traversal="Shallow">
<m:FolderShape>
<t:BaseShape>IdOnly</t:BaseShape>
<t:AdditionalProperties>
<t:FieldURI FieldURI="folder:DisplayName" />
</t:AdditionalProperties>
</m:FolderShape>
<m:IndexedPageFolderView MaxEntriesReturned="10" Offset="0" BasePoint="Beginning" />
<m:ParentFolderIds>
<t:DistinguishedFolderId Id="searchfolders" />
</m:ParentFolderIds>
</m:FindFolder>
</soap:Body>
</soap:Envelope>
O servidor retorna a resposta a seguir, que mostra uma pasta de 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="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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:FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:FindFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:RootFolder IndexedPagingOffset="3" TotalItemsInView="3" IncludesLastItemInRange="true">
<t:Folders>
<t:SearchFolder>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:DisplayName>From Manager</t:DisplayName>
</t:SearchFolder>
</t:Folders>
</m:RootFolder>
</m:FindFolderResponseMessage>
</m:ResponseMessages>
</m:FindFolderResponse>
</s:Body>
</s:Envelope>
O exemplo a seguir de uma solicitação usa o valor do elemento FolderId da resposta anterior em uma solicitação de operação GetFolder para obter a pasta de pesquisa.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:GetFolder>
<m:FolderShape>
<t:BaseShape>AllProperties</t:BaseShape>
</m:FolderShape>
<m:FolderIds>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
</m:FolderIds>
</m:GetFolder>
</soap:Body>
</soap:Envelope>
O servidor retorna a resposta a seguir com todas as propriedades de primeira classe da pasta de 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="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns="http://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:GetFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<m:ResponseMessages>
<m:GetFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:SearchFolder>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:ParentFolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
<t:FolderClass>IPF.Note</t:FolderClass>
<t:DisplayName>From Manager</t:DisplayName>
<t:TotalCount>8</t:TotalCount>
<t:ChildFolderCount>0</t:ChildFolderCount>
<t:EffectiveRights>
<t:CreateAssociated>true</t:CreateAssociated>
<t:CreateContents>true</t:CreateContents>
<t:CreateHierarchy>true</t:CreateHierarchy>
<t:Delete>true</t:Delete>
<t:Modify>true</t:Modify>
<t:Read>true</t:Read>
<t:ViewPrivateItems>true</t:ViewPrivateItems>
</t:EffectiveRights>
<t:UnreadCount>0</t:UnreadCount>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="/o=First Organization/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=8d84a3f4cbb34d48838a3aecf99795c0-Sadie" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:FolderId Id="AQMkAGM2..." ChangeKey="AQAAAA==" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</m:Folders>
</m:GetFolderResponseMessage>
</m:ResponseMessages>
</m:GetFolderResponse>
</s:Body>
</s:Envelope>
Atualizar uma pasta de pesquisa usando a API Gerenciada do EWS
Use o método Folder.Update EWS Managed API em um objeto SearchFolder para atualizar uma pasta de pesquisa. O exemplo a seguir atualiza os critérios de pesquisa em uma pasta de pesquisa com o nome de exibição "From Manager".
using Microsoft.Exchange.WebServices.Data;
static void UpdateSearchFolder(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You cannot request only search folders in
// a FindFolders request, so other search folders might also be present.
if (folder is SearchFolder && folder.DisplayName.Equals("From Manager"))
{
Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
SearchFolder searchFolder = folder as SearchFolder;
EmailAddress newManager = new EmailAddress("hope@contoso.com");
SearchFilter.IsEqualTo newManagerFilter =
new SearchFilter.IsEqualTo(EmailMessageSchema.Sender, newManager);
searchFolder.SearchParameters.SearchFilter = newManagerFilter;
searchFolder.SearchParameters.RootFolderIds.Add(WellKnownFolderName.Inbox);
searchFolder.SearchParameters.Traversal = SearchFolderTraversal.Deep;
searchFolder.Update();
Console.WriteLine("\"{0}\" folder updated.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
Atualizar uma pasta de pesquisa usando o EWS
Se você estiver usando o EWS, use a operação UpdateFolder com um elemento SearchFolder para atualizar uma pasta de pesquisa. O exemplo de solicitação a seguir atualiza os critérios de pesquisa na pasta de pesquisa "From Manager".
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:UpdateFolder>
<m:FolderChanges>
<t:FolderChange>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:SearchParameters" />
<t:SearchFolder>
<t:SearchParameters Traversal="Deep">
<t:Restriction>
<t:IsEqualTo>
<t:FieldURI FieldURI="message:Sender" />
<t:FieldURIOrConstant>
<t:Constant Value="hope@contoso.com" />
</t:FieldURIOrConstant>
</t:IsEqualTo>
</t:Restriction>
<t:BaseFolderIds>
<t:DistinguishedFolderId Id="inbox" />
</t:BaseFolderIds>
</t:SearchParameters>
</t:SearchFolder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</m:FolderChanges>
</m:UpdateFolder>
</soap:Body>
</soap:Envelope>
O servidor responde com uma mensagem UpdateFolderResponse que inclui um valor ResponseCode de NoError, que indica êxito.
Excluir uma pasta de pesquisa usando a API Gerenciada do EWS
Use o método Folder.Delete EWS Managed API em um objeto SearchFolder para excluir uma pasta de pesquisa. O exemplo a seguir exclui uma pasta de pesquisa com o nome de exibição "From Manager". A pasta de pesquisa excluída é movida para a pasta Itens Excluídos.
using Microsoft.Exchange.WebServices.Data;
static void DeleteSearchFolder(ExchangeService service)
{
FolderView folderView = new FolderView(10);
folderView.PropertySet = new PropertySet(FolderSchema.DisplayName);
try
{
FindFoldersResults findResults = service.FindFolders(WellKnownFolderName.SearchFolders, folderView);
foreach (Folder folder in findResults.Folders)
{
// You cannot request only search folders in
// a FindFolders request, so other folders might also be present.
if (folder is SearchFolder && folder.DisplayName.Equals("From Manager"))
{
Console.WriteLine("\"{0}\" folder found.", folder.DisplayName);
folder.Delete(DeleteMode.MoveToDeletedItems);
Console.WriteLine("\"{0}\" folder deleted.", folder.DisplayName);
}
}
}
catch (Exception ex)
{
Console.WriteLine("Exception while enumerating results: {0}", ex.Message);
}
}
Excluir uma pasta de pesquisa usando o EWS
Se você estiver usando o EWS, use a operação DeleteFolder para excluir uma pasta de pesquisa. O exemplo a seguir exclui uma pasta de pesquisa e a move para a pasta Itens Excluídos.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<t:RequestServerVersion Version="Exchange2007_SP1" />
<t:TimeZoneContext>
<t:TimeZoneDefinition Id="Eastern Standard Time" />
</t:TimeZoneContext>
</soap:Header>
<soap:Body>
<m:DeleteFolder DeleteType="MoveToDeletedItems">
<m:FolderIds>
<t:FolderId Id="AAMkAGM2..." ChangeKey="CAAAABYA..." />
</m:FolderIds>
</m:DeleteFolder>
</soap:Body>
</soap:Envelope>
O servidor responde com uma mensagem DeleteFolderResponse que inclui um valor ResponseCode de NoError, que indica sucesso.
Confira também
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários