Usar la API de Microsoft GraphUse the Microsoft Graph API

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.Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

Importante: Cómo se aplican las directivas de acceso condicional a Microsoft Graph es algo que está cambiando.Important: How conditional access policies apply to Microsoft Graph is changing. Las aplicaciones deben actualizarse para administrar los escenarios donde se configuran las directivas de acceso condicional.Applications need to be updated to handle scenarios where conditional access policies are configured. Para obtener más información y directrices, vea Instrucciones para desarrolladores para Acceso condicional de Azure Active Directory.For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

Para leer o escribir en recursos como usuarios o mensajes de correo electrónico, se construye una solicitud similar a la siguiente.To read from or write to a resource such as a user or an email message, you construct a request that looks like the following.

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

Los componentes de una solicitud incluyen:The components of a request include:

  • Método HTTP: método HTTP utilizado en la solicitud a Microsoft Graph.HTTP method - The HTTP method used on the request to Microsoft Graph.
  • {version}: la versión de la API de Microsoft Graph utilizada por la aplicación.{version} - The version of the Microsoft Graph API your application is using.
  • {resource}: el recurso de Microsoft Graph al que se hace referencia.{resource} - The resource in Microsoft Graph that you're referencing.
  • query-parameters: un conjunto opcional de parámetros para modificar la solicitud o la respuesta.query-parameters - An optional set of parameters to modify the request or response.

Después de realizar una solicitud, se devuelve una respuesta que incluye:After you make a request, a response is returned that includes:

  • 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.Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • 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.Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • Vínculo Siguiente: si su solicitud devuelve una gran cantidad de datos, debe recorrer las páginas usando Siguiente. Para más información, consulte Paginación.Next link - If your request returns a lot of data, you need to page through it by choosing Next. For details, see Paging.

Métodos HTTPHTTP methods

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.Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

MétodoMethod DescripciónDescription
GETGET Lee datos de un recurso.Read data from a resource.
POSTPOST Crea un nuevo recurso o realiza una acción.Create a new resource, or perform an action.
PATCHPATCH Actualiza un recurso con nuevos valores.Update a resource with new values.
PUTPUT Reemplaza un recurso por otro nuevo.Replace a resource with a new one.
DELETEDELETE Elimina un recurso.Remove a resource.
  • Para los métodos GET y DELETE, no es necesario un cuerpo de solicitud.For the methods GET and DELETE, no request body is required.
  • 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.The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

VersiónVersion

Microsoft Graph admite actualmente dos versiones: v1.0 y beta.Microsoft Graph currently supports two versions: v1.0 and 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.v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
  • 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.beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

Siempre agradecemos los comentarios sobre nuestras API beta. Para dar su opinión o solicitar características, visite nuestra página UserVoice.We are always looking for feedback on our beta APIs. To provide feedback or request features, see our UserVoice page.

Para obtener más información sobre las versiones de API, consulte Control de versiones y soporte.For more information about API versions, see Versioning and support.

RecursoResource

La dirección URL incluirá el recurso o los recursos con los que interactúa en la solicitud, como me, users, groups, drives y sites. 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 mediante métodos, por ejemplo, para enviar un correo electrónico, utilice me/sendMail.Your URL will include the resource or resources you are interacting with in the request, such as me, users, groups, drives, and sites. Each of the top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. You can also interact with resources using methods; for example, to send an email, use me/sendMail.

Para obtener más información sobre cómo desplazarse por los métodos y relaciones de recursos, consulte Recorrido por Microsoft Graph.For more information about how to navigate resource relationships and methods, see Traverse the 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.Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

Para obtener más información acerca de los permisos, consulte Referencia de permisos.For details about permissions, see Permissions reference.

Parámetros de consulta (opcional)Query parameters (optional)

Puede usar parámetros de consulta opcionales para personalizar la respuesta de la aplicación Microsoft Graph. Use parámetros de consulta 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.You can use optional query parameters to customize the response in your Microsoft Graph app. Use query parameters to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

Por ejemplo, agregar el siguiente parámetro de filtro restringe los mensajes devueltos solo a aquellos que tengan la propiedad emailAddress de jon@contoso.com.For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.

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

Para obtener más información sobre los parámetros de consulta, vea Personalizar respuestas.For more information about query parameters, see Customize responses.

Pasos siguientesNext steps

Está listo para poner en funcionamiento Microsoft Graph. Para obtener más información, vaya a Graph Explorer y pruebe algunas solicitudes y el Inicio rápido, o comience con uno de nuestros ejemplos de código y SDK.You're ready to get up and running with Microsoft Graph. To learn more, go to the Graph Explorer to try out some requests, try the Quick Start, or get started using one of our SDKs and code samples.