Introducción al SDK de Microsoft Graph PowerShell Parte III: Interacción con Exchange Online y SharePoint Online
Más allá de las simples tareas de gestión
En la parte II de esta serie, analicé cómo Microsoft Graph y Graph PowerShell SDK permiten a los administradores administrar muchos aspectos de Microsoft 365 desde un solo módulo. Con algo de experiencia en PowerShell, el SDK hace que las tareas administrativas estándar y los informes sean relativamente fáciles.
Si bien es bueno tener esta funcionalidad en un solo lugar, administrar Microsoft 365 a través de PowerShell es una vieja noticia para la mayoría de los administradores. La ventaja del SDK de Graph sobre otros métodos es que puede aprovechar al máximo la API de Graph, lo que permite a los administradores interactuar con servicios de Microsoft 365 como Exchange Online y SharePoint Online, que anteriormente requerían el uso de API dedicadas que posiblemente necesitaban mucho tiempo. mayor inversión de tiempo para aprender.
Adiós EWS
Exchange Web Services (EWS) ha sido una parte integral de Microsoft Exchange desde Exchange Server 2007. EWS admite el acceso programático a recursos de Exchange, como buzones de correo. En 2018, el equipo de Exchange anunció que ya no invertirían activamente en EWS para Exchange Online y recomendó que los propietarios y proveedores de aplicaciones migraran a Microsoft Graph. A esto le siguieron depreciaciones del API en 2021, lo que indica que el fin de EWS está a la vista.
Interactuar con elementos de correo
Una tarea común de EWS es recuperar y procesar correo desde un buzón. El SDK de Microsoft Graph PowerShell facilita este proceso con varios cmdlets relacionados con mensajese. Por ejemplo, el siguiente comando recupera todos los elementos del buzón de un usuario.
Nota: el uso de permisos delegados como se detalla en la parte I de esta serie solo le permite recuperar elementos a los que su cuenta tiene acceso, como su propio buzón. Para acceder a otros buzones y recursos a los que no tiene acceso, se deben utilizar los permisos de la aplicación. De forma predeterminada, el SDK siempre utilizará permisos delegados. Para obtener más información sobre el uso de permisos de aplicaciones, consulte la parte I de esta serie.
Get-MgUserMessage -UserId <UserID> -AllDevolver todos los elementos de un buzón es una buena prueba, pero no muy práctica cuando se crea código para completar una tarea. Hay varias formas de filtrar los resultados para mejorar el tiempo de ejecución del cmdlet y devolver solo los objetos relevantes. Primero, podemos devolver solo los elementos de una carpeta específica. El cmdlet Get-MgUserMailFolder devuelve las carpetas de nivel superior de un buzón y el cmdlet Get-MgUserMailFolderChildFolder devuelve las subcarpetas de una carpeta. En la Figura 1, encontramos el ID único de la carpeta Bandeja de entrada y lo usamos para obtener el ID de la subcarpeta Correos a procesar. Cada elemento de correo y carpeta tiene un ID único asignado por Exchange Online que se almacena en la propiedad ID del elemento.
El cmdlet Get-MgUserMailFolderMessage devuelve elementos de correo contenidos en una carpeta especificada. Luego, estos resultados se pueden filtrar o buscar para limitarlos aún más utilizando la sintaxis siguiente.
##Return all messages in a particular folder
Get-MgUserMailFolderMessage -MailFolderId AAMkAGI4NjhmMDBjLTcyNTEtNDZkYy1hMmNhLTZjMThjYjQxODIzZgAuAAAAAAAdY2Aq0HOqRqKvhWSGlIAmAQDcQ9TSiMrlRrOhGqycky_7AABCa1F8AAA= -UserId ffcf3b2c-83d0-4e5f-a432-6d6a740a99d1 -All | fl subject,id
##Search messages in a particular folder for the word “PIM”
Get-MgUserMailFolderMessage -MailFolderId AAMkAGI4NjhmMDBjLTcyNTEtNDZkYy1hMmNhLTZjMThjYjQxODIzZgAuAAAAAAAdY2Aq0HOqRqKvhWSGlIAmAQDcQ9TSiMrlRrOhGqycky_7AABCa1F8AAA= -UserId ffcf3b2c-83d0-4e5f-a432-6d6a740a99d1 -All -Search "PIM" | fl subject,id,ReceivedDateTime
##Filter messages in a particular folder by receivedDateTime and by subject starting with “Your weekly PIM digest'”
Get-MgUserMailFolderMessage -MailFolderId AAMkAGI4NjhmMDBjLTcyNTEtNDZkYy1hMmNhLTZjMThjYjQxODIzZgAuAAAAAAAdY2Aq0HOqRqKvhWSGlIAmAQDcQ9TSiMrlRrOhGqycky_7AABCa1F8AAA= -UserId ffcf3b2c-83d0-4e5f-a432-6d6a740a99d1 -All -Filter "(receivedDateTime gt 2022-10-01T00:00:00Z) and (startswith(Subject,'Your weekly PIM digest'))" | fl subject,id,ReceivedDateTime
Como se muestra en la Figura 2, la combinación de filtros y búsqueda con cmdlets como Get-MgUserMailFolderMessage reduce los resultados y nos permite recuperar exactamente lo que queremos.
Más información: para obtener más información sobre cómo evaluar elementos del buzón con Graph SDK, consulte este artículo sobre cómo crear un informe de contenido del buzón con PowerShell y Graph.
Los elementos se devuelven en formato JSON y los elementos de correo se devuelven como un tipo de recurso de mensaje. Un tipo de recurso es un formato predefinido (en JSON) para un objeto en particular; el esquema para el objeto de tipo de recurso de mensaje se detalla en la documentación de Graph.
El SDK de Graph también admite la modificación de elementos de correo existentes con el cmdlet Update-MgUserMessage. En el código que se muestra a continuación, actualizamos el asunto del mensaje identificado con un identificador de mensaje:
##Modify the subject of a message
Update-MgUserMessage -MessageId AAMkAGI4NjhmMDBjLTcyNTEtNDZkYy1hMmNhLTZjMThjYjQxODIzZgBGAAAAAAAdY2Aq0HOqRqKvhWSGlIAmBwDcQ9TSiMrlRrOhGqycky_7AABCa1F8AADcQ9TSiMrlRrOhGqycky_7AABCa4w1AAA= -UserId ffcf3b2c-83d0-4e5f-a432-6d6a740a99d1 -Subject "Updated message subject"
El cmdlet Move-MgUserMessage moverá un correo a una carpeta de destino. En la Figura 3, obtenemos el ID de un elemento de correo existente, obtenemos el ID de la carpeta Bandeja de entrada y movemos el correo a ella.
Los casos de uso para modificar elementos de correo existentes son bastante limitados fuera de las pruebas. Lo que resulta más práctico es la posibilidad de enviar correos electrónicos directamente desde PowerShell. Este artículo que explica cómo enviar correo electrónico de Exchange Online utilizando Microsoft Graph SDK para PowerShell muestra cómo usar Graph SDK para enviar correo directamente desde PowerShell.
Trabajar con SharePoint en línea
La gestión y generación de informes de archivos y sitios es otro beneficio clave de Microsoft Graph. Interactuar con archivos y sitios en SharePoint Online (y por extensión Teams y OneDrive) a través de PowerShell previamente requería conocimiento del módulo SharePoint PnP PowerShell o del modelo de objetos del lado del cliente (CSOM) de SharePoint, ninguno de los cuales es particularmente intuitivo si no tiene experiencia. en el desarrollo de SharePoint.
Microsoft Graph expone puntos finales para interactuar con SharePoint Online y, si bien no tiene la profundidad que tienen PnP o CSOM (creación de plantillas de sitio, por ejemplo), la mayoría de las tareas que los administradores de inquilinos deben realizar son totalmente compatibles.
Un ejemplo de cómo Graph puede ayudar a los administradores en SharePoint Online es este artículo sobre cómo usar las API de Graph para crear un informe de archivos en un sitio de SharePoint Online. El código de este artículo primero busca la lista de unidades (Bibliotecas de documentos) adjuntas a un sitio en particular y filtra la biblioteca "Documentos". Desde aquí, expande los archivos y carpetas bajo la raíz para crear un informe útil.
Este script utiliza el cmdlet Invoke-MgGraphRequest en el SDK de PowerShell para consultar el punto final Drives y devolver todas las bibliotecas. Invoke-MgGraphRequest es una excelente manera de ejecutar consultas en puntos finales que conoce o puntos finales que no tienen un cmdlet SDK de PowerShell nativo.
Se pueden obtener los mismos resultados utilizando el cmdlet Get-MgSiteDrive, sin embargo, existen algunos matices en el cmdlet. Por ejemplo, simplemente ejecutar Get-MgSiteDrive en un sitio en particular consultará el punto final /drive de un sitio. El punto final /drive solo devuelve la biblioteca de documentos predeterminada de un sitio. Esto se muestra en la Figura 4 usando la función debug del SDK como se analiza en este artículo sobre el uso del parámetro Debug para los cmdlets del SDK de Microsoft Graph PowerShell para exponer solicitudes de Graph API.
Para devolver todas las unidades adjuntas a un sitio, debemos agregar el parámetro -All. Este parámetro cambia el punto final que se consulta de /drive a /drives. Este cambio sutil en el URI (que es difícil de detectar cuando se soluciona el problema de por qué un script no funciona como se esperaba) cambia el conjunto de resultados de la biblioteca predeterminada a todas las bibliotecas. El URI con el parámetro -All presente se muestra en la Figura 5.
Este matiz (o característica, es difícil decirlo a partir de la documentación) es relativamente pequeño, pero comienza a mostrar algunas de las asperezas del SDK de PowerShell. El SDK todavía es un trabajo en progreso y sin duda madurará con el tiempo con documentación mejorada y más puntos finales compatibles directamente con cmdlets. Hasta entonces, siempre existe el cmdlet Invoke-MgGraphRequest para llenar los vacíos.
Otro ejemplo es enumerar los archivos en una unidad. El cmdlet Get-MgDriveItem parece que debería hacer lo que se necesita aquí; sin embargo, este cmdlet usa el punto final /drive/driveid/items, que se usa para devolver elementos específicos. No enumerar todos los elementos. En el script, el URI https://graph.microsoft.com/v1.0/sites/$ ($Site.Id)/drives/$ ($DocumentLibrary.Id)/root/children se usa con el cmdlet Invoke-MgGraphRequest y esto hace el trabajo perfectamente.
Resumen
El SDK de Graph PowerShell es una excelente herramienta para que los administradores interactúen con cargas de trabajo de Microsoft 365 de formas que antes no eran prácticas sin una importante inversión de tiempo. El SDK abre muchas posibilidades para comenzar con Microsoft Graph, sin embargo, hay algunas áreas que necesitan mejorar.
Si bien no reemplaza el aprendizaje de las complejidades de Graph API para crear soluciones complejas, el SDK es una manera fantástica de comenzar y realizar tareas estándar sin necesidad de invertir demasiado tiempo.
Gestión de riesgos de ciberseguridad para Active Directory
Descubra cómo prevenir y recuperarse de ataques AD a través de estas soluciones de gestión de riesgos de ciberseguridad.