La automatización de Microsoft 365 que aún depende de Exchange Web Services (EWS) necesita un plan. EWS ha sido el caballo de batalla confiable para la automatización de buzones de correo durante años, pero Microsoft ahora dirige a los desarrolladores y administradores de Exchange Online hacia Microsoft Graph para acceso moderno a correo, calendario, usuarios y grupos.

Si posee un script de PowerShell antiguo, una herramienta de soporte técnico, una integración de calendario o un servicio en segundo plano que se comunique con /EWS/Exchange.asmxeste tutorial lo guiará a través de una ruta práctica de migración. Hará un inventario de lo que hace la carga de trabajo de EWS, asignará cada operación a Microsoft Graph, configurará el SDK de Microsoft Graph PowerShell y probará primero los patrones comunes de buzón y calendario que la mayoría de los equipos necesitan.

Requisitos previos

Para seguirlo, necesitará:

• Un inquilino de Microsoft 365 con Exchange Online.

• Un buzón de prueba que puede consultar.

• PowerShell 7 o Windows PowerShell 5.1.

• Permiso para usar o solicitar permisos de Microsoft Graph en Microsoft Entra ID.

• Familiaridad básica con conceptos de EWS como ExchangeServiceDetección automática, suplantación y nombres de operaciones de EWS.

[!NOTE]

Los ejemplos siguientes son patrones seguros, pero las llamadas Graph que leen datos reales del buzón requieren autenticación y consentimiento del inquilino. Ejecútelos primero en un inquilino de prueba o en un buzón que no sea de producción.

Comprender qué cambia cuando abandona EWS

EWS y Microsoft Graph resuelven problemas empresariales similares, pero lo hacen con formas diferentes.

EWS es una API basada en SOAP que envía XML a través de HTTP/S a Exchange. Las aplicaciones EWS suelen utilizar la API administrada de EWS, ExchangeServicedetección automática, suplantación y nombres de operaciones, como FindItem, GetItem, CreateItemy UpdateItem.

Gráfico de Microsoft es una API REST. En lugar de crear sobres SOAP, llama a recursos como usuarios, mensajes, carpetas de correo y eventos. La autenticación y la autorización se mueven a través de Microsoft Entra ID y OAuth, utilizando permisos delegados o de aplicación.

Ese cambio significa que no se debe tratar la migración como un simple reemplazo de endpoints. Un mejor enfoque es mapear el comportamiento:

Microsoft publica un Referencia de mapeo de API de EWS a Graphy esa página debería formar parte de su libro de migración.

Paso 1: Inventario de cada dependencia de EWS

Comience con el descubrimiento. Antes de reescribir el código, busque todos los lugares en los que su entorno utiliza EWS. Control de fuentes de búsqueda, servidores de tareas programadas, cuentas de automatización, archivos de configuración y configuraciones de integración de proveedores.

Busque marcadores comunes de EWS:

Select-String -Path .\* -Recurse -Pattern \
    'ExchangeService','Microsoft.Exchange.WebServices','EWS/Exchange.asmx','FindItem','GetItem','AutodiscoverUrl'

[!TIP]

Incluya archivos de configuración en la búsqueda, no solo el código fuente. Muchos trabajos heredados almacenan la URL de EWS o la cuenta de servicio en una exportación JSON, XML, INI o tarea programada.

Para cada visita, capture los siguientes detalles en una hoja de cálculo o rastreador de problemas:

Este paso no es glamoroso, pero previene el error común de la migración: reescribir el script visible y omitir la tarea programada que se ejecuta una vez al mes.

Paso 2: elija permisos delegados o de aplicación

Los permisos de gráficos son donde muchas migraciones de EWS se ralentizan. El código de la era EWS a menudo supone que una cuenta de servicio puede llegar a muchos buzones de correo. Graph te hace describir ese acceso a través de permisos y consentimiento del administrador.

Usar permisos delegados cuando la automatización se ejecuta como un usuario que ha iniciado sesión y solo debe hacer lo que ese usuario puede hacer. Este modelo se adapta a herramientas de soporte técnico, scripts interactivos y utilidades de buzón de correo controladas por el usuario.

Usar permisos de aplicaciones cuando un servicio en segundo plano se ejecuta sin un usuario que haya iniciado sesión. Este modelo se adapta a demonios, trabajos nocturnos e integraciones. Los permisos de las aplicaciones son potentes, por lo que no apruebe el acceso amplio para todo el inquilino a menos que la carga de trabajo realmente lo necesite.

Para cargas de trabajo de correo, Microsoft explica que Graph puede acceder al correo de Outlook con la configuración adecuada. permisos delegados o de correo de aplicaciones. Su revisión de seguridad debe responder tres preguntas antes de escribir el código:

1. ¿Qué datos del buzón necesita la aplicación?

2. ¿La aplicación actúa como usuario o como sí misma?

3. ¿Se puede limitar el acceso a un grupo de buzones, un buzón de prueba o una política de acceso a aplicaciones?

[!WARNING]

no conceder Mail.ReadWrite o amplios permisos de aplicación solo para que la primera prueba de concepto funcione. Comience con permisos de solo lectura, pruebe el escenario más pequeño y amplíelo solo cuando la migración lo requiera.

Paso 3: Instale y conecte el SDK de Microsoft Graph PowerShell

El SDK de Microsoft Graph PowerShell es un buen puente para los administradores porque le permite probar el comportamiento de Graph antes de reescribir aplicaciones completas.

Instale el SDK desde el Galería de PowerShell:

Install-Module Microsoft.Graph -Scope CurrentUser

Conéctese con los ámbitos que necesita para una prueba básica de lectura de correo:

Connect-MgGraph -Scopes 'User.Read','Mail.Read','Calendars.Read'

Verifique su contexto después de iniciar sesión:

Get-MgContext | Select-Object Account, TenantId, Scopes

Si su inquilino requiere el consentimiento del administrador para estos ámbitos, el paso de conexión no se completará hasta que un administrador apruebe los permisos.

Paso 4: reescribir una lectura básica de buzón

Muchos scripts de EWS comienzan buscando mensajes recientes. En EWS, eso generalmente significa FindItem contra una carpeta. En Graph PowerShell, comience con Get-MgUserMessage.

$userId = '[email protected]'

Get-MgUserMessage -UserId $userId -Top 10 -Property 'id,subject,receivedDateTime,from' |
    Select-Object Subject, ReceivedDateTime, @{Name="From";Expression={$_.From.EmailAddress.Address}}

La forma REST equivalente es fácil de entender:

“`texto sin formato
OBTENER https://graph.microsoft.com/v1.0/users/[email protected]/mensajes?$top=10&$select=id,asunto,fechahorarecibida,de

Notice two important differences from EWS:

- You request JSON properties with `$select` instead of binding to strongly typed EWS properties.

- The message ID you receive is a Graph resource ID. Do not assume it matches an EWS ID stored in an old database.

## Step 5: Rewrite Calendar Reads

Calendar integrations are another common EWS dependency. Graph exposes calendar and event resources directly.

Use the SDK to list upcoming events:

$ID de usuario = ‘[email protected]’
$inicio = (Obtener-Fecha).ToUniversalTime().ToString(‘o’)
$fin = (Get-Date).AddDays(7).ToUniversalTime().ToString(‘o’)

Get-MgUserCalendarView -UserId $userId -StartDateTime $inicio -EndDateTime $end |
Seleccionar objeto Asunto, Inicio, Fin, Organizador

For REST-based applications, the same idea targets the calendar view endpoint:

```plain text
GET https://graph.microsoft.com/v1.0/users/[email protected]/calendarView?startDateTime=2026-07-05T00:00:00Z&endDateTime=2026-07-12T00:00:00Z

Aquí es donde debes validar las zonas horarias, el comportamiento de recurrencia y los campos del organizador. Es fácil pasar por alto los errores del calendario si solo prueba una reunión sencilla.

Paso 6: Maneje el seguimiento de mensajes y los informes con cuidado

No todas las tareas de administración de Exchange tienen un reemplazo limpio de Graph uno por uno. Por ejemplo, el seguimiento de mensajes y algunos flujos de trabajo de informes a menudo se manejan mejor a través de cmdlets de Exchange Online PowerShell en lugar de puntos finales de correo de Graph.

Si su proceso de la era EWS combina el acceso a elementos del buzón con informes de Exchange, divídalo en dos flujos de trabajo:

• Utilice Microsoft Graph para operaciones de buzón, usuario, grupo y calendario compatibles con Graph.

• Utilice Exchange Online PowerShell para los informes administrativos de Exchange y las tareas relacionadas con el transporte que permanecen en el plano de administración de Exchange.

Esa división mantiene su migración honesta. El objetivo no es forzar todas las tareas de Exchange a través de Graph; el objetivo es eliminar las dependencias de EWS no compatibles sin interrumpir el flujo de trabajo empresarial.

Paso 7: cree una lista de verificación de validación

Antes de la transición, valide la migración con las personas propietarias del proceso, no solo con el código.

Utilice esta lista de verificación:

• Confirme que cada operación de EWS tenga una ruta de reemplazo de Graph, Exchange Online PowerShell o documentada.

• Confirme que los permisos sean de privilegios mínimos y estén aprobados.

• Pruebe con un buzón normal, un buzón compartido y cualquier tipo de buzón especial que admita la carga de trabajo.

• Compare la salida antigua y la nueva para el mismo período de tiempo.

• Pruebe la aceleración y vuelva a intentar el comportamiento.

• Registre los ID de las solicitudes y los errores para que el soporte pueda solucionar los fallos.

• Mantenga el trabajo anterior deshabilitado pero recuperable durante la primera ejecución de producción.

Un simple método de comparación puede ayudar durante las pruebas paralelas:

$userId = '[email protected]'
$outputPath=".\graph-mail-sample.csv"

Get-MgUserMessage -UserId $userId -Top 25 -Property 'subject,receivedDateTime,from' |
    Select-Object Subject, ReceivedDateTime, @{Name="From";Expression={$_.From.EmailAddress.Address}} |
    Export-Csv -Path $outputPath -NoTypeInformation

Write-Host "Graph sample exported to $outputPath"

[!NOTE]

Conserve una muestra exportada del antiguo trabajo de EWS y una muestra exportada del nuevo trabajo de Graph. Pídale al propietario de la empresa que revise los campos, no solo al desarrollador que escribió el script.

Errores comunes de la migración

Evite estas trampas mientras avanza en la migración:

• Suponiendo que los ID de EWS y Graph sean intercambiables. Almacene los nuevos ID de Graph por separado y planifique cualquier migración de búsqueda.

• Saltarse la revisión del consentimiento. Un script funcional con permisos excesivos crea un problema de seguridad.

• Ignorar buzones de correo compartidos. Valide el acceso al buzón compartido con antelación porque expone problemas de diseño de permisos.

• Probando solo mensajes de camino feliz. Incluya archivos adjuntos, reuniones, eventos recurrentes y carpetas grandes.

• Olvidar las dependencias sin código. Las tareas programadas, los conectores de proveedores y los runbooks suelen ocultar las URL de EWS en los archivos de configuración.

Concluyendo

La migración de EWS a Microsoft Graph API es un proyecto manejable cuando lo trata como una migración de flujo de trabajo. Haga un inventario del comportamiento anterior de EWS, asigne cada operación, elija el modelo de permiso correcto y pruebe el reemplazo con Graph PowerShell antes de reescribir el código de producción.

El mayor cambio de mentalidad es pasar de un modelo SOAP de cuenta de servicio a un modelo REST autorizado. Una vez que haga explícito ese cambio, su plan de migración se vuelve más claro: pruebas pequeñas, permisos con privilegios mínimos, validación en paralelo y una transición controlada.

El siguiente paso es elegir un script EWS de bajo riesgo, mapear sus operaciones con la referencia EWS-to-Graph de Microsoft y producir el mismo resultado con Microsoft Graph PowerShell. Una vez que eso funcione, tendrá un patrón repetible para el resto de su patrimonio de EWS.