Cómo utilizar Invoke-MgGraphRequest con PowerShell
Invoke-MgGraphRequest es un cmdlet versátil que le permite realizar casi cualquier llamada a la API de Microsoft Graph sin la necesidad de cmdlets o módulos de Microsoft Graph adicionales. Esto es útil ya que es posible que no desee depender de otros módulos de Microsoft Graph PowerShell pero aun así desee utilizar el módulo de Autenticación para simplificar.
En este tutorial, le mostraré cómo usar el cmdlet Invoke-MgGraphRequest en el SDK de Microsoft Graph PowerShell para realizar solicitudes de API REST a Microsoft Graph para que pueda ver, editar y crear recursos en Microsoft 365 y Azure.
Cómo funciona Invoke-MgGraphRequest
El cmdlet Invoke-MgGraphRequest funciona realizando solicitudes de API REST a Microsoft Graph, lo que puede hacer especificando la ruta del URI REST, el cuerpo de la solicitud y los parámetros del método de solicitud en su comando.
Idealmente, cuando trabaja con Microsoft Graph PowerShell, puede tener un mejor control y aplicar una mejor lógica al usar cmdlets equivalentes para crear, eliminar y actualizar recursos. Sin embargo, no todas las tareas tienen todavía un cmdlet relevante, por lo que usar el cmdlet Invoke-MgGraphRequest es especialmente útil para crear recursos que no tienen cmdlets compatibles.
A continuación se muestra un desglose completo de los parámetros que puede utilizar con Invoke-MgGraphRequest:
Invoke-MgGraphRequest [[-Method] {GET | POST | PUT | PATCH | DELETE}]
[-Uri] <uri>
[[-Body] <Object>]
[[-Headers] <IDictionary>]
[[-OutputFilePath] <string>]
[[-InferOutputFileName]]
[[-InputFilePath] <string>]
[[-PassThru]] [[-Token] <securestring>]
[[-SkipHeaderValidation]]
[[-ContentType] <string>]
[[-Authentication] {Default | UserProvidedToken}]
[[-SessionVariable] <string>]
[[-ResponseHeadersVariable] <string>]
[[-StatusCodeVariable] <string>]
[[-SkipHttpErrorCheck]]
[[-GraphRequestSession] <GraphRequestSession>]
[[-UserAgent] <string>]
[[-OutputType] {HashTable | PSObject | HttpResponseMessage | Json}]
[-Break] [<CommonParameters>]¿Qué es un URI DE RESTO?
La primera información que debe especificar en su comando cuando utiliza el cmdlet Invoke-MgGraphRequest es la ruta del URI REST. El URI (o identificador universal de recursos) identifica dónde se puede encontrar un recurso específico, en nuestro caso, en la API de Microsoft Graph.
Examinemos cómo se compone una ruta de URI REST. Por ejemplo, la ruta URI restante para un dispositivo específico registrado con Microsoft Entra ID sería https://graph.microsoft.com/v1.0/devices/{id}. Para desglosar eso:
https://graph.microsoft.com/v1.0/dispositivos/{id}
https://graph.microsoft.com: este es el nombre de host (o punto final) del servicio Microsoft Graph.
v1.0/ : esta es la versión del perfil de Microsoft Graph.
devices/ : es la ruta al recurso.
{id}: esta es la identificación única del recurso.
Cómo encontrar el URI REST requerido
Siempre que realice una solicitud a Microsoft Graph, deberá especificar la ruta del URI. Con eso, por supuesto, necesita conocer la ruta al recurso que desea cambiar. Esta es una de las complejidades añadidas cuando no se utiliza uno de los cmdlets dedicados.
Existen varios métodos que puede utilizar para identificar la ruta al recurso específico que necesita.
La opción 1 es utilizar el sitio Microsoft Graph Explorer. Puede acceder a Graph Explorer en: https://developer.microsoft.com/en-us/graph/graph-explorer
Comience buscando el recurso que desee bajo el encabezado de recurso, luego seleccione su recurso de la lista. Verá aparecer el URI en el cuadro de texto resaltado a continuación.
La Opción 2 es mi método preferido. Puede utilizar herramientas de desarrollo (o la función "Inspeccionar") en su navegador web para ver el encabezado de la solicitud al crear un recurso. Entonces digamos que desea cambiar la categoría de un dispositivo en Intune. Comience abriendo las propiedades del dispositivo, luego cambie la información que necesita. Pero antes de hacer clic en guardar, haga clic derecho en la página y haga clic en Inspeccionar.
Ahora seleccione la pestaña Red como la que he resaltado a continuación:
Una vez que haya seleccionado la pestaña de red, puede regresar y hacer clic en Guardar en la página de propiedades del dispositivo. En la pestaña de red, ahora verá que aparecen solicitudes debajo del encabezado Nombre.
Seleccione la solicitud de la lista que coincida con la acción que ha realizado; los nombres a menudo serán más significativos que los siguientes:
Ahora puede ver la ruta URI completa que coincide con la acción que desea realizar en las pestañas de encabezados a la derecha. Aunque ya realizó la acción en el portal, puede utilizar esta nueva información para aplicar este cambio mediante programación en el futuro o en varios dispositivos a la vez. El resultado completo de lo anterior se encuentra a continuación:
https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$refAdemás, tome nota del método de solicitud (en este caso, PUT), ya que lo usaremos más adelante cuando construyamos nuestra solicitud.
Cómo crear un cuerpo de solicitud
El cuerpo de la solicitud, también conocido como carga útil, son los datos que se envían a Microsoft Graph (el punto final de la API) que contiene toda la información sobre la solicitud. El cuerpo de la solicitud se envía a Microsoft Graph en formato JSON; este formato lo utilizan ampliamente los clientes API y normalmente contendrá información para crear o actualizar un recurso existente.
Echemos un vistazo a un cuerpo de ejemplo de nuestro ejemplo anterior en la opción 2. Arriba cambiamos la categoría de un dispositivo en Intune y analizamos los encabezados de solicitud usando la herramienta de inspección en nuestro navegador. Para obtener el cuerpo de la solicitud, haremos lo mismo.
Siga el mismo proceso que el anterior en la opción 2 para ver la solicitud; sin embargo, esta vez seleccione la pestaña Carga útil y luego ver fuente.
Ahora verá la carga útil de la solicitud en su formato JSON sin formato:
Luego podemos pegar este código en Microsoft Graph Explorer o en un IDE de su elección para formatearlo correctamente. Hay varias herramientas en línea disponibles que formatearán automáticamente su código JSON para mejorar su legibilidad.
{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}Probando nuestro URI y carga útil
Antes de comenzar el desarrollo de cualquier script, sería una buena idea probar nuestro URI y nuestra carga útil para asegurarnos de que funcione como se espera. Le recomiendo que haga esto utilizando la herramienta web Microsoft Graph Explorer proporcionada por Microsoft.
Siga los pasos a continuación para realizar la prueba: (Usaré el URI de ejemplo y la carga útil que usamos anteriormente)
1. Comience iniciando sesión en Microsoft Graph Explorer yendo aquí y seleccionando el ícono de perfil en la parte superior derecha.
2. Una vez que haya iniciado sesión, pegue el URI en el cuadro de texto de la URL (a la izquierda del botón "Ejecutar consulta") y luego pegue la carga útil en el cuerpo de la solicitud, de la siguiente manera:
3. Antes de ejecutar su consulta, asegúrese de regresar al portal para revertir el cambio que realizó originalmente para recopilar la información requerida. Una vez que ejecutamos la solicitud en la herramienta Graph Explorer, podemos verificar que se haya actualizado nuevamente en el portal para confirmar que la solicitud funciona.
4. Por último, cambie el método de solicitud a PUT y haga clic en Ejecutar consulta. En el caso de esta solicitud fue exitosa, sin embargo, la respuesta quedó en blanco. Pero si revisamos las propiedades del dispositivo desde el portal de Intune, se actualizaron como se esperaba.
Cómo encontrar los permisos necesarios usando Graph Explorer
Una cosa que no puede obtener al extraer el encabezado de la solicitud y la carga útil de su solicitud utilizando la herramienta de inspección son los permisos necesarios para realizar la acción que desea.
Hay un par de formas convenientes de identificar qué permisos se requieren...
La opción más sencilla es utilizar la pestaña Modificar permisos de Microsoft Graph Explorer que le indicará exactamente qué permisos se requieren para ejecutar su consulta. En el caso de mi carga útil de prueba, puede ver a continuación qué permisos fueron necesarios.
Otra opción es utilizar el cmdlet Find-MgGraphPermission que enumerará todos los permisos disponibles para Microsoft Graph.
La ejecución del cmdlet por sí sola generará mucha información y, para comprender cada permiso, deberá leer la descripción. Para limitar esto, puede filtrar sus resultados.
Find-MgGraphPermission | Where-Object {$_.Name -match "Device"}Sus resultados se verán como los siguientes:
Construyendo nuestro script usando el cmdlet Invoke-MgGraphRequest
Si ha seguido los pasos anteriores, ahora debería tener (o saber cómo obtener) toda la información que necesitamos para crear nuestro script de PowerShell para que podamos implementar o modificar nuestros recursos mediante programación. Nuevamente usaré el mismo ejemplo que probamos anteriormente en Graph Explorer.
Aquí está nuestro script de ejemplo completo: (siga desplazándose para ver el desglose).
#Connect to Microsoft Graph
Connect-MgGraph -Scopes DeviceManagementManagedDevices.ReadWrite.All
#Define the URI
$uri = @'
https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$ref
'@
#Define policy parameters
$json = @'
{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}
'@
#Create policy
Invoke-MgGraphRequest -Uri $uri -Body $json -Method PUT -ContentType "application/json"Para desglosar el guión y que se entienda, intentaré explicar cada apartado.
En primer lugar, me conectaré a Microsoft Graph utilizando la menor cantidad de permisos necesarios para ejecutar nuestras tareas.
Connect-MgGraph -Scopes DeviceManagementManagedDevices.ReadWrite.All
Aquí estoy almacenando la ruta URI en la variable $uri. Observe cómo estoy usando @’ y ‘@ alrededor de mi URI, estos se denominan ‘Here Strings’. Aquí se utilizan cadenas para garantizar que el texto entre ellas se tome literalmente. Sin las 'Cadenas Here', el $ref al final del URI se tomaría como una variable vacía.
$uri = @'
https://graph.microsoft.com/beta/deviceManagement/managedDevices('956a2c3b-bd8d-4339-9f26-3d1b034748f6')/deviceCategory/$ref
'@
Hemos hecho algo similar a lo anterior con nuestra carga útil JSON:
$json = @'
{
"@odata.id":"https://graph.microsoft.com/beta/deviceManagement/deviceCategories/3725a237-e0e4-4b0b-aab0-3868e12c8ba9"
}
'@Por último, ejecutaremos nuestro comando y haremos el cambio:
Invoke-MgGraphRequest -Uri $uri -Body $json -Method PUT -ContentType "application/json"Cómo utilizar los diferentes métodos; OBTENER, PUBLICAR, PONER, PARCHEAR, BORRAR
Hay 5 métodos diferentes para recuperar y enviar datos a Microsoft Graph; desglosaré lo que significa cada uno de ellos a continuación.
El método OBTENER
El uso de GET recuperará datos del servidor sobre recursos específicos o múltiples según el URI que especifique. Hay poco riesgo al utilizar el método GET ya que no se realizan cambios. Por ejemplo, si queremos ver todas las políticas de acceso condicional en nuestro inquilino, podemos usar lo siguiente:
#Define the URI
$uri = "https://graph.microsoft.com/beta/policies/conditionalAccessPolicies"
#Create policy
$policies = Invoke-MgGraphRequest -Uri $uri -Method GET
#Expand values
$policies.Values.values
El método POST
Las solicitudes POST se utilizan para crear nuevos recursos; por ejemplo, si desea crear una nueva política de cumplimiento en Microsoft Intune, puede utilizar el siguiente ejemplo:
$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies"
$json = @'
{
"id":"00000000-0000-0000-0000-000000000000",
"displayName":"Temp1",
"roleScopeTagIds":["0"],
"@odata.type":"#microsoft.graph.windows10CompliancePolicy",
"scheduledActionsForRule":[
{
"ruleName":"PasswordRequired",
"scheduledActionConfigurations":[
{
"actionType":"block",
"gracePeriodHours":0,
"notificationTemplateId":"",
"notificationMessageCCList":[]
}]
}],
"deviceThreatProtectionRequiredSecurityLevel":"unavailable",
"passwordRequiredType":"deviceDefault",
"bitLockerEnabled":true,
"deviceThreatProtectionEnabled":false
}
'@
Invoke-MgGraphRequest -uri $uri -body $json -method POST -ContentType "application/json"El método PUT
Las solicitudes PUT sirven para actualizar recursos; por ejemplo, si desea cambiar una propiedad en un dispositivo en Intune, usaría una solicitud PUT. Desplácese hacia arriba para revisar el ejemplo que di al crear nuestro script usando Invoke-MgGraphRequest.
El método PARCHE
El método PATCH es similar a PUT pero solo aplicará actualizaciones específicas a los recursos. Por ejemplo, si queremos actualizar las políticas de cumplimiento que creamos con el método POST, podemos usar el siguiente script:
$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies/f048f8f0-5370-4ea6-979b-5dabc4f5329c"
$json = @'
{
"id":"f048f8f0-5370-4ea6-979b-5dabc4f5329c",
"displayName":"Temp1",
"description":null,
"roleScopeTagIds":["0"],
"@odata.type":"#microsoft.graph.windows10CompliancePolicy",
"bitLockerEnabled":true,
"codeIntegrityEnabled":true,
"tpmRequired":false,"validOperatingSystemBuildRanges":[],
"[email ":"https://graph.microsoft.com/beta/$metadata#deviceManagement/deviceCompliancePolicies('f048f8f0-5370-4ea6-979b-5dabc4f5329c')/microsoft.graph.windows10CompliancePolicy/assignments",
"[email ":"https://graph.microsoft.com/beta/$metadata#deviceManagement/deviceCompliancePolicies('f048f8f0-5370-4ea6-979b-5dabc4f5329c')/microsoft.graph.windows10CompliancePolicy/scheduledActionsForRule(scheduledActionConfigurations())"
}
'@
Invoke-MgGraphRequest -uri $uri -body $json -method PATCH -ContentType "application/json"El método BORRAR
El método DELETE, como habrás adivinado, te permite eliminar recursos específicos. Por ejemplo, podemos usar los siguientes comandos para eliminar la política de cumplimiento que creamos y modificamos anteriormente:
$uri = "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies/a7be0c3d-dd89-49c7-a464-f371e72b30d7"
Invoke-MgGraphRequest -uri $uri -method DELETE