Procedimientos recomendados para trabajar con Microsoft Graph.

  • Artículo

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 tener acceso a los datos a través de Microsoft Graph, la aplicación debe adquirir un token de acceso OAuth 2.0 y presentarlo a Microsoft Graph mediante alguna 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 API Biblioteca de autenticación de Microsoft (MSAL) para adquirir el token de acceso a Microsoft Graph.

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 verificación del editor, la declaración de privacidad y los términos de uso de la aplicación se mostrarán en el consentimiento y en otras experiencias. Configure estas opciones con cuidado para que los usuarios finales las entiendan.
    • 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 más información, vea 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
User does not have access (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, es muy probable que el usuario que ha iniciado sesión no tenga privilegios de acceso 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, puede que un recurso no exista, porque no se ha aprovisionado todavía (como la foto de un usuario) o 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 Puede que las API limiten las solicitudes en cualquier momento por diversos motivos, por lo que la aplicación debe estar siempre preparada para controlar 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 Probablemente se deba a que el servicio está ocupado. 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 diseña la aplicación para controlar también los miembros desconocidos, puede optar por recibirlos 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. Tenga en cuenta que 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 resulta más eficaz que simplemente realizar sondeos periódicamente.

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 que la aplicación realice cálculos excesivos para recuperar datos que ya tiene, minimiza el tráfico de red y reduce 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

Suele ser preferible utilizar los webhooks y la consulta delta juntos, porque si se utiliza solo la consulta delta, es necesario averiguar el intervalo de sondeo correcto: si es demasiado corto podría traducirse en respuestas vacías que desperdician recursos y, si es demasiado largo, es posible que se acabe 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 procesamiento por lotes cuando una de latencia de red significativa pueda tener un gran impacto en el rendimiento.

Confiabilidad y compatibilidad

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

  • Use TLS 1.2 para admitir todas las funcionalidades de Microsoft Graph. Para obtener más información sobre el desuso de Microsoft Graph TLS 1.0 y 1.1, consulte Habilitar la compatibilidad con TLS 1.2 en el 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 le ayudará 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.