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.
El SDK de Microsoft Graph para Go está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
// GET https://graph.microsoft.com/v1.0/me
result, err := client.Me().Get(context.Background(), nil)
Importante
El SDK de Microsoft Graph para Python está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
# GET https://graph.microsoft.com/v1.0/me
user = asyncio.run(client.me.get())
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"};
});
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
let user = await client.api('/me')
.select('displayName', 'jobTitle')
.get();
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
final User user = graphClient.me()
.buildRequest()
.select("DisplayName,JobTitle")
.get();
# GET https://graph.microsoft.com/v1.0/users/{user-id}?$select=displayName,jobTitle
$userId = "71766077-aacc-470a-be5e-ba47db3b2e88"
# The -Property parameter causes a $select parameter to be included in the request
$user = Get-MgUser -UserId $userId -Property DisplayName,JobTitle
Importante
El SDK de Microsoft Graph para Go está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
El SDK de Microsoft Graph para Python está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
# GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
query_params = MeRequestBuilder.MeRequestBuilderGetQueryParameters(
select=['displayName', 'jobTitle']
)
request_config = MeRequestBuilder.MeRequestBuilderGetRequestConfiguration(
query_parameters=query_params,
)
user = asyncio.run(client.me
.get(request_configuration=request_config))
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.
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();
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
let messageId = 'AQMkAGUy..';
let messages = await client.api(`/me/messages/${messageId}`)
.get();
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
final String messageId = "AQMkAGUy..";
final Message message = graphClient.me().messages(messageId)
.buildRequest()
.get();
// 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" });
// GET https://graph.microsoft.com/v1.0/me/messages?$expand=attachments
let messageId = 'AQMkAGUy..';
let message = await client.api(`/me/messages/${messageId}`)
.expand('attachments')
.get();
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
final String messageId = "AQMkAGUy...";
final Message message = graphClient.me().messages(messageId)
.buildRequest()
.expand("attachments")
.get();
# GET https://graph.microsoft.com/v1.0/users/{user-id}/messages?$expand=attachments
$userId = "71766077-aacc-470a-be5e-ba47db3b2e88"
$messageId = "AQMkAGUy.."
# -ExpandProperty is equivalent to $expand
$message = Get-MgUserMessage -UserId $userId -MessageId $messageId -ExpandProperty Attachments
Importante
El SDK de Microsoft Graph para Go está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
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
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);
// POST https://graph.microsoft.com/v1.0/me/calendars
final Calendar calendar = new Calendar();
calendar.Name = "Volunteer";
final Calendar newCalendar = graphClient.me().calendars()
.buildRequest()
.post(calendar);
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);
// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
final Team team = new Team();
team.FunSettings = new TeamFunSettings();
team.FunSettings.AllowGiphy = true;
team.FunSettings.GiphyContentRating = GiphyRatingType.STRICT;
final String teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";
graphClient.teams(teamId)
.buildRequest()
.patch(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"};
});
// GET https://graph.microsoft.com/v1.0/me/events
let events = await client.api('/me/events')
.header('Prefer','outlook.timezone="Pacific Standard Time"')
.select('subject,body,bodyPreview,organizer,attendees,start,end,location')
.get();
// GET https://graph.microsoft.com/v1.0/users/{user-id}/events
final Event events = graphClient.me().events()
.buildRequest(new HeaderOption("Prefer","outlook.timezone=\"Pacific Standard Time\""))
.select("Subject,Body,BodyPreview")
.get();
# GET https://graph.microsoft.com/v1.0/users/{user-id}/events
$userId = "71766077-aacc-470a-be5e-ba47db3b2e88"
$requestUri = "/v1.0/users/" + $userId + "/events"
$events = Invoke-GraphRequest -Method GET -Uri $requestUri `
-Headers @{ Prefer = "outlook.timezone=""Pacific Standard Time""" }
Importante
El SDK de Microsoft Graph para Go está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
El SDK de Microsoft Graph para Python está actualmente en versión preliminar. No se admite el uso de este SDK en producción.
# GET https://graph.microsoft.com/v1.0/users/{user-id}/events
request_config = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
headers={'Prefer': 'outlook.timezone="Pacific Standard Time"'},
)
events = asyncio.run(client.me
.events
.get(request_configuration=request_config))
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.