Realizar llamadas API con los SDK de Microsoft Graph

  • Artículo
  • Tiempo de lectura: 9 minutos

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

También está microsoft Graph SDK de PowerShell, 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 la búsqueda de comandos para llamadas API, vea Navegación por microsoft Graph SDK de PowerShell.

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
    .Request()
    .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, en algunos escenarios no es necesario devolver el conjunto predeterminado de propiedades. Seleccionar solo las propiedades necesarias puede mejorar el rendimiento de la solicitud. Puede personalizar la solicitud para incluir el parámetro $select de consulta con una lista de propiedades.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle

var user = await graphClient.Me
    .Request()
    .Select(u => new {
        u.DisplayName,
        u.JobTitle
    })
    .GetAsync();

Recuperar una lista de entidades

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

// GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

var messages = await graphClient.Me.Messages
    .Request()
    .Select(m => new {
        m.Subject,
        m.Sender
    })
    .Filter("<filter condition>")
    .OrderBy("receivedDateTime")
    .GetAsync();

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, vea paginación a través de una colección.

Obtener acceso a un elemento de una colección

Para SDK que admiten un estilo fluido, se puede tener acceso 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}

string messageId = "AQMkAGUy..";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .GetAsync();

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

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .Expand("attachments")
    .GetAsync();

Eliminar una entidad

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

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .DeleteAsync();

Realizar una solicitud POST para crear una nueva entidad

Para 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 request expone un post método. Para PowerShell, hay un New-* comando disponible que acepta parámetros que se asignan a la entidad que se va a agregar. La entidad creada normalmente 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
    .Request()
    .AddAsync(calendar);

Actualización de una entidad existente con PATCH

La mayoría de las actualizaciones de Microsoft Graph se realizan con un método y, por lo tanto, solo es necesario incluir las propiedades que desea PATCH 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
    }
};

var teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";

await graphClient.Teams[teamId]
    .Request()
    .UpdateAsync(team);

Usar encabezados HTTP para controlar el comportamiento de la solicitud

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

//  GET https://graph.microsoft.com/v1.0/users/{user-id}/events

var events = await graphClient.Me.Events
    .Request()
    .Header("Prefer",@"outlook.timezone=""Pacific Standard Time""")
    .Select( e => new {
        e.Subject,
        e.Body,
        e.BodyPreview
    })
    .GetAsync();

Proporcionar parámetros de consulta personalizados

Para 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 están codificados en 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

var queryOptions = new List<QueryOption>()
{
    new QueryOption("startdate", "2020-12-01T00:00:00Z"),
    new QueryOption("enddate", "2020-12-30T00:00:00Z")
};

var calendar = await graphClient.Me.CalendarView()
    .Request(queryOptions)
    .GetAsync();