Compilación de aplicaciones de Python con Microsoft Graph

En este tutorial se explica cómo crear una aplicación de consola de Python que use Microsoft Graph API para acceder a los datos en nombre de un usuario.

En este tutorial, aprenderá a:

• Obtener el usuario que ha iniciado sesión
• Enumerar los mensajes de bandeja de entrada del usuario
• Enviar correo electrónico

Requisitos previos

Antes de iniciar este tutorial, debe tener Python y pip instalados en la máquina de desarrollo.

También debe tener una cuenta profesional o educativa de Microsoft con un buzón de Exchange Online. Si no tiene un inquilino de Microsoft 365, puede calificar para uno a través del Programa para desarrolladores de Microsoft 365; Para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.

Registrar la aplicación en el portal

• 28 minutos restantes

En este ejercicio registrará una nueva aplicación en Azure Active Directory para habilitar la autenticación de usuario. Puede registrar una aplicación mediante el Centro de administración de Microsoft Entra o mediante el SDK de PowerShell de Microsoft Graph.

Registro de la aplicación para la autenticación de usuario

En esta sección registrará una aplicación que admita la autenticación de usuario mediante el flujo de código de dispositivo.

Creación de una aplicación de consola de Python

• 25 minutos restantes

Empiece por crear un nuevo archivo de Python.

1. Cree un nuevo archivo denominado main.py y agregue el código siguiente.

   print ('Hello world!')
   

2. Guarde el archivo y use el siguiente comando para ejecutar el archivo.

   python3 main.py
   

   Si funciona, la aplicación debe generar Hello world!.

Instalar dependencias

Antes de continuar, agregue algunas dependencias adicionales que usará más adelante.

• Biblioteca cliente de Identidad de Azure para Python para autenticar al usuario y adquirir tokens de acceso.
• SDK de Microsoft Graph para Python (versión preliminar) para realizar llamadas a Microsoft Graph.

Ejecute los siguientes comandos en la CLI para instalar las dependencias.

python3 -m pip install azure-identity
python3 -m pip install msgraph-sdk

Cargar la configuración de la aplicación

En esta sección agregará los detalles del registro de la aplicación al proyecto.

1. Cree un archivo en el mismo directorio que main.py denominado config.cfg y agregue el código siguiente.

   [azure]
   clientId = YOUR_CLIENT_ID_HERE
   tenantId = common
   graphUserScopes = User.Read Mail.Read Mail.Send
   

2. Actualice los valores según la tabla siguiente.

   Configuración	Valor
   clientId	El identificador de cliente del registro de la aplicación
   tenantId	Si eligió la opción para permitir que solo los usuarios de su organización inicien sesión, cambie este valor por el identificador de inquilino. De lo contrario, deje como common.

   Sugerencia

   Opcionalmente, puede establecer estos valores en un archivo independiente denominado config.dev.cfg.

Diseñar la aplicación

En esta sección creará un menú simple basado en consola.

1. Cree un nuevo archivo denominado graph.py y agregue el código siguiente a ese archivo.

   # Temporary placeholder
   class Graph:
       def __init__(self, config):
           self.settings = config
   

   Este código es un marcador de posición. Implementará la Graph clase en la sección siguiente.

2. Abra main.py y reemplace todo su contenido por el código siguiente.

   import asyncio
   import configparser
   from msgraph.generated.models.o_data_errors.o_data_error import ODataError
   from graph import Graph
   
   async def main():
       print('Python Graph Tutorial\n')
   
       # Load settings
       config = configparser.ConfigParser()
       config.read(['config.cfg', 'config.dev.cfg'])
       azure_settings = config['azure']
   
       graph: Graph = Graph(azure_settings)
   
       await greet_user(graph)
   
       choice = -1
   
       while choice != 0:
           print('Please choose one of the following options:')
           print('0. Exit')
           print('1. Display access token')
           print('2. List my inbox')
           print('3. Send mail')
           print('4. Make a Graph call')
   
           try:
               choice = int(input())
           except ValueError:
               choice = -1
   
           try:
               if choice == 0:
                   print('Goodbye...')
               elif choice == 1:
                   await display_access_token(graph)
               elif choice == 2:
                   await list_inbox(graph)
               elif choice == 3:
                   await send_mail(graph)
               elif choice == 4:
                   await make_graph_call(graph)
               else:
                   print('Invalid choice!\n')
           except ODataError as odata_error:
               print('Error:')
               if odata_error.error:
                   print(odata_error.error.code, odata_error.error.message)
   

3. Agregue los siguientes métodos de marcador de posición al final del archivo. Los implementará en pasos posteriores.

   async def greet_user(graph: Graph):
       # TODO
       return
   
   async def display_access_token(graph: Graph):
       # TODO
       return
   
   async def list_inbox(graph: Graph):
       # TODO
       return
   
   async def send_mail(graph: Graph):
       # TODO
       return
   
   async def make_graph_call(graph: Graph):
       # TODO
       return
   

4. Agregue la siguiente línea para llamar main al final del archivo.

   # Run main
   asyncio.run(main())
   

Esto implementa un menú básico y lee la elección del usuario desde la línea de comandos.

Agregar autenticación de usuario

• 20 minutos restantes

En esta sección ampliará la aplicación del ejercicio anterior para admitir la autenticación con Azure AD. Esto es necesario para obtener el token de acceso de OAuth necesario para llamar a Microsoft Graph. En este paso, integrará la biblioteca cliente de Azure Identity para Python en la aplicación y configurará la autenticación para el SDK de Microsoft Graph para Python (versión preliminar).

La biblioteca de identidades de Azure proporciona varias clases que implementan flujos de TokenCredential token de OAuth2. El SDK de Microsoft Graph usa esas clases para autenticar llamadas a Microsoft Graph.

Configuración del cliente de Graph para la autenticación de usuario

En esta sección usará la DeviceCodeCredential clase para solicitar un token de acceso mediante el flujo de código del dispositivo.

1. Abra graph.py y reemplace todo su contenido por el código siguiente.

   from configparser import SectionProxy
   from azure.identity import DeviceCodeCredential
   from msgraph import GraphServiceClient
   from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder
   from msgraph.generated.users.item.mail_folders.item.messages.messages_request_builder import (
       MessagesRequestBuilder)
   from msgraph.generated.users.item.send_mail.send_mail_post_request_body import (
       SendMailPostRequestBody)
   from msgraph.generated.models.message import Message
   from msgraph.generated.models.item_body import ItemBody
   from msgraph.generated.models.body_type import BodyType
   from msgraph.generated.models.recipient import Recipient
   from msgraph.generated.models.email_address import EmailAddress
   
   class Graph:
       settings: SectionProxy
       device_code_credential: DeviceCodeCredential
       user_client: GraphServiceClient
   
       def __init__(self, config: SectionProxy):
           self.settings = config
           client_id = self.settings['clientId']
           tenant_id = self.settings['tenantId']
           graph_scopes = self.settings['graphUserScopes'].split(' ')
   
           self.device_code_credential = DeviceCodeCredential(client_id, tenant_id = tenant_id)
           self.user_client = GraphServiceClient(self.device_code_credential, graph_scopes)
   

   Este código declara dos propiedades privadas, un DeviceCodeCredential objeto y un GraphServiceClient objeto . La __init__ función crea una nueva instancia de DeviceCodeCredentialy, a continuación, usa esa instancia para crear una nueva instancia de GraphServiceClient. Cada vez que se realiza una llamada API a Microsoft Graph a través de user_client, usará la credencial proporcionada para obtener un token de acceso.

2. Agregue la siguiente función a graph.py.

   async def get_user_token(self):
       graph_scopes = self.settings['graphUserScopes']
       access_token = self.device_code_credential.get_token(graph_scopes)
       return access_token.token
   

3. Reemplace la función vacía display_access_token de main.py por lo siguiente.

   async def display_access_token(graph: Graph):
       token = await graph.get_user_token()
       print('User token:', token, '\n')
   

4. Compile y ejecute la aplicación. Escriba 1 cuando se le solicite una opción. La aplicación muestra una dirección URL y un código de dispositivo.

   Python Graph Tutorial
   
   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   1
   To sign in, use a web browser to open the page https://microsoft.com/devicelogin and
   enter the code RB2RUD56D to authenticate.
   

5. Abra un explorador y vaya a la dirección URL que se muestra. Escriba el código proporcionado e inicie sesión.

   Importante

   Tenga en cuenta cualquier cuenta de Microsoft 365 existente que haya iniciado sesión en el explorador al navegar a https://microsoft.com/devicelogin. Use características del explorador como perfiles, modo invitado o modo privado para asegurarse de autenticarse como la cuenta que quiere usar para las pruebas.

6. Una vez completado, vuelva a la aplicación para ver el token de acceso.

   Sugerencia

   Solo con fines de validación y depuración, puede descodificar tokens de acceso de usuario (solo para cuentas profesionales o educativas) mediante el analizador de tokens en línea de Microsoft en https://jwt.ms. Esto puede ser útil si encuentra errores de token al llamar a Microsoft Graph. Por ejemplo, comprobar que la scp notificación del token contiene los ámbitos de permiso de Microsoft Graph esperados.

Obtener usuario

• 15 minutos restantes

En esta sección incorporará Microsoft Graph a la aplicación. Para esta aplicación, usará el SDK de Microsoft Graph para Python (versión preliminar) para realizar llamadas a Microsoft Graph.

1. Agregue la siguiente función a graph.py.

   async def get_user(self):
       # Only request specific properties using $select
       query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
           select=['displayName', 'mail', 'userPrincipalName']
       )
   
       request_config = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
           query_parameters=query_params
       )
   
       user = await self.user_client.me.get(request_configuration=request_config)
       return user
   

2. Reemplace la función vacía greet_user de main.py por lo siguiente.

   async def greet_user(graph: Graph):
       user = await graph.get_user()
       if user:
           print('Hello,', user.display_name)
           # For Work/school accounts, email is in mail property
           # Personal accounts, email is in userPrincipalName
           print('Email:', user.mail or user.user_principal_name, '\n')
   

Si ejecuta la aplicación ahora, después de iniciar sesión en la aplicación le da la bienvenida por su nombre.

Hello, Megan Bowen!
Email: MeganB@contoso.com

Código explicado

Tenga en cuenta el código de la get_user función . Son solo unas pocas líneas, pero hay algunos detalles clave que debe tener en cuenta.

Acceso a 'me'

La función compila una solicitud a la API Get user . Esta API es accesible de dos maneras:

GET /me
GET /users/{user-id}

En este caso, el código llamará al punto de conexión de API GET /me . Se trata de un método abreviado para obtener el usuario autenticado sin conocer su identificador de usuario.

Solicitud de propiedades específicas

La función usa el parámetro de consulta $select para especificar el conjunto de propiedades que necesita. Microsoft Graph devolverá solo las propiedades solicitadas en la respuesta. En get_user, esto se logra con el select parámetro en el MeRequestBuilderGetQueryParameters objeto .

Bandeja de entrada de lista

• 12 minutos restantes

En esta sección agregará la capacidad de enumerar los mensajes en la bandeja de entrada de correo electrónico del usuario.

1. Agregue la siguiente función a graph.py.

   async def get_inbox(self):
       query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
           # Only request specific properties
           select=['from', 'isRead', 'receivedDateTime', 'subject'],
           # Get at most 25 results
           top=25,
           # Sort by received time, newest first
           orderby=['receivedDateTime DESC']
       )
       request_config = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
           query_parameters= query_params
       )
   
       messages = await self.user_client.me.mail_folders.by_mail_folder_id('inbox').messages.get(
               request_configuration=request_config)
       return messages
   

2. Reemplace la función vacía list_inbox de main.py por lo siguiente.

   async def list_inbox(graph: Graph):
       message_page = await graph.get_inbox()
       if message_page and message_page.value:
           # Output each message's details
           for message in message_page.value:
               print('Message:', message.subject)
               if (
                   message.from_ and
                   message.from_.email_address
               ):
                   print('  From:', message.from_.email_address.name or 'NONE')
               else:
                   print('  From: NONE')
               print('  Status:', 'Read' if message.is_read else 'Unread')
               print('  Received:', message.received_date_time)
   
           # If @odata.nextLink is present
           more_available = message_page.odata_next_link is not None
           print('\nMore messages available?', more_available, '\n')
   

3. Ejecute la aplicación, inicie sesión y elija la opción 2 para mostrar la bandeja de entrada.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   2
   Message: Updates from Ask HR and other communities
     From: Contoso Demo on Yammer
     Status: Read
     Received: 2022-04-26T19:19:05Z
   Message: Employee Initiative Thoughts
     From: Patti Fernandez
     Status: Read
     Received: 2022-04-25T19:43:57Z
   Message: Voice Mail (11 seconds)
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-22T19:43:23Z
   Message: Our Spring Blog Update
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-19T22:19:02Z
   Message: Atlanta Flight Reservation
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-19T15:15:56Z
   Message: Atlanta Trip Itinerary - down time
     From: Alex Wilber
     Status: Unread
     Received: 2022-04-18T14:24:16Z
   
   ...
   
   More messages available? True
   

Código explicado

Tenga en cuenta el código de la get_inbox función .

Acceso a carpetas de correo conocidas

La función compila una solicitud a list messages API. Dado que incluye el mail_folders.by_mail_folder_id('inbox') generador de solicitudes, la API solo devolverá mensajes en la carpeta de correo solicitada. En este caso, dado que la bandeja de entrada es una carpeta predeterminada y conocida dentro del buzón de un usuario, es accesible a través de su nombre conocido. Se obtiene acceso a las carpetas no predeterminadas de la misma manera, reemplazando el nombre conocido por la propiedad id. de la carpeta de correo. Para obtener más información sobre los nombres de carpeta conocidos disponibles, consulte tipo de recurso mailFolder.

Acceso a una colección

A diferencia de la get_user función de la sección anterior, que devuelve un único objeto, este método devuelve una colección de mensajes. La mayoría de las API de Microsoft Graph que devuelven una colección no devuelven todos los resultados disponibles en una sola respuesta. En su lugar, usan la paginación para devolver una parte de los resultados al tiempo que proporcionan un método para que los clientes soliciten la siguiente "página".

Tamaños de página predeterminados

Las API que usan la paginación implementan un tamaño de página predeterminado. En el caso de los mensajes, el valor predeterminado es 10. Los clientes pueden solicitar más (o menos) mediante el parámetro de consulta $top . En get_inbox, esto se logra con el top parámetro en el MessagesRequestBuilderGetQueryParameters objeto .

Obtención de páginas posteriores

Si hay más resultados disponibles en el servidor, las respuestas de colección incluyen una @odata.nextLink propiedad con una dirección URL de API para acceder a la página siguiente. El SDK de Python expone esto como la propiedad en objetos odata_next_link de página de colección. Si esta propiedad está presente, hay más resultados disponibles.

Ordenar colecciones

La función usa el parámetro de consulta $orderby para solicitar resultados ordenados por el momento en que se recibe el mensaje (receivedDateTime propiedad). Incluye la DESC palabra clave para que los mensajes recibidos más recientemente aparezcan primero. En get_inbox, esto se logra con el orderby parámetro en el MessagesRequestBuilderGetQueryParameters objeto .

Enviar correo

• 8 minutos restantes

En esta sección agregará la capacidad de enviar un mensaje de correo electrónico como usuario autenticado.

1. Agregue la siguiente función a graph.py.

   async def send_mail(self, subject: str, body: str, recipient: str):
       message = Message()
       message.subject = subject
   
       message.body = ItemBody()
       message.body.content_type = BodyType.Text
       message.body.content = body
   
       to_recipient = Recipient()
       to_recipient.email_address = EmailAddress()
       to_recipient.email_address.address = recipient
       message.to_recipients = []
       message.to_recipients.append(to_recipient)
   
       request_body = SendMailPostRequestBody()
       request_body.message = message
   
       await self.user_client.me.send_mail.post(body=request_body)
   

2. Reemplace la función vacía send_mail de main.py por lo siguiente.

   async def send_mail(graph: Graph):
       # Send mail to the signed-in user
       # Get the user for their email address
       user = await graph.get_user()
       if user:
           user_email = user.mail or user.user_principal_name
   
           await graph.send_mail('Testing Microsoft Graph', 'Hello world!', user_email or '')
           print('Mail sent.\n')
   

3. Ejecute la aplicación, inicie sesión y elija la opción 3 para enviarse un correo electrónico.

   Please choose one of the following options:
   0. Exit
   1. Display access token
   2. List my inbox
   3. Send mail
   4. Make a Graph call
   3
   Mail sent.
   

   Nota:

   Si está realizando pruebas con un inquilino para desarrolladores del Programa para desarrolladores de Microsoft 365, es posible que el correo electrónico que envíe no se entregue y que reciba un informe de no entrega. Si esto ocurre, póngase en contacto con el soporte técnico a través del Centro de administración de Microsoft 365.

4. Para comprobar que se ha recibido el mensaje, elija la opción 2 para mostrar la bandeja de entrada.

Código explicado

Tenga en cuenta el código de la send_mail función .

Envío de correo

La función usa el generador de user_client.me.send_mail solicitudes, que compila una solicitud a send mail API.

Creación de objetos

A diferencia de las llamadas anteriores a Microsoft Graph que solo leen datos, esta llamada crea datos. Para ello con la biblioteca cliente, cree un diccionario que represente la carga de la solicitud, establezca las propiedades deseadas y, a continuación, envíela en la llamada API. Dado que la llamada envía datos, se usa el post método en lugar de get.

Opcional: agregue su propio código

• 5 minutos restantes

En esta sección agregará sus propias funcionalidades de Microsoft Graph a la aplicación. Podría tratarse de un fragmento de código de la documentación de Microsoft Graph o del Explorador de Graph, o código que haya creado. Esta sección es opcional.

Actualizar la aplicación

1. Agregue la siguiente función a graph.py.

   async def make_graph_call(self):
       # INSERT YOUR CODE HERE
       return
   

2. Reemplace la función vacía make_graph_call de main.py por lo siguiente.

   async def make_graph_call(graph: Graph):
       await graph.make_graph_call()
   

Elección de una API

Busque una API en Microsoft Graph que le gustaría probar. Por ejemplo, create event API. Puede usar uno de los ejemplos de la documentación de la API o crear su propia solicitud de API.

Configurar permisos

Compruebe la sección Permisos de la documentación de referencia de la API elegida para ver qué métodos de autenticación se admiten. Algunas API no admiten solo aplicaciones ni cuentas personales de Microsoft, por ejemplo.

• Para llamar a una API con autenticación de usuario (si la API admite la autenticación de usuario (delegado), agregue el ámbito de permiso necesario en config.cfg.
• Para llamar a una API con autenticación solo de aplicación, consulte el tutorial de autenticación de solo aplicación .

Agregar el código

Copie el código en la make_graph_call función de graph.py. Si va a copiar un fragmento de código de la documentación o del Explorador de Graph, asegúrese de cambiar el GraphServiceClient nombre a self.user_client.

¡Enhorabuena!

• 100 % completado.

Ha completado el tutorial de Microsoft Graph de Python. Ahora que tiene una aplicación en funcionamiento que llama a Microsoft Graph, puede experimentar y agregar nuevas características.

• Obtenga información sobre cómo usar la autenticación de solo aplicación con el SDK de Microsoft Graph para Python.
• Visite información general de Microsoft Graph para ver todos los datos a los que puede acceder con Microsoft Graph.

Ejemplos de Python

• Aplicación web de Django
• Ejemplo de API de seguridad