Microsoft Graph PowerShell para administradores de SharePoint: primeros comandos
Por Mirko Peters · · Actualizado
Microsoft Graph PowerShell para SharePoint: instala el SDK, inicia sesión con el ámbito adecuado, enumera sitios con Get-MgSite y soluciona los errores 403 con los que los administradores se topan primero.
Traducido automáticamente con IA a partir de la publicación original. Lee el original en inglés
Microsoft Graph PowerShell para SharePoint significa usar el SDK de Graph para leer y administrar sitios desde la línea de comandos. Instalas un único módulo, inicias sesión con Connect-MgGraph y un ámbito de permisos, y ejecutas cmdlets como Get-MgSite. Esta guía está dirigida a administradores de SharePoint que ya conocen el centro de administración de SharePoint y quieren un primer camino seguro hacia la automatización con scripts. Instalarás el SDK, iniciarás sesión con el ámbito mínimo que funcione, enumerarás sitios y aprenderás a interpretar los errores que aparecen primero.
Puntos clave
- Microsoft Graph PowerShell es un SDK que envuelve las API de Graph, así que cada comando requiere antes un inicio de sesión con Connect-MgGraph y los ámbitos de permiso adecuados.
- Get-MgSite enumera los sitios de SharePoint y necesita como mínimo el permiso Sites.Read.All, que es la opción de menor privilegio que Microsoft documenta para este comando.
- Get-MgContext muestra qué ámbitos tiene tu sesión actual, que es la forma más rápida de explicar un error 403 Forbidden.
- Find-MgGraphCommand y Find-MgGraphPermission te indican qué permiso necesita un comando, así que no tienes que adivinar los nombres de los ámbitos.
- El inicio de sesión delegado se adapta a una persona frente al teclado, mientras que el inicio de sesión solo de aplicación con un certificado o una identidad administrada se adapta a trabajos desatendidos.
Qué es Microsoft Graph PowerShell y por qué lo usan los administradores
Microsoft Graph es la API única para los datos de Microsoft 365: usuarios, grupos, archivos, correo, Teams y sitios de SharePoint. El SDK de Microsoft Graph PowerShell envuelve la API de Graph en cmdlets. No tienes que escribir solicitudes web a cada endpoint. Ejecutas Get-MgSite y obtienes objetos de sitio como resultado.
Para un administrador de SharePoint, esto aporta tres ventajas prácticas.
- Una herramienta para varios servicios. El mismo inicio de sesión sirve para sitios, usuarios y grupos. Un script puede enumerar sitios y, después, consultar sus propietarios.
- Un modelo de permisos que puedes leer. Cada llamada necesita permisos concretos, llamados ámbitos. Puedes ver qué ámbitos tiene una sesión y por qué se rechazó una llamada.
- Una vía para dejar atrás los módulos antiguos. Las notas de entidad de Microsoft Graph PowerShell lo describen como el reemplazo de los módulos retirados de Azure AD PowerShell y MSOnline.
El módulo comunitario PnP PowerShell es la otra opción habitual para scripts de SharePoint, y su documentación indica que algunos cmdlets también se comunican con Graph. Graph PowerShell no sustituye a todas las herramientas de administración de SharePoint. Cubre lo que expone la API de Graph. Algunas opciones del inquilino siguen estando en el centro de administración de SharePoint o en otros módulos. Considera Graph como una herramienta más de tu conjunto, no como la única.
Paso 1: instala el SDK e inicia sesión
La guía de instalación recomienda PowerShell 7 o posterior en todas las plataformas. Windows PowerShell necesita la versión 5.1 o posterior, .NET Framework 4.7.2 o posterior y una directiva de ejecución de RemoteSigned o menos restrictiva.
Sigue estos pasos:
- Instala el módulo para tu propia cuenta:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Usa-Scope AllUserssolo si tienes derechos de administrador y necesitas una instalación compartida. - Comprueba el resultado con
Get-InstalledModule Microsoft.Graph. - Ten en cuenta que el módulo principal instala más de 47 submódulos. La página indica que puedes instalar solo los que necesites y que
Microsoft.Graph.Authenticationse incluye con ellos. - Más adelante, actualízalo con
Update-Module Microsoft.Graph. Un módulo desactualizado figura como una de las causas conocidas de conflictos de versión.
Instalarlo en una versión de PowerShell no lo instala en la otra, así que ejecuta el comando en la versión que vayas a usar.
Ahora, inicia sesión. La página sobre comandos de autenticación explica que el SDK admite dos tipos de acceso: delegado y solo aplicación. El acceso delegado actúa en nombre de un usuario que ha iniciado sesión, y sus permisos son ámbitos. El acceso solo aplicación se ejecuta sin usuario, con un certificado, un secreto de cliente o una identidad administrada.
Para tus primeros comandos, usa el acceso delegado y solicita un único ámbito de solo lectura:
Connect-MgGraph -Scopes "Sites.Read.All"
Se abrirá una ventana del navegador para iniciar sesión. Para comprobar qué has obtenido, ejecuta Get-MgContext | Select -ExpandProperty Scopes. Microsoft documenta Get-MgContext como el comando que devuelve los detalles de tu sesión actual, como el identificador de cliente, el identificador de inquilino, los ámbitos y el tipo de autenticación. Cuando termines, ejecuta Disconnect-MgGraph. La página indica que seguirás con la sesión iniciada hasta que lo hagas, porque los tokens se almacenan en caché con el ámbito predeterminado CurrentUser. Añade -ContextScope Process a Connect-MgGraph si quieres que el inicio de sesión dure solo mientras dure la sesión actual.
Primeros comandos para sitios de SharePoint
La referencia de Get-MgSite enumera los parámetros principales: -Filter, -Search, -Property (alias -Select), -Top, -Sort y -All. Los ejemplos de la propia página son breves:
Get-MgSiteenumera los sitios.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"devuelve solo las colecciones de sitios raíz, con dos propiedades.
A partir de ahí, puedes ir ampliando:
- Listar con paginación. Ejecuta
Get-MgSite -Allpara recorrer todas las páginas de resultados. Sin-All, es posible que solo veas la primera página. - Elige las columnas. Añade
-Property "id,displayName,webUrl"para que la salida sea más breve y fácil de leer. - Busca por palabra clave. Ejecuta
Get-MgSite -Search "finance". La API de búsqueda de Graph busca texto libre en varias propiedades del sitio. - Obtén un sitio concreto. Ejecuta
Get-MgSite -SiteId <id>, donde el identificador es el valor deidde un resultado anterior. Tiene la forma de un nombre de host, seguido de dos GUID, separados por comas.
Cada uno de estos cmdlets se corresponde con una llamada REST. Get-MgSite -All lee la colección de sitios en https://graph.microsoft.com/v1.0/sites, la URL que la documentación REST muestra para listar sitios, y -Filter, -Search y -Property se convierten en opciones de consulta de esa URL. El SDK obtiene sus tokens a través de la Biblioteca de autenticación de Microsoft (MSAL). Si falta un cmdlet para una llamada que necesitas, Invoke-MgGraphRequest puede llamar directamente a un URI. La página de solución de problemas lo usa para comprobar el URI que hay detrás de un error «Bad request».
Hay dos límites importantes. En primer lugar, el endpoint de lista de Graph devuelve los sitios de la geografía predeterminada de la organización. Para todas las geografías, Microsoft remite a la API getAllSites, que corresponde al cmdlet Get-MgAllSite. En segundo lugar, la API de búsqueda solo puede ordenar por createdDateTime.
¿Qué permisos necesitas? Ámbitos de Microsoft Graph PowerShell y de SharePoint
Los permisos de Microsoft Graph son la parte que sorprende a los usuarios nuevos. Para leer sitios, la página del cmdlet indica Sites.Read.All como la opción de menos privilegios y Sites.ReadWrite.All como la de más privilegios. Elige la primera, a menos que un script deba modificar algo.
No tienes que recordar los nombres de los ámbitos. Dos comandos auxiliares hacen la búsqueda:
Find-MgGraphCommandmuestra qué permisos requiere un cmdlet o una API. La página de solución de problemas usaFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissionscomo ejemplo.Find-MgGraphPermissionbusca permisos por área o por nombre, por ejemploFind-MgGraphPermission application. La salida muestra el tipo (delegado o de aplicación), si el consentimiento lo debe dar un administrador y una descripción.
Hay un punto en el que la documentación no coincide consigo misma. La página REST para listar sitios solo muestra permisos de aplicación para esa llamada y marca el acceso delegado como no compatible. La página del cmdlet Get-MgSite enumera ambos. Prueba tu propia llamada en un inquilino que no sea de producción y lee el texto del error si falla. No des por hecho que la página del cmdlet es correcta para todas las llamadas.
Para los trabajos desatendidos necesitas acceso solo de aplicación. Eso implica un registro de aplicación en Microsoft Entra, permisos de aplicación (también llamados permisos de API) y consentimiento de administrador. La página de solución de problemas indica que los permisos de aplicación requieren consentimiento de administrador. Usa un certificado o una identidad administrada, no una contraseña escrita en el script.
Ejemplo: un inventario de sitios inactivos en cinco comandos
Las cifras de este ejemplo son inventadas.
Un administrador quiere una primera lista de los sitios que nadie ha modificado en el último año.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countdevuelve 480 en este ejemplo.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Supongamos que el archivo tiene 60 filas. Son 60 de 480, es decir, un 12,5 %, una lista breve para revisar con los propietarios de los sitios. El administrador solo tiene acceso de lectura y no ha cambiado nada. La fecha de última modificación de un sitio no demuestra que nadie lo use, así que la lista es un punto de partida para hacer preguntas, no una lista de eliminación.
Errores comunes
- Conectarse sin ámbito. Un inicio de sesión sin el ámbito adecuado provoca errores 403. Ejecuta
Get-MgContexty compara los ámbitos con los que necesita el cmdlet. - Pedir ámbitos de escritura para una tarea de lectura.
Sites.ReadWrite.Alles más de lo que necesita un informe. Empieza conSites.Read.All. - Olvidar
-All. Sin este parámetro, una lista puede parecer completa cuando solo es la primera página. - Mezclar las versiones del módulo. Microsoft recomienda el módulo v1.0 para los scripts. El módulo beta está en vista previa y puede cambiar sin previo aviso.
- Omitir la actualización. Una versión antigua de
Microsoft.Graphfigura como causa conocida de conflictos de versión. EjecutaUpdate-Module Microsoft.Graphantes de buscar otras causas. - Mantener la sesión iniciada en un equipo compartido. Los tokens se almacenan en caché. Ejecuta
Disconnect-MgGraphcuando termines.
Cómo puede ayudar el software
La mayoría de las necesidades iniciales se cubren con herramientas que ya tienes. El SDK de Microsoft Graph PowerShell se encarga de las lecturas y las exportaciones. El centro de administración de SharePoint muestra las listas de sitios y su configuración sin código. Excel o Power BI convierten un CSV en un informe que los propietarios de los sitios pueden leer. Para las ejecuciones programadas, Azure Automation puede ejecutar un script con una identidad administrada.
Busca carencias solo después del primer mes. Si sigues reconstruyendo el mismo inventario a mano, normalmente basta con un script guardado con una carpeta de salida fija y un recordatorio mensual.
Siguiente paso
Instala el SDK, ejecuta Connect-MgGraph -Scopes "Sites.Read.All" y exporta hoy mismo a CSV la salida de Get-MgSite -All. Después, usa Find-MgGraphCommand con tu próximo cmdlet para conocer su permiso antes de ejecutar tareas de Microsoft Graph PowerShell para SharePoint en producción.