Usar la API de Microsoft Graph

Microsoft Graph es una API para web REST que permite tener acceso a los recursos del servicio Microsoft Cloud. Después de registrar su aplicación y obtener tokens de autenticación para un usuario o servicio, puede realizar solicitudes a la API de Microsoft Graph.

Importante

La forma en que se aplican las directivas de acceso condicional a Microsoft Graph está cambiando. Las aplicaciones deben actualizarse para administrar los escenarios donde se configuran las directivas de acceso condicional. Para obtener más información y directrices, vea Instrucciones para desarrolladores sobre el Acceso condicional de Azure Active Directory.

Espacio de nombres OData

La API de Microsoft Graph define la mayoría de sus recursos, métodos y enumeraciones en el espacio de nombres OData, microsoft.graph, en los metadatos de Microsoft Graph. Se define un pequeño número de conjuntos de API en sus subespacios de nombres, como la API de registros de llamadas que define los recursos como callRecord en microsoft.graph.callRecords.

A menos que se especifique explícitamente en el tema correspondiente, asume que los tipos, los métodos y las enumeraciones forman parte del espacio de nombres de microsoft.graph.

Llamar a un método de API REST

Para leer o escribir en recursos como usuarios o mensajes de correo electrónico, se construye una solicitud similar a la siguiente:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Los componentes de una solicitud incluyen:

• {método HTTP}: método HTTP utilizado en la solicitud a Microsoft Graph.
• {versión}: la versión de la API de Microsoft Graph que usa la aplicación.
• {recurso}: el recurso de Microsoft Graph al que se hace referencia.
• {parámetros de consulta}: opciones de consulta de OData opcionales o parámetros del método REST que personalizan la respuesta.

Después de realizar una solicitud, se devuelve una respuesta que incluye:

• Código de estado: un código de estado HTTP que indica correcto o incorrecto. Para obtener más información sobre los códigos de error HTTP, consulte Errores.
• Mensaje de respuesta: los datos que ha solicitado o el resultado de la operación. Con algunas operaciones, el mensaje de respuesta puede estar vacío.
• @odata.nextLink: si su solicitud devuelve una gran cantidad de datos, debe recorrerla usando la URL que se devuelve en @odata.nextLink. Para obtener más información, vea Paginación.

Métodos HTTP

Microsoft Graph utiliza el método HTTP en la solicitud para determinar lo que está haciendo la solicitud. La API admite los siguientes métodos.

Método	Descripción
GET	Lee datos de un recurso.
POST	Crea un nuevo recurso o realiza una acción.
PATCH	Actualiza un recurso con nuevos valores.
PUT	Reemplaza un recurso por otro nuevo.
DELETE	Elimina un recurso.

• Para los métodos CRUD GET y DELETE, no es necesario un cuerpo de solicitud.
• Los métodos POST, PATCH y PUT requieren un cuerpo de la solicitud —generalmente especificado en formato JSON— que contiene información adicional, como los valores de las propiedades del recurso.

Versión

Microsoft Graph admite actualmente dos versiones: v1.0 y beta.

• v1.0 incluye las API que por lo general están disponibles. Utilice la versión v1.0 para todas las aplicaciones de producción.
• beta incluye las API que todavía están en versión preliminar. Debido a que podríamos introducir cambios importantes en nuestras API beta, recomendamos que utilice la versión beta solo para probar aplicaciones que están en desarrollo, y no en sus aplicaciones de producción.

Siempre agradecemos los comentarios sobre nuestras API beta. Para dar su opinión o solicitar características, visite el Foro de ideas de la plataforma de desarrollo de Microsoft 365.

Para obtener más información sobre las versiones de API, consulte Control de versiones y soporte.

Resource

Un recurso puede ser una entidad o un tipo complejo, que normalmente se define con propiedades. Las entidades pueden diferir de los tipos complejos al incluir siempre una propiedad id.

La dirección URL incluirá el recurso con el que interactúa en la solicitud, como me, usuario, grupo, disco y sitio. A menudo, los recursos de nivel superior también incluye relaciones, que se pueden usar para tener acceso a recursos adicionales, como me/messages o me/drive. También puede interactuar con los recursos mediante métodos; por ejemplo, para enviar un correo electrónico, utilice me/sendMail. Para obtener más información, vea Obtener acceso a datos y métodos al navegar por Microsoft Graph.

Cada recurso podría necesitar diferentes permisos de acceso. A menudo necesitará un nivel de permisos mayor para crear o actualizar un recurso que para leerlo. Para obtener más información sobre los permisos necesarios, consulte el tema de referencia del método.

Para obtener más información acerca de los permisos, consulte Referencia de permisos.

Parámetros de consulta

Los parámetros de consulta pueden ser opciones de consulta de sistema de OData u otras cadenas que un método acepta para personalizar la respuesta.

Use opciones de consulta de sistema de OData opcionales para incluir más o menos propiedades que la respuesta predeterminada, filtrar la respuesta según los elementos que coincidan con una consulta personalizada o proporcionar parámetros adicionales para un método.

Por ejemplo, agregar el siguiente parámetro filter restringe los mensajes devueltos solo a aquellos que tengan la propiedad emailAddress de jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Para obtener más información sobre las opciones de consulta, vea Usar los parámetros de consulta para personalizar respuestas.

Aparte de las opciones de consulta de OData, algunos métodos requieren valores de parámetro especificados como parte de la dirección URL de la consulta. Por ejemplo, puede obtener una colección de eventos producidos durante un período de tiempo en el calendario de un usuario consultando la relación calendarView de un user y especificando los valores de período startDateTime y endDateTime como parámetros de consulta:

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Herramientas para interactuar con Microsoft Graph

Probador de Graph

Graph Explorer es una herramienta basada en web que puede usar para generar y probar solicitudes con las API de Microsoft Graph. Puede acceder a ella en https://developer.microsoft.com/graph/graph-explorer.

Puede acceder a los datos de la demostración sin iniciar sesión, o puede iniciar sesión en un espacio empresarial propio. Siga estos pasos para crear la solicitud:

1. Seleccione el método HTTP.
2. Seleccione la versión de API que quiera usar.
3. Escriba la consulta en el cuadro de texto solicitud.
4. Seleccione Ejecutar consulta.

El ejemplo siguiente muestra una solicitud que devuelve información sobre los usuarios en el espacio empresarial de demostración:

Las consultas de ejemplo se proporcionan en el Probador de Graph para permitirle ejecutar solicitudes comunes más rápidamente. Para ver los ejemplos disponibles, seleccione mostrar más muestras. Seleccione Activado para el conjunto de ejemplos que quiera ver y, después de cerrar la ventana de selección, debería ver una lista de solicitudes predefinidas.

Se mostrarán un código de estado y un mensaje después de enviar una solicitud y la respuesta se mostrará en la pestaña Vista previa de respuesta.

Postman

Postman es una herramienta que puede usar para crear y probar solicitudes con las API de Microsoft Graph. Puede descargar Postman en https://www.getpostman.com/. Para interactuar con Microsoft Graph en Postman, debe usar la colección de Microsoft Graph.

Para más información, consulte Usar Postman con la API de Microsoft Graph.

Siguientes pasos

Está listo para poner en funcionamiento Microsoft Graph.Vaya a Inicio rápido o empiece usando uno de nuestros SDK y muestras de código.