Búsqueda de sitios web

¿Cómo conectarse a la API de Microsoft Graph desde PowerShell?

Introducción

Microsoft Graph API es una API web RESTful que consolida el acceso a varios servicios de Microsoft 365, lo que permite a los desarrolladores crear aplicaciones que interactúan con datos en múltiples plataformas, incluidas Azure Active Directory, SharePoint, OneDrive, Outlook y más. Microsoft Graph PowerShell funciona en todas las plataformas, incluidas Windows, macOS y Linux. Admite autenticación moderna. PowerShell, un lenguaje de programación y una herramienta de automatización ampliamente utilizado, se puede utilizar para conectarse e interactuar con Graph API, lo que la convierte en una habilidad esencial para los profesionales de TI. En esta guía para principiantes, brindaremos una descripción general completa de Graph API, analizaremos los requisitos previos para conectarse a ella, la instalación y configuración, la autenticación y una guía paso a paso para conectarse a Graph API usando PowerShell, brindando ejemplos. y explicaciones a lo largo del camino.

Instalación del módulo Microsoft.Graph PowerShell

Para comenzar, deberá instalar el módulo Microsoft Graph PowerShell. Este módulo proporciona un conjunto de cmdlets que le permiten interactuar con Graph API. Ejecute el siguiente comando en una sesión de PowerShell elevada:

Compruebe si el módulo Microsoft Graph PowerShell ya está instalado, utilizando este comando de PowerShell:


Get-InstalledModule | Where-Object {$_.Name -match "Microsoft.Graph"}

Instale el módulo Microsoft Graph PowerShell:


Install-Module -Name "Microsoft.Graph"

Para instalar el SDK de PowerShell de Microsoft Graph para el ámbito de usuario actual:


Install-Module Microsoft.Graph -Scope CurrentUser

Esto instala Microsoft Graph y sus submódulos (38 a la fecha). Espere a que se complete la instalación.

Actualizar el módulo Microsoft Graph PowerShell

Para actualizar el módulo existente, utilice lo siguiente:


Update-Module Microsoft.Graph

Desinstalar el módulo Microsoft Graph PowerShell

Microsoft Graph tiene un módulo principal y varios submódulos. Para desinstalar el módulo Graph, primero debemos desinstalar el módulo principal:


Uninstall-Module Microsoft.Graph

Y luego desinstale todos los submódulos de Microsoft Graph. El módulo de Autenticación debe ser desinstalado al final, ya que otros módulos dependen de él.


#Uninstall all Sub-modules of Graph
Get-InstalledModule Microsoft.Graph.* | ForEach-Object { if($_.Name -ne "Microsoft.Graph.Authentication") {
    Uninstall-Module $_.Name } 
}

#Uninstall the dependant module
Uninstall-Module Microsoft.Graph.Authentication

¿Cómo utilizar PowerShell para llamar a Graph API?

Con el módulo Microsoft.Graph instalado, puede comenzar a usar Graph API para realizar diversas tareas. Admite acceso delegado, donde los usuarios pueden iniciar sesión y dar su consentimiento, y acceso solo a aplicaciones para escenarios desatendidos. Utilice el comando Connect-MgGraph para iniciar sesión con los ámbitos necesarios. Una vez conectado, puede llamar a cualquier método Graph API disponible.

Método 1: conectarse a Graph API con acceso delegado desde PowerShell

Utilizará el acceso delegado para iniciar sesión como usuario, otorgar consentimiento a los ámbitos necesarios para que el SDK actúe en su nombre y llamar a Microsoft Graph. A continuación se muestra un ejemplo de cómo obtener información del usuario mediante PowerShell:


#Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read.All"

#Get All users
$users = Get-MgUser
$users | Select-Object DisplayName, UserPrincipalName, Mail

Esto solicitará autenticación y deberá iniciar sesión con una cuenta de administrador para dar su consentimiento a los ámbitos requeridos.

Una vez conectado, el comando indica éxito con un mensaje ¡Bienvenido a Microsoft Graph!. Y el comando Get-MgUser genera una lista de usuarios en su organización de Microsoft 365.

Si desea conectarse a la versión Beta de Graph API, utilice el cmdlet Select-MgProfile -Name "beta". A continuación se muestra otro ejemplo de cómo obtener la fecha y hora del último inicio de sesión del usuario:


#Connect to Microsoft Graph
Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All"

#Set the Graph Profile
Select-MgProfile -Name "beta"

#Properties to Retrieve
$Properties = @(
    'Id','DisplayName','UserPrincipalName','UserType', 'AccountEnabled', 'SignInActivity'    
)

#Get All users along with the properties
$AllUsers = Get-MgUser -All -Property $Properties

$SigninLogs = @()
ForEach ($User in $AllUsers)
{
    $SigninLogs += [PSCustomObject][ordered]@{
            LoginName       = $User.UserPrincipalName
            DisplayName     = $User.DisplayName
            UserType        = $User.UserType
            AccountEnabled  = $User.AccountEnabled
            LastSignIn      = $User.SignInActivity.LastSignInDateTime
    }
}

$SigninLogs

#Disconnect MS Graph
Disconnect-MgGraph

De manera similar, para conectarse a un sitio de SharePoint Online con Microsoft Graph API, use este PowerShell:


#Parameters
$SiteID = "0defaa16-1fc5-4a55-bbec-a06d10de2a42"

#Connect to Microsoft Graph
Connect-MgGraph -Scopes "Sites.FullControl.All"

#Get a SharePoint Site collection
$Site = Get-MGSite -SiteId $SiteId

#Get All document libraries from the site
Get-MgSiteDrive -SiteId $SiteId

Ejemplos de uso de la API de Microsoft Graph con PowerShell

Para darle una idea de lo que es posible con Microsoft Graph API y PowerShell. También puede realizar operaciones masivas. Aquí están algunos ejemplos:

  • Para obtener el contexto, utilice: Get-MgContext
  • Recuperando una lista de todos los usuarios en Office 365: Get-MgUser
  • Creando un nuevo sitio de SharePoint: New-MgSite
  • Recuperar una lista de todos los archivos de OneDrive para un usuario específico: Get-MgDriveItem -DriveId -DriveItemId

Como puede ver, las posibilidades son infinitas con Microsoft Graph API y PowerShell.

Encuentre el alcance del permiso requerido para los comandos de gráficos

El usuario que inició sesión o el ID de cliente que usamos para conectarnos a Microsoft Graph debe tener permiso para acceder a un ámbito específico. Por ejemplo, si desea actualizar un perfil de usuario utilizando el comando Update-MgUser, puede hacerlo con el alcance "User.ReadWrite.All". Para encontrar el alcance requerido, use el cmdlet Find-MgGraphCommand. P.ej.,


Find-MgGraphCommand -command Update-MgUser | Select -First 1 -ExpandProperty Permissions

Para obtener todos los cmdlets disponibles en el módulo Microsoft Graph PowerShell, puede utilizar lo siguiente:


Get-command -Module Microsoft.Graph*

¡Hay 9275 cmdlets disponibles en la versión Microsoft Graph 1.25!

Método 2: conectarse a Graph API mediante App ID desde PowerShell

Antes de comenzar, hay algunos requisitos previos que debes cumplir:

  1. Debe registrar una aplicación en Azure AD.
  2. Debe otorgar permiso a la aplicación para acceder a Graph API.
  3. Agregue un certificado o secreto de cliente al ID de la aplicación. El certificado puede ser autofirmado o de una autoridad.

Registrar una aplicación en Azure AD

Antes de conectarse a Graph API con PowerShell, debe registrar una aplicación en Azure AD para obtener los permisos y las credenciales necesarios.

Para registrar una aplicación en Azure AD, siga estos pasos:

  1. Inicie sesión en el portal de Azure AD (https://aad.portal.azure.com/).

  2. Haga clic en “Azure Active Directory” en el menú de la izquierda >> Haga clic en “Registros de aplicaciones” >> Haga clic en “Nuevo registro”.

  3. Ingrese un nombre para su aplicación y seleccione "Cuentas solo en este directorio de organización" como tipo de cuenta admitida.

  4. Haga clic en “Registrarse”.

Después de registrar la aplicación, será redirigido al panel de la aplicación. Tome nota del “ID de la aplicación (cliente)” y del “ID del directorio (inquilino)”, ya que los necesitaremos más adelante.

Otorgar permisos a la aplicación

Para acceder a Graph API, su aplicación debe tener los permisos adecuados. Para otorgar permisos a la aplicación, siga estos pasos:

  1. Haga clic en "Permisos de API" en el menú de la izquierda de la aplicación que creó >> Haga clic en "Agregar un permiso".

  2. Seleccione "Microsoft Graph" como API.

  3. Busque y seleccione los permisos necesarios (por ejemplo, "Sites.FullControl.All" para obtener control total en todos los sitios de SharePoint Online).

  4. Haga clic en "Agregar permisos".

  5. Otorgue su consentimiento para los permisos agregados haciendo clic en "Otorgar consentimiento de administrador para

Para obtener un desglose completo de todos los permisos disponibles que puede especificar al conectarse a Microsoft Graph, consulte la hoja de referencia de permisos de Microsoft: https://learn.microsoft.com/en-us/graph/permissions-reference

Agregar certificado y/o secreto de cliente al AppID

Debe agregar un secreto de cliente (contraseña) o un certificado (¡o ambos!) a la aplicación para conectarse de forma segura a la aplicación. Para agregar un certificado a la aplicación, necesitamos un certificado autofirmado o un certificado SSL estándar de una autoridad.

Agregar certificado a la aplicación

Utilice este script de PowerShell para generar un certificado autofirmado en su carpeta "Documentos". Esto se utilizará para la autenticación basada en certificados.


#Parameters
$CertificateName = "Graph API Cert"
$CertificatePassword = "Password1"
 
#Get the "Documents" folder
$DocumentsFolder = [Environment]::GetFolderPath("MyDocuments")
 
#Generate a Self-signed Certificate
$Certificate = New-SelfSignedCertificate -Subject $CertificateName -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
 
#Export the Certificate to "Documents" Folder in your computer
Export-Certificate -Cert $Certificate -FilePath $DocumentsFolder\$CertificateName.cer
 
#Export the PFX File
Export-PfxCertificate -Cert $Certificate -FilePath "$DocumentsFolder\$CertificateName.pfx" -Password (ConvertTo-SecureString -String $CertificatePassword -Force -AsPlainText)

Este certificado debe instalarse en el "Tienda de confianza" de la máquina donde ejecutará el script.

Sube el Certificado a la App

Una vez que el certificado esté listo, siga estos pasos para agregar un certificado a su aplicación:

  1. Vaya a su aplicación de Azure >> Haga clic en "Certificados y secretos" >> Haga clic en la pestaña "Certificados".
  2. Haga clic en “Subir certificado”.

  3. Busque el archivo CER generado y haga clic en el botón "Agregar".

  4. Tome nota de la "huella digital". Esa es su clave segura asociada con el certificado para autenticarse en la aplicación.

Agregar secreto de cliente a la aplicación

De manera similar, para agregar un secreto de cliente a la aplicación, haga lo siguiente:

  1. Haga clic en “Certificados y secretos” >> Haga clic en la pestaña “Secretos del cliente” y luego en “Nuevo secreto del cliente”.

  2. Establezca la validez de "Descripción" y "Expira". Cuando termine, haga clic en Agregar.

  3. Tome nota del secreto del cliente, que usaremos para conectarnos a Graph API.

Conéctese a Graph API con App ID desde PowerShell usando el certificado

Ahora que hemos registrado una aplicación y le hemos otorgado permisos, y le hemos agregado un secreto de cliente y un certificado. Estamos listos para conectarnos a Graph API desde PowerShell. A continuación se explica cómo conectarse a Microsoft Graph API mediante la huella digital del certificado:


#Parameters for Tenant ID and Client ID
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06" #App ID
$CertThumbPrint = "63FDD807AE01C1EB34CE5647D164E3C153C0FA7"

#Connect to Microsoft Graph using App
Connect-MgGraph -ClientID $ClientID -TenantId $TenantID -CertificateThumbprint $CertThumbPrint

Conéctese a Graph API usando Client Secret

Si desea utilizar el secreto del cliente, aquí tiene el script de PowerShell.


#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9Ad2Q~DA-yLotNvvaplkchnnf__6D5zdFJi1mb4l"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$Token = $Connection.access_token

#Connect to Microsoft Graph 
Connect-MgGraph -AccessToken $Token

Los cmdlets de Microsoft Graph son contenedores de llamadas a la API Rest. También puede llamar al método Invoke-Webrequests para interactuar con cualquier método API REST subyacente.


#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9dd8Q~DA-yLotavvabkchnnf__6c5VdFJi0mb1l"
$Domain = "Crescent"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$AuthHeader = @{
'Authorization'="Bearer $($Connection.access_token)"
}

#Get all sites
$URI = "https://graph.microsoft.com/v1.0/sites"
$WebRequest = Invoke-WebRequest -Headers $AuthHeader -Uri $URI
$Result = ($WebRequest.Content | ConvertFrom-Json).Value

#Get all site collections of the domain
$Result | Where {$_.siteCollection.Hostname -eq "$Domain.sharepoint.com"} | select name,webUrl,id

Explorador de gráficos

Encontrar el método API adecuado para la tarea puede resultar un desafío para los principiantes. Puede utilizar Graph Explore o Rest API Reference como punto de partida.

Errores comunes y consejos para solucionar problemas

Si bien el uso de Azure AD Graph API y Microsoft Graph API con PowerShell es generalmente sencillo, existen algunos errores comunes que puede encontrar. Un error común es "El servidor remoto devolvió un error: (401) No autorizado". También puede obtener "privilegios insuficientes para completar la operación". Por lo general, esto significa que sus credenciales son incorrectas o que no tiene los permisos adecuados para acceder a Graph API. Vuelva a verificar sus credenciales y permisos para asegurarse de que sean correctos.

Otro error común es "El término 'nombre de cmdlet' no se reconoce como el nombre de un cmdlet". Normalmente, esto significa que el módulo de PowerShell adecuado no está instalado ni cargado. Asegúrese de haber instalado y cargado el módulo apropiado para el cmdlet que está intentando utilizar.

Conclusión

En esta guía para principiantes, cubrimos los aspectos básicos de la conexión a la API de Microsoft Graph mediante PowerShell, desde la configuración de su entorno y la autenticación hasta la realización de llamadas a la API. También hemos visto cómo registrar una aplicación en Azure AD, otorgarle permisos y agregar secretos de cliente a la aplicación. Con el conocimiento adquirido en esta guía, puede comenzar a automatizar tareas y administrar su entorno de Microsoft 365 de manera más eficiente.

Los siguientes pasos podrían ser explorar más cmdlets proporcionados por el módulo PowerShell de la API de Microsoft Graph o comenzar a crear sus propios scripts de PowerShell para automatizar tareas comunes. Las posibilidades son infinitas, ¡así que comienza hoy!

Preguntas frecuentes:

¿Cuál es el propósito de Microsoft Graph?

Microsoft Graph API es un punto final de API RESTful unificado que permite a los desarrolladores acceder e interactuar con datos, inteligencia y servicios disponibles en la nube de Microsoft. Actúa como un único punto de entrada para acceder a una amplia variedad de recursos, como usuarios, grupos, correos electrónicos, calendarios, tareas, archivos, dispositivos y más, en múltiples servicios de Microsoft como Office 365, Azure Active Directory, Enterprise Mobility y Seguridad, Windows y más.

¿Cómo instalo Microsoft Graph en PowerShell?

Para instalar el SDK de Microsoft Graph PowerShell, ejecute el siguiente comando en su sesión de PowerShell:

Install-Module -Name Microsoft.Graph

Este comando instala el módulo Microsoft.Graph que proporciona cmdlets para interactuar con la API de Microsoft Graph en PowerShell.

¿Qué permisos se requieren para Microsoft Graph PowerShell?

¡Depende de los puntos finales de API específicos y de los recursos a los que desee acceder! En general, existen dos tipos de permisos en Microsoft Graph:
1. Permisos delegados: para actuar en nombre de los usuarios que han iniciado sesión.
2. Permisos de aplicaciones: estos permisos se otorgan a aplicaciones que se ejecutan sin interacción del usuario, como servicios en segundo plano.
Debe registrar una aplicación en el portal de Azure, asignar permisos a la aplicación, otorgar consentimiento de administrador y luego usar los permisos de la aplicación registrada. credenciales en su script de PowerShell.

¿Por qué deberíamos migrar al SDK de PowerShell de la API de Microsoft Graph?

Porque los módulos AzureAD, MSOnline y AzureADPreview PowerShell están programados para quedar obsoletos. Para estar preparados, los administradores deben comenzar con el nuevo módulo SDK de Microsoft Graph PowerShell.

Artículos relacionados