Usar la API de Microsoft Graph

  • Artículo

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 e instrucciones, consulte Guía para desarrolladores para Microsoft Entra acceso condicional.

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.
  • {headers}: encabezados de solicitud que personalizan la solicitud. Puede ser opcional o obligatorio en función de la API.

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

  • Código de estado: un código de estado HTTP que indica éxito o error. Para obtener más información sobre los códigos de error HTTP, consulte Errores.
  • Mensaje de respuesta: los datos que solicitó o el resultado de la operación. El mensaje de respuesta puede estar vacío para algunas operaciones.
  • @odata.nextLink - Si la solicitud devuelve una gran cantidad de datos, debe paginar mediante la dirección URL devuelta en @odata.nextLink. Para más información, consulte Paginación.
  • Encabezados de respuesta: información adicional sobre la respuesta, como el tipo de contenido devuelto y el identificador de solicitud que puede usar para correlacionar la respuesta con la solicitud.

Métodos HTTP

Microsoft Graph usa el método HTTP en la solicitud para determinar lo que está haciendo la solicitud. En función del recurso, la API puede admitir operaciones como acciones, funciones o operaciones CRUD que se describen a continuación.

Método Descripción
GET Lee datos de un recurso.
POST Crea un nuevo recurso o realiza una acción.
PATCH Actualice un recurso con nuevos valores o actualice un recurso (cree si el recurso no existe, actualice en caso contrario).
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.

Importante

Las solicitudes de escritura en microsoft Graph API tienen un límite de tamaño de 4 MB.

En algunos casos, el límite real de tamaño de la solicitud de escritura es inferior a 4 MB. Por ejemplo, adjuntar un archivo a un evento de usuario tiene POST /me/events/{id}/attachments un límite de tamaño de solicitud de 3 MB, ya que un archivo de alrededor de 3,5 MB puede ser mayor que 4 MB cuando se codifica en base64.

Las solicitudes que superan el límite de tamaño producen un error con el código de estado HTTP 413 y el mensaje de error "Entidad de solicitud demasiado grande" o "Carga demasiado grande".

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 proporcionar comentarios o solicitar características, vea nuestro Foro de ideas de la plataforma para desarrolladores 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, user, group, drive y site. Cada uno de 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 con métodos (por ejemplo, para enviar un correo electrónico, use me/sendMail). Para obtener más información, vea Tener acceso a datos y métodos al navegar por Microsoft Graph.

Cada recurso puede requerir permisos diferentes para acceder a él. A menudo necesitará un mayor nivel de permisos 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

Encabezados

Microsoft Graph admite encabezados estándar HTTP y encabezados personalizados.

Las API específicas pueden requerir que se incluyan encabezados adicionales en la solicitud. Por otro lado, Microsoft Graph siempre devolverá encabezados obligatorios, como el request-id encabezado en la respuesta, o algunos encabezados pueden ser específicos de algunas API o funcionalidades, por ejemplo, el encabezado se incluye cuando la Retry-After aplicación alcanza los límites de limitación o el Location encabezado que se incluye para las operaciones de larga duración.

Los encabezados no distinguen mayúsculas de minúsculas como se define en rfc 9110 , a menos que se especifique explícitamente lo contrario.

Herramientas para interactuar con Microsoft Graph

Probador de Graph

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

Puede obtener acceso a los datos de la demo sin iniciar sesión, o puede iniciar sesión en un espacio empresarial propio. Siga los pasos siguientes 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:

Captura de pantalla de Graph Explorer con una solicitud Obtener usuario resaltada

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. Pruebe el Inicio rápido o empiece a usar uno de nuestros SDK y muestras de código.