Compilación de scripts de PowerShell con Microsoft Graph
En este tutorial se explica cómo crear un script de PowerShell que use Microsoft Graph API para acceder a los datos en nombre de un usuario.
Nota:
Para obtener información sobre cómo usar Microsoft Graph para acceder a los datos mediante la autenticación de solo aplicación, consulte este tutorial de autenticación de solo aplicación.
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
Sugerencia
Como alternativa a seguir este tutorial, puede descargar el código completado a través de la herramienta de inicio rápido , que automatiza el registro y la configuración de aplicaciones. El código descargado funciona sin necesidad de realizar modificaciones.
También puede descargar o clonar el repositorio de GitHub y seguir las instrucciones del ARCHIVO LÉAME para registrar una aplicación y configurar el proyecto.
Requisitos previos
Antes de iniciar este tutorial, debe tener PowerShell instalado en la máquina de desarrollo. PowerShell 5.1 es el requisito mínimo, pero se recomienda PowerShell 7.
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.
Nota:
Este tutorial se ha escrito con PowerShell 7.2.2 y el SDK de PowerShell de Microsoft Graph, versión 1.9.5. Los pasos de esta guía pueden funcionar con otras versiones, pero no se han probado.
Registrar la aplicación en el portal
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.
Nota:
El registro de una aplicación para la autenticación de usuario para el SDK de PowerShell de Microsoft Graph es opcional. El SDK tiene su propio registro de aplicación y el identificador de cliente correspondiente. Sin embargo, el uso de su propio identificador de aplicación permite un mayor control sobre los ámbitos de permisos para un script de PowerShell determinado.
Abra un explorador y vaya al Centro de administración de Microsoft Entra e inicie sesión con una cuenta de administrador global.
Seleccione Microsoft Entra ID en el panel de navegación izquierdo, expanda Identidad, aplicaciones y registros de aplicaciones.
Seleccione Nuevo registro. Escriba un nombre para la aplicación, por ejemplo,
Graph User Auth Tutorial.Establezca los tipos de cuenta admitidos como desee. Las opciones son:
Opción ¿Quién puede iniciar sesión? Solo las cuentas de este directorio organizativo Solo los usuarios de la organización de Microsoft 365 Cuentas en cualquier directorio organizativo Usuarios de cualquier organización de Microsoft 365 (cuentas profesionales o educativas) Cuentas en cualquier directorio organizativo... y cuentas personales de Microsoft Usuarios de cualquier organización de Microsoft 365 (cuentas profesionales o educativas) y cuentas personales de Microsoft Deje URI de redireccionamiento vacía.
Seleccione Registrar. En la página Información general de la aplicación, copie el valor del identificador de aplicación (cliente) y guárdelo, lo necesitará en el paso siguiente. Si eligió Cuentas en este directorio organizativo solo para los tipos de cuenta admitidos, copie también el identificador de directorio (inquilino) y guárdelo.
Seleccione Autenticación en Administrar. Busque la sección Configuración avanzada y cambie el botón de alternancia Permitir flujos de cliente público a Sí y, a continuación, elija Guardar.
Nota:
Tenga en cuenta que no ha configurado ningún permiso de Microsoft Graph en el registro de la aplicación. Esto se debe a que el ejemplo usa el consentimiento dinámico para solicitar permisos específicos para la autenticación de usuario.
Agregar autenticación de usuario
En esta sección autenticará una sesión de PowerShell como usuario para Microsoft Graph. Esto es necesario para obtener el token de acceso de OAuth necesario para llamar a Microsoft Graph.
El SDK de PowerShell de Microsoft Graph proporciona dos métodos de autenticación para la autenticación de usuario: la autenticación interactiva del explorador y el código del dispositivo. La autenticación interactiva del explorador usa el explorador predeterminado de un dispositivo para permitir que el usuario inicie sesión. La autenticación de código de dispositivo permite la autenticación en entornos que no tienen un explorador predeterminado. En este ejercicio, usará la autenticación de código de dispositivo.
Importante
Si aún no tiene instalado el SDK de PowerShell de Microsoft Graph, instálelo ahora antes de continuar.
Autentificar el usuario
Abra PowerShell y use el siguiente comando para establecer la
$clientIDvariable de sesión, reemplazando <your-client-id> por el identificador de cliente del registro de la aplicación.$clientId = <your-client-id>Establezca la variable de
$tenantIdsesión. Si eligió la opción para permitir que solo los usuarios de su organización inicien sesión al registrar la aplicación, reemplace <tenant-id> por el identificador de inquilino de la organización. De lo contrario, reemplace porcommon.$tenantId = <tenant-id>Establezca la variable de
$graphScopessesión.$graphScopes = "user.read mail.read mail.send"Use el siguiente comando para autenticar al usuario dentro de la sesión actual de PowerShell.
# Authenticate the user Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthenticationSugerencia
Si prefiere usar la autenticación interactiva del explorador, omita el
-UseDeviceAuthenticationparámetro .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.Una vez completado, vuelva a la ventana de PowerShell. Ejecute el siguiente comando para comprobar el contexto autenticado.
# Get the Graph context Get-MgContextClientId : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b TenantId : 601faea3-be45-4960-898f-92b379b17cd9 CertificateThumbprint : Scopes : {Mail.Read, Mail.Send, openid, profile…} AuthType : Delegated AuthProviderType : DeviceCodeProvider CertificateName : Account : MeganB@contoso.com AppName : PowerShell Graph Tutorial ContextScope : CurrentUser Certificate : PSHostVersion : 2022.4.1 ClientTimeout : 00:05:00
Obtener usuario
En esta sección obtendrá el usuario autenticado.
En la sesión de PowerShell autenticada, ejecute el siguiente comando para obtener el contexto actual. El contexto proporciona información para identificar al usuario autenticado.
$context = Get-MgContextEjecute el siguiente comando para obtener el usuario de Microsoft Graph.
# Get the authenticated user by UPN $user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'Sugerencia
Puede agregar el
-Debugmodificador al comando anterior para ver la solicitud y la respuesta de la API.Ejecute los siguientes comandos para generar información del usuario.
Write-Host "Hello," $user.DisplayName # For Work/school accounts, email is in Mail property # Personal accounts, email is in UserPrincipalName Write-Host "Email:", ($user.Mail ?? $user.UserPrincipalName)Hello, Megan Bowen! Email: MeganB@contoso.com
Código explicado
Tenga en cuenta el comando usado para obtener el usuario autenticado. Es un comando aparentemente simple, pero hay algunos detalles clave que debe tener en cuenta.
Acceso a 'me'
El Get-MgUser comando compila una solicitud a la API Get user . Esta API es accesible de dos maneras:
GET /me
GET /users/{user-id}
El SDK de PowerShell de Microsoft Graph no admite el punto de conexión de API GET /me . Para usar el punto de GEt /users/{user-id} conexión, debemos proporcionar un valor para el {user-id} parámetro . En el ejemplo anterior, se usa el $context.Account valor . Este valor contiene el nombre principal de usuario (UPN) del usuario autenticado.
Solicitud de propiedades específicas
La función usa el -Select parámetro en el comando para especificar el conjunto de propiedades que necesita. Esto agrega el parámetro de consulta $select a la llamada API.
Tipo de valor devuelto fuertemente tipado
La función devuelve un MicrosoftGraphUser objeto deserializado a partir de la respuesta JSON de la API. Dado que el comando usa -Select, solo las propiedades solicitadas tendrán valores en el objeto devuelto. Todas las demás propiedades tendrán valores predeterminados.
Bandeja de entrada de lista
En esta sección enumerará los mensajes en la bandeja de entrada de correo electrónico del usuario.
En la sesión de PowerShell autenticada, compruebe que la
$uservariable está establecida.PS > $user.DisplayName Megan BowenEjecute el siguiente comando para mostrar la bandeja de entrada del usuario.
Get-MgUserMailFolderMessage -UserId $user.Id -MailFolderId Inbox -Select ` "from,isRead,receivedDateTime,subject" -OrderBy "receivedDateTime DESC" ` -Top 25 | Format-Table Subject,@{n='From';e={$_.From.EmailAddress.Name}}, ` IsRead,ReceivedDateTimeRevise la salida.
Subject From IsRead ReceivedDateTime ------- ---- ------ ---------------- Updates from Ask HR and other communities Contoso Demo on Yammer False 4/19/2022 10:19:02 PM Employee Initiative Thoughts Patti Fernandez False 4/19/2022 3:15:56 PM Voice Mail (11 seconds) Alex Wilber False 4/18/2022 2:24:16 PM Our Spring Blog Update Alex Wilber True 4/18/2022 1:52:03 PM Atlanta Flight Reservation Alex Wilber False 4/13/2022 2:30:27 AM Atlanta Trip Itinerary - down time Alex Wilber False 4/12/2022 4:46:01 PM
Código explicado
Considere el comando usado para enumerar la bandeja de entrada del usuario.
Acceso a carpetas de correo conocidas
El Get-MgUserMailFolderMessage comando compila una solicitud a la API List messages , específicamente mediante el punto de GET /users/{user-id}/mailFolders/{folder-id}/messages conexión. Con ese punto de conexión, la API solo devuelve 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: -MailFolderId Inbox. 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 del Get-MgUser comando 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 el SDK de PowerShell de Microsoft Graph, esto se logra con el -Top 25 parámetro .
Nota:
El valor pasado a través -Top de es un límite superior, no un número explícito. La API devuelve una serie de mensajes hasta el valor especificado.
Ordenar colecciones
La función usa el -OrderBy parámetro en la solicitud 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. Esto agrega el parámetro de consulta $orderby a la llamada API.
Enviar correo
En esta sección, enviará un mensaje de correo electrónico como usuario autenticado.
En la sesión de PowerShell autenticada, compruebe que la
$uservariable está establecida.PS > $user.DisplayName Megan BowenUse el siguiente comando para definir un objeto que represente el cuerpo de la solicitud para Send mail API.
$sendMailParams = @{ Message = @{ Subject = "Testing Microsoft Graph" Body = @{ ContentType = "text" Content = "Hello world!" } ToRecipients = @( @{ EmailAddress = @{ Address = ($user.Mail ?? $user.UserPrincipalName) } } ) } }Use el siguiente comando para enviar el mensaje.
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParamsNota:
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.
Para comprobar que se ha recibido el mensaje, repita el
Get-MgUserMailFolderMessagecomando del paso anterior.
Código explicado
Tenga en cuenta los comandos usados para enviar un mensaje.
Envío de correo
El Send-MgUserMail comando 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 el SDK, cree un objeto que represente el cuerpo de la solicitud, establezca las propiedades deseadas y, a continuación, pásela en el BodyParameter parámetro .
Opcional: agregue su propio código
En esta sección usará sus propios comandos del SDK de PowerShell de Microsoft Graph. 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.
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, personalizar una solicitud de API en el Explorador de Graph y usar el fragmento de código generado o usar el Find-MgGraphCommand comando para buscar el comando correspondiente.
Por ejemplo, uno de los puntos de conexión de API para crear un evento es POST /users/{id | userPrincipalName}/events. Puede usarlo para buscar el comando de PowerShell correspondiente.
PS > Find-MgGraphCommand -Uri "/users/{id | userPrincipalName}/events" -Method "POST"
APIVersion: v1.0
Command Module Method URI OutputType Permissions Variants
------- ------ ------ --- ---------- ----------- --------
New-MgUserEvent Calendar POST /users/{user-id}/events IMicrosoftGraphEvent {Calendars.ReadWrite} {Create1, CreateExp…
APIVersion: beta
Command Module Method URI OutputType Permissions Variants
------- ------ ------ --- ---------- ----------- --------
New-MgUserEvent Calendar POST /users/{user-id}/events IMicrosoftGraphEvent1 {Calendars.ReadWrite} {Create, CreateExp…
La salida indica que el New-MgUserEvent comando es el comando correspondiente.
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 la autenticación de usuario (delegado) ni las cuentas personales de Microsoft, por ejemplo.
Desconecte la sesión actual (Disconnect-MgGraph) y vuelva a conectarse con el permiso necesario en el -Scopes parámetro .
Sugerencia
El uso del -ForceRefresh parámetro con el Connect-MgGraph comando garantiza que se apliquen los permisos recién configurados.
Ejecución del comando
Ahora que está conectado con los permisos necesarios, ejecute el comando elegido.
¡Enhorabuena!
Ha completado el tutorial de Microsoft Graph de PowerShell. 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 PowerShell de Microsoft Graph.
- Visite información general de Microsoft Graph para ver todos los datos a los que puede acceder con Microsoft Graph.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.