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

  • Artículo

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 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 una variedad de opciones, como el filtrado y la ordenación, y, por último, seleccionar el tipo de operación que desea realizar.

También existe 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, 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 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 = new string[] { "displayName", "jobTitle"};
    });

Recuperar una lista de entidades

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

Nota:

Algunas solicitudes de recursos de Azure Active Directory requieren el uso de funcionalidades de consulta avanzadas. Si obtiene 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 de Azure AD.

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

var messages = await graphClient.Me.Messages
    .GetAsync( requestConfig => 
                {
                    requestConfig.QueryParameters.Select = new string[] { "subject", "sender"};
                    requestConfig.QueryParameters.Filter = "<filter condition>";
                    requestConfig.QueryParameters.Orderby = new string[] { "receivedDateTime" };
                });

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. Para 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]
    .GetAsync();

Puede usar el $expand filtro para solicitar una entidad relacionada, o una colección de entidades, al mismo tiempo que solicita 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]
    .GetAsync( requestConfig => requestConfig.QueryParameters.Expand = new string[] { "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}

string messageId = "AQMkAGUy...";
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, hay disponible un New-* comando 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
    .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 y, 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
    }
};

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

await graphClient.Teams[teamId]
    .PatchAsync(team);

Uso de encabezados HTTP para controlar el comportamiento de las solicitudes

Puede usar una Header() función 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
    .GetAsync( requestConfig => 
                {
                    requestConfig.Headers.Add("Prefer", @"outlook.timezone=""Pacific Standard Time""");
                    requestConfig.QueryParameters.Select = new string[] {"subject", "body", "bodyPreview"};
                });

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 mediante 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

var calendar = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration => 
    {
        requestConfiguration.QueryParameters.StartDateTime = "2020-12-01T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime = "2020-12-30T00:00:00Z";
    });