Consulta de Microsoft Graph mediante REST

  • 3 minutos

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

Microsoft Graph API define la mayoría de sus recursos, métodos y enumeraciones en el espacio de nombres de OData, microsoft.graph, en los metadatos de Microsoft Graph. Hay varios conjuntos de API definidos en sus subespacios de nombres, como la API de registros de llamadas que define recursos como callRecord en microsoft.graph.callRecords.

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

Llamada a un método de API REST

Para leer o escribir en un recurso, como un usuario o un mensaje de correo electrónico, construya una solicitud similar a la siguiente:

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

Los componentes de una solicitud incluyen:

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

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

  • Código de estado: código de estado HTTP que indica acierto o fallo.
  • Mensaje de respuesta: los datos que solicitó o el resultado de la operación. El mensaje de respuesta puede estar vacío en el caso de algunas operaciones.
  • nextLink: si la solicitud devuelve varios datos, debe paginarlos mediante la dirección URL devuelta en @odata.nextLink.

Métodos HTTP

Microsoft Graph usa el método HTTP en la solicitud para determinar lo que hace la solicitud. La API admite los métodos siguientes.

Método Descripción
GET Leer datos de un recurso.
POST Crear un recurso o realizar una acción.
PATCH Actualizar un recurso con nuevos valores.
PUT Reemplazar un recurso por uno nuevo.
Delete Quitar un recurso.
  • En el caso de los métodos CRUD GET y DELETE, no se requiere ningún cuerpo de solicitud.
  • Los métodos POST, PATCH y PUT requieren que se especifique un cuerpo de solicitud en formato JSON que contenga información adicional. Por ejemplo, los valores de las propiedades del recurso.

Versión

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

  • v1.0 incluye las API disponibles con carácter general. Use la versión v1.0 para todas las aplicaciones de producción.
  • beta incluye las API que están actualmente en versión preliminar. Dado que podríamos introducir cambios importantes en nuestras API de la versión beta, se recomienda usar la versión beta solo para probar las aplicaciones que están en desarrollo. No use las API de la versión beta en las aplicaciones de producción.

Recurso

Un recurso puede ser una entidad o un tipo complejo, normalmente definido con propiedades. Las entidades difieren de los tipos complejos en que siempre incluyen una propiedad id.

La dirección URL incluye el recurso con el que interactúa en la solicitud, como me, usuario, grupo, unidad y sitio. A menudo, los recursos de nivel superior también incluyen relaciones, que puede usar para acceder a otros recursos, como me/messages o me/drive. También puede interactuar con recursos mediante métodos; por ejemplo, para enviar un correo electrónico, use me/sendMail.

Cada recurso puede exigir permisos de acceso diferentes. Con frecuencia, necesitará un mayor nivel de permisos para crear o actualizar un recurso que para leerlo. Para más información sobre los permisos necesarios, consulte el tema de referencia del método.

Parámetros de consulta

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

Puede usar opciones de consulta del sistema OData opcionales para incluir más o menos propiedades que la respuesta predeterminada, filtrar la respuesta por los elementos que coincidan con una consulta personalizada o proporcionar otros parámetros para un método.

Por ejemplo, al agregar el parámetro filter siguiente, se restringen los mensajes devueltos a solo aquellos con la propiedad emailAddress de jon@contoso.com.

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

Otros recursos

A continuación, se muestran vínculos a algunas herramientas que puede usar para compilar y probar solicitudes mediante las instancias de Microsoft Graph API.