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
yDELETE
, no es necesario un cuerpo de solicitud. - Los métodos
POST
,PATCH
yPUT
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:
- Seleccione el método HTTP.
- Seleccione la versión de API que quiera usar.
- Escriba la consulta en el cuadro de texto solicitud.
- 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.
Comentarios
Enviar y ver comentarios de