Procedimientos recomendados para trabajar con Microsoft Graph.

En este artículo se describen los procedimientos recomendados que puede aplicar para ayudar a las aplicaciones a sacar el máximo partido de Microsoft Graph, ya sea que esto implique aprender sobre Microsoft Graph, mejorar el rendimiento de las aplicaciones o hacer que la aplicación sea más confiable para los usuarios finales.

Usar la herramienta Probador de Graph para familiarizarse con la API

La mejor manera de empezar a explorar los datos disponibles en Microsoft Graph es usar Probador de Graph. Probador de Graph le permite crear solicitudes REST (con soporte completo de CRUD), adaptar los encabezados de solicitud HTTP y ver las respuestas de datos. Para ayudarle a empezar, Probador de Graph ofrece también un conjunto de consultas de ejemplo.

Experimente con nuevas API antes de integrarlas en la aplicación.

Autenticación

Para acceder a los datos a través de Microsoft Graph, la aplicación debe adquirir un token de acceso de OAuth 2.0 y presentarlo a Microsoft Graph en cualquiera de las siguientes opciones:

• El encabezado de solicitud Authorization HTTP, como token de portador
• El constructor cliente de Graph, cuando use una biblioteca cliente de Microsoft Graph

Use la Biblioteca de autenticación de Microsoft (MSAL) para adquirir el token de acceso a Microsoft Graph.

Consentimiento y autorización

Siga estos procedimientos recomendados para otorgar consentimiento y autorización en la aplicación:

• Aplicar privilegios mínimos. Conceda a los usuarios y a las aplicaciones solo el permiso con privilegios más bajo que necesiten para llamar a la API. Consulte la sección de permisos en los temas de método (por ejemplo, vea Crear usuario) y elija los permisos con privilegios mínimos. Por ejemplo, si la aplicación solo leerá el perfil del usuario que ha iniciado sesión actualmente, conceda User.Read en lugar de User.ReadBasic.All. Si una aplicación no lee el calendario del usuario, no le conceda el permiso Calendars.Read . Para obtener la lista completa de permisos, vea Referencia de permisos.

• Utilizar el tipo de permiso basado en escenarios adecuado. Evite usar permisos delegados y de aplicación en la misma aplicación. Si va a compilar una aplicación interactiva en la que haya un usuario que haya iniciado sesión, la aplicación debe usar permisos delegados. En cambio, si la aplicación se ejecuta sin que haya un usuario que ha iniciado sesión, como un demonio o servicio en segundo plano, la aplicación debe usar permisos de aplicación.

  Precaución

  El uso de permisos de aplicación en escenarios interactivos puede exponer la aplicación a riesgos de seguridad y cumplimiento normativo. Se pueden elevar involuntariamente los privilegios de acceso a datos de un usuario, saltándose las directivas configuradas por un administrador.

• Tener cuidado al configurar la aplicación. Esto afectará directamente a las experiencias de usuario final y de administrador, así como a la seguridad y la adopción de la aplicación. Por ejemplo:

  • El nombre, el logotipo, el dominio, el estado de comprobación del publicador, la declaración de privacidad y los términos de uso de la aplicación se muestran con consentimiento y otras experiencias. Configure estas opciones cuidadosamente para que los usuarios finales las comprendan.
  • Tenga en cuenta quiénes darán consentimiento en la aplicación (administradores o usuarios finales) y configure la aplicación para solicitar permisos adecuadamente.
  • Asegúrese de que comprende la diferencia entre consentimiento estático, dinámico e incremental.

• Considerar el uso de aplicaciones multiempresa. Cuente con la posibilidad de que los clientes tengan varios controles de aplicación y consentimiento en diferentes estados. Por ejemplo:

  • Los administradores de inquilinos pueden deshabilitar la posibilidad de que los usuarios finales den su consentimiento a las aplicaciones. En este caso, un administrador tendrá que dar el consentimiento en nombre de los usuarios.
  • Los administradores de inquilinos pueden establecer directivas de autorización personalizadas tales como impedir que los usuarios lean los perfiles de otros usuarios o restringir la creación de grupos de autoservicio a un conjunto limitado de usuarios. En este caso, es de esperar que la aplicación tenga que controlar la respuesta de error 403 Forbidden cuando actúe en nombre de un usuario.

Controlar las respuestas con eficacia

Las aplicaciones han de estar preparadas para controlar distintos tipos de respuestas en función de las solicitudes que se realicen en Microsoft Graph. Estos son algunos de los procedimientos más importantes que hay que seguir para garantizar que la aplicación tenga un comportamiento confiable y predecible para los usuarios finales.

Paginación

Al consultar una colección de recursos, es muy probable que Microsoft Graph establezca el conjunto de resultados obtenido en varias páginas, debido a límites de tamaño de página del lado del servidor. Cuando un conjunto de resultados abarca varias páginas, Microsoft Graph devuelve una propiedad @odata.nextLink en la respuesta que contiene una dirección URL a la siguiente página de resultados.

Por ejemplo, al mostrar los mensajes de usuarios que han iniciado sesión:

GET https://graph.microsoft.com/v1.0/me/messages

Se devolverá una respuesta que contiene una propiedad @odata.nextLink si el conjunto de resultados supera el límite de tamaño de página del servidor.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

Nota:

La aplicación siempre debe controlar la posibilidad de que las respuestas se paginen por naturaleza y usen la propiedad @odata.nextLink para obtener el próximo conjunto de resultados paginado, hasta que se hayan leído todas las páginas del conjunto de resultados. La última página no contendrá ninguna propiedad @odata.nextLink. Debe incluir la dirección URL completa en la propiedad @odata.nextLink de la solicitud de la siguiente página de resultados, que trata la URL completa como opaca.

Para obtener más información, consulte paginación.

Control de errores esperados

Aunque la aplicación debe controlar todas las respuestas de error (en los rangos de 400 y 500), preste especial atención a determinados errores esperados y respuestas, que aparecen en la tabla siguiente.

Tema	Código de error HTTP	Procedimiento recomendado
El usuario no tiene acceso	403	Si la aplicación está funcionando, podría encontrarse este error aunque se le hayan concedido los permisos necesarios mediante una experiencia de consentimiento. En este caso, lo más probable es que el usuario que inició sesión no tenga privilegios para acceder al recurso solicitado. La aplicación debe presentar un error genérico "Acceso denegado" al usuario que ha iniciado sesión.
No encontrado	404	En algunos casos, es posible que no se encuentre el recurso solicitado. Por ejemplo, es posible que un recurso no exista, porque aún no se ha aprovisionado (como la foto de un usuario) o porque se ha eliminado. Algunos recursos eliminados podrían restaurarse completamente en los 30 días siguientes a la eliminación, como los recursos de usuario, de grupo y de aplicación, por lo que la aplicación también debe tener esto en cuenta.
Limitación	429	Las API pueden limitarse en cualquier momento por diversos motivos, por lo que la aplicación siempre debe estar preparada para controlar las respuestas 429. Esta respuesta de error incluye el campo Retry-After (volver a intentar más adelante) en el encabezado de la respuesta HTTP. La interrupción de solicitudes con el retraso Retry-After (volver a intentar más adelante) es la mejor forma de recuperarse de la limitación de solicitudes. Para más información, vea limitación.
Servicio no disponible	503	Es probable que esto se deba a que los servicios están ocupados. Debe emplear una estrategia de interrupción similar a la respuesta 429. Además, debe realizar siempre nuevas solicitudes de reintento a través de una nueva conexión HTTP.

Control de futuros miembros en enumeraciones mutables

Agregar miembros a enumeraciones existentes puede interrumpir las aplicaciones que ya usan estas enumeraciones. La API de Microsoft Graph utiliza el mecanismo de enumeraciones mutables para agregar nuevos miembros a enumeraciones existentes sin provocar un cambio importante en las aplicaciones.

Las enumeraciones mutables tienen un miembro centinela común llamado unknownFutureValue que delimita los miembros conocidos que se han definido inicialmente en la enumeración frente a los miembros desconocidos que se van agregando posteriormente o que se definirán en el futuro. Los miembros conocidos se asignan internamente a valores numéricos que son menores que el miembro centinela y los miembros desconocidos a valores mayores que el miembro centinela. En la documentación de una enumeración mutable se enumeran los posibles valores de cadena en orden ascendente: miembros conocidos seguidos de unknownFutureValue y seguidos de miembros desconocidos. Al igual que en otros tipos de enumeraciones, siempre se debe hacer referencia a los miembros de enumeraciones mutables por sus valores de cadena.

De forma predeterminada, una operación GET devuelve solo los miembros conocidos para las propiedades de los tipos de enumeración mutable y la aplicación debe ser capaz de controlar solo los miembros conocidos. Si también diseña la aplicación para controlar miembros desconocidos, puede optar por recibir esos miembros mediante un encabezado de solicitud HTTP Prefer :

Prefer: include-unknown-enum-members

Almacenamiento de datos local

Lo ideal es que la aplicación realice llamadas a Microsoft Graph para recuperar datos en tiempo real cuando sea necesario. Solo deben almacenarse datos en caché o localmente si es necesario en un escenario específico y si ese caso de uso está cubierto por las condiciones de uso y la directiva de privacidad y no infringe los Condiciones de Uso de las API de Microsoft. La aplicación también debe implementar políticas de retención y eliminación adecuadas.

Optimizaciones

En general, por motivos de rendimiento e incluso de seguridad o privacidad, solo deben obtenerse los datos que la aplicación realmente necesita y nada más.

Proyecciones de uso

Elija solo las propiedades que la aplicación realmente necesita y nada más, porque así ahorra tráfico de red y procesamiento de datos innecesarios en su aplicación (y en el servicio).

Nota:

Utilice el parámetro de consulta $select para limitar las propiedades devueltas por una consulta a las necesarias para la aplicación.

Por ejemplo, al recuperar los mensajes del usuario que ha iniciado sesión, puede especificar que solo se devuelvan las propiedades from y subject:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Al realizar una solicitud GET sin usar $select para limitar la cantidad de datos de propiedades, Microsoft Graph incluye una propiedad @microsoft.graph.tips que proporciona una recomendación de procedimientos recomendados para usar $select de forma similar al siguiente mensaje:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Obtener respuestas mínimas

Con algunas operaciones, como PUT y PATCH (y, en algunos casos, POST), si la aplicación no tiene que usar una carga útil de respuesta, puede pedir a la API que devuelva datos mínimos. Algunos servicios ya devuelven una 204 No Content respuesta para las operaciones PUT y PATCH.

Nota:

Solicite respuestas de representación mínimas mediante el encabezado Prefer establecido en return=minimal, donde se admite. Para las operaciones de creación, es posible que el uso de este encabezado no sea adecuado porque es posible que la aplicación espere obtener el servicio generado id para el objeto recién creado en la respuesta.

Control de cambios: consulta delta y notificaciones de webhook

Si la aplicación tiene que estar informada de los cambios en los datos, se puede obtener una notificación de webhook siempre que los datos de interés hayan cambiado. Esto es más eficaz que simplemente sondear con regularidad.

Utilice notificaciones de webhook para recibir notificaciones push cuando cambien los datos.

Si se requiere que la aplicación almacene en caché o localmente los datos de Microsoft Graph y los mantenga actualizados o que, por otros motivos, siga los cambios en los datos, debe utilizarse la consulta delta. Esto evita un cálculo excesivo por parte de la aplicación para recuperar los datos que la aplicación ya tiene, minimizar el tráfico de red y reducir la probabilidad de alcanzar un umbral de limitación.

Use la consulta delta para mantener los datos actualizados con eficacia.

Uso conjunto de webhooks y consulta delta

Los webhooks y las consultas delta suelen usarse mejor juntos, ya que si usa solo la consulta delta, debe averiguar el intervalo de sondeo adecuado: demasiado corto y esto podría dar lugar a respuestas vacías, que desperdician recursos, demasiado tiempo y podría acabar con datos obsoletos. Si utiliza notificaciones de webhook como desencadenador de llamadas de consulta delta, obtendrá lo mejor de ambos mundos.

Utilice notificaciones de webhook como desencadenador de llamadas de consulta delta. También debe asegurarse de que la aplicación tenga un umbral de sondeo de seguridad en caso de que no se active ninguna notificación.

Procesamiento por lotes

El procesamiento por lotes de JSON le permite optimizar la aplicación combinando varias solicitudes en un solo objeto JSON. La combinación de solicitudes individuales en una sola solicitud por lotes puede ahorrarle a la aplicación una cantidad significativa de latencia de red y conservar los recursos de conexión.

Use el procesamiento por lotes donde una latencia de red significativa puede tener un impacto significativo en el rendimiento.

Confiabilidad y compatibilidad

Para garantizar la confiabilidad y facilitar la compatibilidad con la aplicación:

• Use TLS 1.3 o 1.2 para admitir todas las funcionalidades de Microsoft Graph. Migre desde TLS 1.0 y 1.1. Para obtener más información, consulte Habilitación de la compatibilidad con TLS 1.2 en su entorno.
• Respete el TTL de DNS y establezca el TTL de la conexión para que coincidan. Esto garantiza la disponibilidad en caso de conmutaciones por error.
• Abra las conexiones a todas las respuestas DNS anunciadas.
• Genere un GUID único y envíelo en cada solicitud del resto de Microsoft Graph REST. Esto ayuda a Microsoft a investigar los errores más fácilmente si necesita informar de un problema con Microsoft Graph.
  • En cada solicitud de Microsoft Graph, genere un GUID único, envíelo por el client-request-id encabezado de la solicitud HTTP y también iniciar sesión en los registros de la aplicación.
  • Registre siempre y request-idDate desde los encabezados de respuesta HTTP. Estos, junto con client-request-id, son necesarios para informar de problemas en Microsoft Q&A o Soporte técnico de Microsoft.