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.
Garrantzitsua
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.
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
.
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.
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
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.
Garrantzitsua
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".
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.
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.
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
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.
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:
- 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 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.
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.