Realización de llamadas API mediante los SDK de Microsoft Graph

  • Artículo

Las bibliotecas de servicio del SDK de Microsoft Graph proporcionan una clase de cliente que se usará como punto de partida para crear todas las solicitudes de API. Hay dos estilos de clase de cliente: uno usa una interfaz fluida para crear la solicitud (por ejemplo, client.Users["user-id"].Manager) y el otro acepta una cadena de ruta de acceso (por ejemplo, api("/users/user-id/manager")). Cuando tiene un objeto de solicitud, puede especificar varias opciones, como el filtrado y la ordenación, y, por último, seleccionar el tipo de operación que desea realizar.

También está el SDK de PowerShell de Microsoft Graph, que no tiene ninguna clase de cliente. En su lugar, todas las solicitudes se representan como comandos de PowerShell. Por ejemplo, para obtener el administrador de un usuario, el comando es Get-MgUserManager. Para obtener más información sobre cómo buscar comandos para llamadas API, consulte Navegación por el SDK de PowerShell de Microsoft Graph.

Leer información de Microsoft Graph

Para leer información de Microsoft Graph, primero debe crear un objeto de solicitud y, a continuación, ejecutar el GET método en la solicitud.

// GET https://graph.microsoft.com/v1.0/me
var user = await graphClient.Me
    .GetAsync();

Usar $select para controlar las propiedades devueltas

Al recuperar una entidad, no todas las propiedades se recuperan automáticamente; a veces, deben seleccionarse explícitamente. Además, no es necesario devolver el conjunto predeterminado de propiedades en algunos escenarios. Seleccionar solo las propiedades necesarias puede mejorar el rendimiento de la solicitud. Puede personalizar la solicitud para incluir el parámetro de $select consulta con una lista de propiedades.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
var user = await graphClient.Me
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Select =
            ["displayName", "jobTitle"];
    });

Recuperar una lista de entidades

Recuperar una lista de entidades es similar a recuperar una sola entidad, excepto que existen otras opciones para configurar la solicitud. El $filter parámetro de consulta puede reducir el conjunto de resultados a solo las filas que coincidan con la condición proporcionada. El $orderby parámetro de consulta solicita que el servidor proporcione la lista de entidades ordenadas por las propiedades especificadas.

Nota:

Algunas solicitudes de recursos de Microsoft Entra requieren el uso de funcionalidades de consulta avanzadas. Si recibe una respuesta que indica una solicitud incorrecta, una consulta no admitida o una respuesta que incluye resultados inesperados, incluidos el parámetro y ConsistencyLevel el $count encabezado de consulta, puede permitir que la solicitud se realice correctamente. Para obtener detalles y ejemplos, consulte Funcionalidades avanzadas de consulta en objetos de directorio.

// GET https://graph.microsoft.com/v1.0/me/messages?
// $select=subject,sender&$filter=subject eq 'Hello world'
var messages = await graphClient.Me.Messages
    .GetAsync(requestConfig =>
    {
        requestConfig.QueryParameters.Select =
            ["subject", "sender"];
        requestConfig.QueryParameters.Filter =
            "subject eq 'Hello world'";
    });

Es probable que el objeto devuelto al recuperar una lista de entidades sea una colección paginada. Para obtener más información sobre cómo obtener la lista completa de entidades, consulte paginación a través de una colección.

Acceso a un elemento de una colección

En el caso de los SDK que admiten un estilo fluido, se puede acceder a las colecciones de entidades mediante un índice de matriz. En el caso de los SDK basados en plantillas, basta con insertar el identificador de elemento en el segmento de ruta de acceso que sigue a la colección. Para PowerShell, los identificadores se pasan como parámetros.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync();

Puede usar el $expand filtro para solicitar una entidad o colección de entidades relacionadas al mismo tiempo que solicita la entidad principal.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync(requestConfig =>
        requestConfig.QueryParameters.Expand =
            ["attachments"]);

Eliminación de una entidad

Las solicitudes de eliminación se construyen de la misma manera que las solicitudes para recuperar una entidad, pero usan una DELETE solicitud en lugar de .GET

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
await graphClient.Me.Messages[messageId]
    .DeleteAsync();

Realizar una solicitud POST para crear una nueva entidad

En el caso de los SDK que admiten un estilo fluido, se pueden agregar nuevos elementos a colecciones con un Add método . En el caso de los SDK basados en plantillas, el objeto de solicitud expone un post método. Para PowerShell, un New-* comando acepta parámetros que se asignan a la entidad que se va a agregar. La entidad creada se devuelve de la llamada.

// POST https://graph.microsoft.com/v1.0/me/calendars
var calendar = new Calendar
{
    Name = "Volunteer",
};

var newCalendar = await graphClient.Me.Calendars
    .PostAsync(calendar);

Actualización de una entidad existente con PATCH

La mayoría de las actualizaciones de Microsoft Graph se realizan mediante un PATCH método; por lo tanto, solo es necesario incluir las propiedades que desea cambiar en el objeto que se pasa.

// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
var team = new Team
{
    FunSettings = new TeamFunSettings
    {
        AllowGiphy = true,
        GiphyContentRating = GiphyRatingType.Strict,
    },
};

// teamId is a string containing the id property of the team
await graphClient.Teams[teamId]
    .PatchAsync(team);

Uso de encabezados HTTP para controlar el comportamiento de las solicitudes

Puede adjuntar encabezados personalizados a una solicitud mediante una Header() función. Para PowerShell, agregar encabezados solo es posible con el Invoke-GraphRequest método . Algunos escenarios de Microsoft Graph usan encabezados personalizados para ajustar el comportamiento de la solicitud.

// GET https://graph.microsoft.com/v1.0/me/events
var events = await graphClient.Me.Events
    .GetAsync(requestConfig =>
    {
        requestConfig.Headers.Add(
            "Prefer", @"outlook.timezone=""Pacific Standard Time""");
    });

Proporcionar parámetros de consulta personalizados

En el caso de los SDK que admiten un estilo fluido, puede proporcionar valores de parámetros de consulta personalizados mediante una lista de QueryOptions objetos. En el caso de los SDK basados en plantillas, los parámetros se codifican con dirección URL y se agregan al URI de solicitud. Para PowerShell y Go, los parámetros de consulta definidos para una API determinada se exponen como parámetros al comando correspondiente.

// GET https://graph.microsoft.com/v1.0/me/calendarView?
// startDateTime=2023-06-14T00:00:00Z&endDateTime=2023-06-15T00:00:00Z
var events = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.StartDateTime =
            "2023-06-14T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime =
            "2023-06-15T00:00:00Z";
    });