Usando atributos e filtros de e-mail¶
Conforme mostrado anteriormente na seção buscando mensagens de e-mail, podemos usar diferentes atributos em um filtro ao buscar por alguns e-mails.
Utilizando a API do Microsoft Graph, os filtros são baseados no Open Data Protocol (OData). A string de filtro nos permite basicamente criar filtros avançados combinando diferentes atributos e operações.
Nos exemplos abaixo mostraremos algumas formas de como criar filtros avançados e também algumas comparações ao utilizar direto uma string de filtro baseada no OData.
Construindo uma string de filtro¶
No geral, a string de filtro é complexa e pode ficar confusa dependendo das operações a serem realizadas. Com base nisso, através do plugin é possível criar filtros de uma maneira mais simplificada através da classe Query. Dessa forma, conseguimos criar as mesmas strings de filtro porém de uma forma mais facilitada e intuitiva.
Para começarmos a construir a string de filtro, vamos utilizar a própria instância do plugin do Outlook.
Através do método new_query_filter vamos obter o objeto Query que será utilizado como base na construção de um novo filtro.
Utilizando atributos da mensagem¶
Basicamente, esse objeto Query nos permite definir o atributo que pretendemos utilizar no filtro, em seguida podemos definir a operação que será feita considerando esse atributo.
Podemos por exemplo procurar por um e-mail que tenha um assunto específico, ou que contenha um determinado conteúdo no assunto.
# Filtro para buscar todos os emails que tenham como assunto "Test Message"
query_filter.on_attribute("subject").equals("Test Message")
# Filtro para buscar todos os emails que contenham "Test" no assunto
query_filter.on_attribute("subject").contains("Test")
# Filtro considerando apenas o endereço que enviou o email
query_filter.on_attribute("from").equals("test@email.com")
Utilizando múltiplos atributos no filtro¶
Além de usar atributos individualmente, também é possível combinar vários atributos na mesma sequência de filtros.
Basicamente, isso seria equivalente a uma operação AND. Somente mensagens que correspondem a todos os filtros serão retornadas.
Também é possível fazer operações OR, para filtrar mensagens por um atributo ou outro. Nesse caso, basta utilizar o método chain indicando o operador OR.
# Filtra apenas mensagens que correspondem a um desses atributos:
#
# "Filter this message" como assunto
# OR
# "Message to filter" como assunto
query_filter = outlook.new_query_filter()
query_filter.on_attribute("subject").equals("Filter this message").chain("or").\
on_attribute("subject").equals("Message to filter")
Utilizando a string de filtro ao buscar as mensagens¶
Após construir a string de filtro, basta utilizá-la como parâmetro do método search_messages.
outlook = MS365OutlookPlugin(service_account=service)
# Criando um novo filtro através do objeto Query
query_filter = outlook.new_query_filter()
# Filtro utilizando o assunto do email
query_filter.on_attribute("subject").equals("Test Message")
# Buscando todos os emails que tenham como assunto "Test Message"
messages = outlook.search_messages(criteria=query_filter)
# Esse mesmo filtro também poderia ser escrito dessa forma (OData)
messages = outlook.search_messages(criteria="subject eq 'Test Message'")
Comparando as strings de filtro¶
Em um primeiro momento pode parecer que as strings no formato OData não são tão confusas.
Porém, dependendo da complexidade e da quantidade de operações necessárias no filtro, a construção da string dessa forma pode ficar inviável.
Nos exemplos abaixo são exibidos alguns filtros criados utilizando o guia acima, e a versão da string OData equivalente.
Dica
Se você já utiliza ou tem familiaridade com o padrão Open Data Protocol (OData), pode continuar construindo as strings de filtro dessa maneira sem nenhum problema.
O método search_messages também suporta a string de filtro nesse modelo, desde que a sintaxe esteja correta.
A classe Query é somente um facilitador e uma forma mais prática na hora de criar filtros para buscar por mensagens específicas.
- Filtro utilizando o assunto do e-mail
- Filtro utilizando o endereço que enviou o e-mail
- Filtro utilizando múltiplos atributos do e-mail
- Filtro realizando uma operação de 'OR'
- Filtros utilizando a data de criação do e-mail
Dica
Utilizando o atributo created_date_time você pode realizar diversas operações utilizando uma data específica como base.
É possível criar um filtro para buscar e-mails que foram recebidos nessa data, assim como em uma data maior ou menor do que essa.
from datetime import datetime
...
# Buscando e-mails recebidos na data 26/04/2023
query_filter.on_attribute('created_date_time').equals(datetime(2023, 4, 26))
# Buscando e-mails com a data maior ou igual do que 26/04/2023
query_filter.on_attribute('created_date_time').greater_equal(datetime(2023, 4, 26))
# Buscando e-mails com a data menor ou igual do que 26/04/2023
query_filter.on_attribute('created_date_time').less_equal(datetime(2023, 4, 26))
# Buscando e-mails recebidos na data 26/04/2023
"createdDateTime eq 2023-04-26T03:00:00+00:00"
# Buscando e-mails com a data maior ou igual do que 26/04/2023
"createdDateTime ge 2023-04-26T03:00:00+00:00"
# Buscando e-mails com a data menor ou igual do que 26/04/2023
"createdDateTime le 2023-04-26T03:00:00+00:00"
Tabela de atributos¶
Veja na tabela abaixo os atributos mais comuns que podem ser utilizados na construção dos filtros através do objeto Query.
| Atributo | Descrição | Tipo de valor |
|---|---|---|
subject |
o assunto do e-mail | str |
from |
o endereço do remetente do e-mail | str |
created_date_time |
a data de recebimento do e-mail | date |
body |
contém o texto no corpo do e-mail | str |
isRead |
o e-mail possui a flag "lido" ou não | bool |