Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Cuando dev Proxy detecta que la aplicación realiza solicitudes de Microsoft Graph API sin usar un SDK, sugiere la migración a un SDK. Esta guía existe porque los SDK de Microsoft Graph simplifican significativamente el trabajo con las API de Microsoft Graph y le ayudan a crear aplicaciones más sólidas.
Ventajas de los SDK de Microsoft Graph
Los SDK de Microsoft Graph proporcionan numerosas ventajas sobre la realización de llamadas HTTP sin procesar.
Control de autenticación integrada
Los SDK se integran con bibliotecas de autenticación, como la Biblioteca de Autenticación de Microsoft (MSAL), gestionando automáticamente la adquisición, actualización y administración de tokens. No es necesario implementar manualmente el flujo de OAuth 2.0 ni preocuparse por la expiración del token.
Lógica de reintento automático para el control de flujo
Los servicios de Microsoft 365 implementan la limitación para garantizar la confiabilidad del servicio. Cuando la aplicación recibe una 429 Too Many Requests respuesta, el SDK controla automáticamente los reintentos con retrasos de retroceso adecuados, respetando el Retry-After encabezado que devuelve Microsoft Graph.
Control de paginación adecuado
Muchos puntos de conexión de Microsoft Graph devuelven resultados paginados. Los SDKs proporcionan iteradores integrados que manejan de forma transparente la obtención de páginas posteriores, por lo que no es necesario realizar un seguimiento manual de los valores @odata.nextLink y realizar otras solicitudes.
Seguridad de tipos e IntelliSense
Los SDK proporcionan modelos fuertemente tipados para solicitudes y respuestas, lo que proporciona compatibilidad con IntelliSense en el IDE. Los modelos de tipo reducen los errores y aceleran el desarrollo detectando problemas en tiempo de compilación en lugar de en tiempo de ejecución.
Compatibilidad con procesamiento por lotes
Los SDK admiten el procesamiento por lotes de varias solicitudes en una sola llamada HTTP, lo que reduce la sobrecarga de red y mejora el rendimiento. El procesamiento por lotes también le ayuda a mantenerse dentro de los límites al reducir el número de solicitudes individuales.
Consultas delta
Los SDK simplifican la implementación de consultas delta que permiten sincronizar de forma eficaz los cambios de datos desde la última solicitud. El uso de consultas delta es fundamental para crear aplicaciones con capacidad de respuesta que necesitan mantenerse sincronizadas con los datos de Microsoft 365.
Arquitectura de middleware para la personalización
Los SDK usan una canalización de middleware personalizable para agregar registro, modificar encabezados, implementar directivas de reintento personalizadas o insertar otros comportamientos sin cambiar el código de la aplicación.
Patrones de API coherentes
Los SDK proporcionan patrones coherentes en diferentes plataformas e lenguajes, lo que facilita el uso compartido de conocimientos entre los miembros del equipo y entre proyectos.
Qué se pierde en las llamadas HTTP sin procesar.
Al realizar llamadas HTTP directas a Microsoft Graph, debe implementar varias características críticas usted mismo.
Implementación manual de lógica de reintento
Sin un SDK, debe implementar la lógica de reintento para controlar 429 responses, entre las que se incluyen:
- Análisis de los valores del
Retry-Afterencabezado - Implementación de retroceso exponencial
- Control de diferentes escenarios de error
- Evitar tormentas de reintento bajo una carga pesada
Control manual de paginación
Necesitas:
- Comprobar cada respuesta en busca de
@odata.nextLink - Realizar más solicitudes para cada página
- Agregar resultados entre páginas
- Control de errores parciales durante la paginación
Manejo de errores de plantilla
Microsoft Graph puede devolver varias respuestas de error con estructuras diferentes. Sin un SDK, debe hacer lo siguiente:
- Análisis de cuerpos de respuesta de error
- Gestione adecuadamente los diferentes códigos de estado HTTP
- Extracción de mensajes de error significativos para el registro
- Implementar comportamiento de respaldo para errores inesperados
Complejidad de la autenticación
La administración manual de la autenticación requiere:
- Implementación de flujos de OAuth 2.0
- Almacenamiento y protección de tokens
- Gestión de la actualización de tokens antes de su expiración
- Administración de diferentes escenarios de autenticación (delegados frente a permisos de aplicación)
SDK disponibles
Microsoft proporciona SDK oficiales para las siguientes plataformas:
| Plataforma | SDK | Documentación |
|---|---|---|
| .NET | Microsoft.Graph | Documentación del SDK de .NET |
| JavaScript/TypeScript | @microsoft/microsoft-graph-client | Documentación del SDK de JavaScript |
| Java | microsoft-graph | Documentación del SDK de Java |
| Pitón | msgraph-sdk-python | Documentación del SDK de Python |
| Go | msgraph-sdk-go | Documentación del SDK de Go |
| PHP | microsoft-graph | Documentación del SDK de PHP |
| PowerShell | Microsoft.Graph | Documentación del SDK de PowerShell |
Alternativas al uso de un SDK
Aunque se recomiendan SDK para la mayoría de los escenarios, hay casos en los que otros enfoques podrían ser una mejor opción:
Cliente generado por Kiota
Si la aplicación solo usa un pequeño subconjunto de api de Microsoft Graph, considere la posibilidad de generar un cliente con Kiota en lugar de usar el SDK completo. Kiota genera un cliente ligero y fuertemente tipado adaptado a las API específicas que necesita, lo que minimiza tu dependencia, al tiempo que le proporciona seguridad de tipos y construcción de solicitudes.
Uso mínimo de la API
Si está escribiendo un script rápido o una herramienta que realiza solo algunas llamadas API, es posible que la sobrecarga de configurar un SDK no esté justificada. En estos casos, las llamadas HTTP directas pueden ser más sencillas. Sin embargo, todavía necesita controlar la autenticación y las respuestas de error usted mismo, lo que puede agregar rápidamente complejidad incluso para scripts simples.
Idioma no admitido
Si usa un lenguaje de programación que no tiene un SDK oficial, debe realizar llamadas HTTP directas. También puede considerar el uso de Kiota para generar un cliente para su idioma si Kiota lo admite.
Cuando el SDK aún no admite una característica específica
Microsoft Graph agrega continuamente nuevas funcionalidades. En ocasiones, es posible que una nueva API o característica no tenga una API fluida en el SDK inmediatamente. En la mayoría de los casos, puede seguir usando el SDK para realizar solicitudes arbitrarias mediante una cadena de ruta de acceso, lo que proporciona las ventajas del middleware del SDK (autenticación, reintentos, registro) sin necesidad de generadores de solicitudes con tipo. Si el SDK no admite la solicitud en absoluto, puede revertir a llamadas HTTP directas hasta que se agregue compatibilidad con el SDK.
Entornos sensibles al rendimiento
En escenarios como funciones sin servidor o informática perimetral donde la hora de inicio en frío y el tamaño del paquete importan, un enfoque más ligero mediante clientes generados por Kiota o llamadas HTTP directas podría ser más adecuado.
Pasos siguientes
Obtenga información sobre cómo actualizar la aplicación para usar un SDK de Microsoft Graph:
Contenido relacionado
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.
