Uso de atributos y filtros de correo electrónico¶
Como se mostró anteriormente en la sección de obtención de mensajes de correo electrónico, podemos utilizar diferentes atributos en un filtro al buscar algunos mensajes de correo electrónico.
Usando la API de Microsoft Graph, los filtros se basan en el Protocolo de Datos Abiertos (OData). La cadena de filtro nos permite crear filtros avanzados combinando diferentes atributos y operaciones.
En los ejemplos a continuación, mostramos algunas formas de crear filtros avanzados y comparaciones al utilizar directamente una cadena de filtro basada en OData.
Construyendo una cadena de filtro¶
Generalmente, la cadena de filtro es compleja y puede resultar confusa dependiendo de las operaciones realizadas. Basándonos en esto, a través del complemento, es posible crear filtros de manera más sencilla mediante la clase Query. De esta manera, logramos crear las mismas cadenas de filtro pero de forma más fácil e intuitiva.
Para comenzar a construir la cadena de filtro, vamos a utilizar la instancia del complemento de Outlook.
Utilizando el método new_query_filter, obtendremos el objeto Query que se utilizará como base para construir un nuevo filtro.
Utilizando atributos del mensaje¶
Este objeto Query nos permite definir el atributo que pretendemos utilizar en el filtro; luego, podemos determinar la operación que se realizará considerando este atributo.
Por ejemplo, podemos buscar un correo electrónico con un asunto específico o que contenga cierto contenido en el asunto.
# Filter to search for all emails with the subject "Test Message"
query_filter.on_attribute("subject").equals("Test Message")
# Filter to search for all emails with "Test" in the subject
query_filter.on_attribute("subject").contains("Test")
# Filter considering only the address that sent the email
query_filter.on_attribute("from").equals("test@email.com")
Utilizando múltiples atributos en el filtro¶
Además de utilizar atributos individualmente, también es posible combinar múltiples atributos en la misma cadena de criterios.
Esto sería equivalente a una operación Y. Solo se devolverán los mensajes que cumplan con todos los filtros.
También es posible realizar operaciones O para filtrar mensajes por un atributo u otro. En este caso, utiliza el método chain indicando el operador O.
# Filter only messages that match one of these attributes:
#
# "Filter this message" as subject
# OR
# "Message to filter" as subject
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 la cadena de filtro al obtener mensajes¶
Después de construir la cadena de filtro, simplemente úsala como parámetro del método search_messages.
outlook = MS365OutlookPlugin(service_account=service)
# Creating a new filter through the Query object
query_filter = outlook.new_query_filter()
# Filter using email subject
query_filter.on_attribute("subject").equals("Test Message")
# Searching for all emails with the subject "Test Message"
messages = outlook.search_messages(criteria=query_filter)
# This same filter could also be written this way (OData)
messages = outlook.search_messages(criteria="subject eq 'Test Message'")
Comparando cadenas de filtro¶
A primera vista, puede parecer que las cadenas en formato OData no son confusas.
Sin embargo, construir la cadena de esta manera puede ser inviable dependiendo de la complejidad y cantidad de operaciones requeridas en el filtro.
Los ejemplos a continuación muestran filtros creados utilizando la guía anterior y la versión equivalente en cadena de texto OData.
Tip
Si ya utilizas o estás familiarizado con el patrón del Protocolo de Datos Abiertos (OData), puedes continuar construyendo las cadenas de filtro de esta manera sin ningún problema.
El método search_messages también admite la cadena de filtro en este modelo siempre que la sintaxis sea correcta.
La clase Query es solo un facilitador y una forma más práctica de crear filtros para buscar mensajes específicos.
- Filtro utilizando el asunto del correo electrónico
- Filtro utilizando la dirección que envió el correo electrónico
- Filtro utilizando múltiples atributos de correo electrónico
- Filtro realizando una operación 'O'
- Filtros utilizando la fecha de creación del correo electrónico
Tip
Utilizando el atributo created_date_time, puedes realizar varias operaciones utilizando una fecha específica como base.
Puedes crear un filtro para buscar correos electrónicos que se recibieron en esa fecha y en una fecha mayor o menor a esa.
from datetime import datetime
...
# Searching for emails received on 04/26/2023
query_filter.on_attribute('created_date_time').equals(datetime(2023, 4, 26))
# Searching for emails with a date greater than or equal to 04/26/2023
query_filter.on_attribute('created_date_time').greater_equal(datetime(2023, 4, 26))
# Searching for emails with a date less than or equal to 04/26/2023
query_filter.on_attribute('created_date_time').less_equal(datetime(2023, 4, 26))
# Searching for emails received on 04/26/2023
"createdDateTime eq 2023-04-26T03:00:00+00:00"
# Searching for emails with a date greater than or equal to 04/26/2023
"createdDateTime ge 2023-04-26T03:00:00+00:00"
# Searching for emails with a date less than or equal to 04/26/2023
"createdDateTime le 2023-04-26T03:00:00+00:00"
Tabla de atributos¶
Consulta la tabla a continuación para ver los atributos más comunes que se pueden utilizar para construir filtros utilizando el objeto Query.
| Atributo | Descripción | Tipo de valor |
|---|---|---|
subject |
el asunto del correo electrónico | str |
from |
la dirección del remitente del correo | str |
created_date_time |
fecha del correo electrónico | fecha |
body |
contiene el texto en el cuerpo del correo | str |
isRead |
el correo tiene la marca "leído" o no | bool |