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
user = await graph_client.me.get()
// GET https://graph.microsoft.com/v1.0/me
const user = await graphClient.api('/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, 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
final User user = graphClient.me().get( requestConfiguration -> {
requestConfiguration.queryParameters.select = new String[] {"displayName", "jobTitle"};
});
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
// Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetQueryParameters
$query = new UserItemRequestBuilderGetQueryParameters(
select: ['displayName', 'jobTitle']);
// Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration
$config = new UserItemRequestBuilderGetRequestConfiguration(
queryParameters: $query);
/** @var Models\User $user */
$user = $graphClient->me()
->get($config)
->wait();
# 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
# GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
# msgraph.generated.users.item.user_item_request_builder
query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
select=['displayName', 'jobTitle']
)
config = RequestConfiguration(
query_parameters=query_params
)
user = await graph_client.me.get(config)
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
const user = await graphClient
.api('/me')
.select(['displayName', 'jobTitle'])
.get();
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.
El objeto devuelto al recuperar una lista de entidades probablemente será 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();
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
result, _ := graphClient.Me().Messages().
ByMessageId(messageId).Get(context.Background(), nil)
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
final Message message = graphClient.me().messages().byMessageId(messageId).get();
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
/** @var Models\Message $message */
$message = $graphClient->me()
->messages()
->byMessageId($messageId)
->get()
->wait();
# GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
# message_id is a string containing the id property of the message
message = await graph_client.me.messages.by_message_id(message_id).get()
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
const message = await graphClient.api(`/me/messages/${messageId}`).get();
Uso de $expand para acceder a entidades relacionadas
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"]);
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// import github.com/microsoftgraph/msgraph-sdk-go/users
expand := users.ItemMessagesMessageItemRequestBuilderGetQueryParameters{
Expand: []string{"attachments"},
}
options := users.ItemMessagesMessageItemRequestBuilderGetRequestConfiguration{
QueryParameters: &expand,
}
// messageId is a string containing the id property of the message
result, _ := graphClient.Me().Messages().
ByMessageId(messageId).Get(context.Background(), &options)
// GET
// https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
final Message message = graphClient.me().messages().byMessageId(messageId).get( requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String[] {"attachments"};
});
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
// Microsoft\Graph\Generated\Users\Item\Messages\Item\MessageItemRequestBuilderGetQueryParameters
$query = new MessageItemRequestBuilderGetQueryParameters(
expand: ['attachments']
);
// Microsoft\Graph\Generated\Users\Item\Messages\Item\MessageItemRequestBuilderGetRequestConfiguration
$config = new MessageItemRequestBuilderGetRequestConfiguration(
queryParameters: $query);
/** @var Models\Message $message */
$message = $graphClient->me()
->messages()
->byMessageId($messageId)
->get($config)
->wait();
# 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
# GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
# message_id is a string containing the id property of the message
# msgraph.generated.users.item.messages.item.message_item_request_builder
query_params = MessageItemRequestBuilder.MessageItemRequestBuilderGetQueryParameters(
expand=['attachments']
)
config = RequestConfiguration(
query_parameters=query_params
)
message = await graph_client.me.messages.by_message_id(message_id).get(config)
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
const message = await graphClient
.api(`/me/messages/${messageId}`)
.expand('attachments')
.get();
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();
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
err := graphClient.Me().Messages().
ByMessageId(messageId).Delete(context.Background(), nil)
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
graphClient.me().messages().byMessageId(messageId).delete();
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
$graphClient->me()
->messages()
->byMessageId($messageId)
->delete()
->wait();
# DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
# message_id is a string containing the id property of the message
await graph_client.me.messages.by_message_id(message_id).delete()
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
await graphClient.api(`/me/messages/${messageId}`).delete();
Creación de una nueva entidad con POST
Para obtener un estilo fluido y SDK basados en plantillas, se pueden agregar nuevos elementos a las colecciones con 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);
// POST https://graph.microsoft.com/v1.0/me/calendars
calendar := models.NewCalendar()
name := "Volunteer"
calendar.SetName(&name)
result, _ := graphClient.Me().Calendars().Post(context.Background(), calendar, nil)
// POST https://graph.microsoft.com/v1.0/me/calendars
final Calendar calendar = new Calendar();
calendar.setName("Volunteer");
final Calendar newCalendar = graphClient.me().calendars().post(calendar);
// POST https://graph.microsoft.com/v1.0/me/calendars
$calendar = new Models\Calendar();
$calendar->setName('Volunteer');
/** @var Models\Calendar $newCalendar */
$newCalendar = $graphClient->me()
->calendars()
->post($calendar)
->wait();
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);
// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
final Team team = new Team();
final TeamFunSettings funSettings = new TeamFunSettings();
funSettings.setAllowGiphy(true);
funSettings.setGiphyContentRating(GiphyRatingType.Strict);
team.setFunSettings(funSettings);
// teamId is a string containing the id property of the team
graphClient.teams().byTeamId(teamId).patch(team);
// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
$funSettings = new Models\TeamFunSettings();
$funSettings->setAllowGiphy(true);
$funSettings->setGiphyContentRating(
new Models\GiphyRatingType(Models\GiphyRatingType::STRICT));
$team = new Models\Team();
$team->setFunSettings($funSettings);
// $teamId is a string containing the id property of the team
$graphClient->teams()
->byTeamId($teamId)
->patch($team);
# PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
# msgraph.generated.models.team_fun_settings.TeamFunSettings
fun_settings = TeamFunSettings()
fun_settings.allow_giphy = True
# msgraph.generated.models.giphy_rating_type
fun_settings.giphy_content_rating = GiphyRatingType.Strict
# msgraph.generated.models.team.Team
team = Team()
team.fun_settings = fun_settings
# team_id is a string containing the id property of the team
await graph_client.teams.by_team_id(team_id).patch(team)
// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
const team: Team = {
funSettings: {
allowGiphy: true,
giphyContentRating: 'strict',
},
};
// teamId is a string containing the id property of the team
await graphClient.api(`/teams/${teamId}`).update(team);
Uso de encabezados HTTP para controlar el comportamiento de las solicitudes
Puede adjuntar encabezados personalizados a una solicitud mediante la Headers colecció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
final EventCollectionResponse events = graphClient.me().events().get( requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "outlook.timezone=\"Pacific Standard Time\"");
});
// GET https://graph.microsoft.com/v1.0/me/events
// Microsoft\Graph\Generated\Users\Item\Events\EventsRequestBuilderGetRequestConfiguration
$config = new EventsRequestBuilderGetRequestConfiguration(
headers: ['Prefer' => 'outlook.timezone="Pacific Standard Time"']
);
/** @var Models\EventCollectionResponse $events */
$events = $graphClient->me()
->events()
->get($config)
->wait();
# 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""" }
# GET https://graph.microsoft.com/v1.0/me/events
# msgraph.generated.users.item.events.events_request_builder
config = RequestConfiguration()
config.headers.add('Prefer', 'outlook.timezone="Pacific Standard Time"')
events = await graph_client.me.events.get(config)
// GET https://graph.microsoft.com/v1.0/me/events
const events = await graphClient
.api('/me/events')
.header('Prefer', 'outlook.timezone="Pacific Standard Time"')
.get();
Proporcionar parámetros de consulta personalizados
En el caso de los SDK que admiten el estilo fluido, puede proporcionar valores de parámetros de consulta personalizados mediante el QueryParameters objeto . 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.
Microsoft Graph proporciona acceso a los datos almacenados en servicios de Microsoft 365. En este módulo, aprenderá a acceder a datos de Microsoft 365 para mostrar el calendario predeterminado de un usuario en una aplicación de JavaScript mediante API y SDK de Microsoft Graph. Para asegurarse de que la aplicación web solo muestra lo que es inmediatamente relevante para el usuario, accederá y mostrará las repeticiones y las instancias de eventos durante un período determinado.