The Microsoft Graph SDK service libraries provide a client class to use as the starting point for creating all API requests. There are two styles of client class: one uses a fluent interface to create the request (for example, client.Users["user-id"].Manager) and the other accepts a path string (for example, api("/users/user-id/manager")). When you have a request object, you can specify various options, such as filtering and sorting, and finally, you select the type of operation you want to perform.
There's also the Microsoft Graph PowerShell SDK, which has no client class. Instead, all requests are represented as PowerShell commands. For example, to get a user's manager, the command is Get-MgUserManager. For more information on finding commands for API calls, see Navigating the Microsoft Graph PowerShell SDK.
Read information from Microsoft Graph
To read information from Microsoft Graph, you first need to create a request object and then run the GET method on the request.
# GET https://graph.microsoft.com/v1.0/users/{user-id}$userId = "71766077-aacc-470a-be5e-ba47db3b2e88"$user = Get-MgUser -UserId$userId
Python
# GET https://graph.microsoft.com/v1.0/me
user = await graph_client.me.get()
TypeScript
// GET https://graph.microsoft.com/v1.0/meconst user = await graphClient.api('/me').get();
Use $select to control the properties returned
When retrieving an entity, not all properties are automatically retrieved; sometimes, they need to be explicitly selected. Also, returning the default set of properties isn't necessary in some scenarios. Selecting just the required properties can improve the performance of the request. You can customize the request to include the $select query parameter with a list of properties.
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitlefinal User user = graphClient.me().get( requestConfiguration -> {
requestConfiguration.queryParameters.select = new String[] {"displayName", "jobTitle"};
});
PHP
// 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();
PowerShell
# 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
Python
# 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)
TypeScript
// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitleconst user = await graphClient
.api('/me')
.select(['displayName', 'jobTitle'])
.get();
Retrieve a list of entities
Retrieving a list of entities is similar to retrieving a single entity, except other options exist for configuring the request. The $filter query parameter can reduce the result set to only those rows that match the provided condition. The $orderby query parameter requests that the server provide the list of entities sorted by the specified properties.
Note
Some requests for Microsoft Entra resources require the use of advanced query capabilities. If you get a response indicating a bad request, unsupported query, or a response that includes unexpected results, including the $count query parameter and ConsistencyLevel header may allow the request to succeed. For details and examples, see Advanced query capabilities on directory objects.
The object returned when retrieving a list of entities will likely be a paged collection. For details about how to get the complete list of entities, see paging through a collection.
Access an item of a collection
For SDKs that support a fluent style, collections of entities can be accessed using an array index. For template-based SDKs, it's sufficient to embed the item identifier in the path segment following the collection. For PowerShell, identifiers are passed as parameters.
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}// messageId is a string containing the id property of the messagevar message = await graphClient.Me.Messages[messageId]
.GetAsync();
Go
// 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)
Java
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}// messageId is a string containing the id property of the messagefinal Message message = graphClient.me().messages().byMessageId(messageId).get();
PHP
// 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()
TypeScript
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}// messageId is a string containing the id property of the messageconst message = await graphClient.api(`/me/messages/${messageId}`).get();
Use $expand to access related entities
You can use the $expand filter to request a related entity or collection of entities at the same time that you request the main entity.
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments// messageId is a string containing the id property of the messagevar message = await graphClient.Me.Messages[messageId]
.GetAsync(requestConfig =>
requestConfig.QueryParameters.Expand =
["attachments"]);
Go
// 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)
Java
// GET// https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments// messageId is a string containing the id property of the messagefinal Message message = graphClient.me().messages().byMessageId(messageId).get( requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String[] {"attachments"};
});
PHP
// 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();
PowerShell
# 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
Python
# 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)
TypeScript
// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments// messageId is a string containing the id property of the messageconst message = await graphClient
.api(`/me/messages/${messageId}`)
.expand('attachments')
.get();
Delete an entity
Delete requests are constructed in the same way as requests to retrieve an entity, but use a DELETE request instead of a GET.
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}// messageId is a string containing the id property of the messageawait graphClient.Me.Messages[messageId]
.DeleteAsync();
Go
// 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)
Java
// 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();
PHP
// 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 messageawait graph_client.me.messages.by_message_id(message_id).delete()
TypeScript
// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}// messageId is a string containing the id property of the messageawait graphClient.api(`/me/messages/${messageId}`).delete();
Creating a new entity with POST
For fluent style and template-based SDKs, new items can be added to collections with a POST method. For PowerShell, a New-* command accepts parameters that map to the entity to add. The created entity is returned from the call.
// POST https://graph.microsoft.com/v1.0/me/calendarsvar calendar = new Calendar
{
Name = "Volunteer",
};
var newCalendar = await graphClient.Me.Calendars
.PostAsync(calendar);
Go
// 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)
Java
// POST https://graph.microsoft.com/v1.0/me/calendarsfinal Calendar calendar = new Calendar();
calendar.setName("Volunteer");
final Calendar newCalendar = graphClient.me().calendars().post(calendar);
PHP
// 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();
PowerShell
# POST https://graph.microsoft.com/v1.0/users/{user-id}/calendars$userId = "71766077-aacc-470a-be5e-ba47db3b2e88"New-MgUserCalendar -UserId$userId -Name"Volunteer"
Most updates in Microsoft Graph are performed using a PATCH method; therefore, it's only necessary to include the properties you want to change in the object you pass.
// 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 teamawait 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);
PHP
// 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 teamawait graph_client.teams.by_team_id(team_id).patch(team)
TypeScript
// 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 teamawait graphClient.api(`/teams/${teamId}`).update(team);
Use HTTP headers to control request behavior
You can attach custom headers to a request using the Headers collection. For PowerShell, adding headers is only possible with the Invoke-GraphRequest method. Some Microsoft Graph scenarios use custom headers to adjust the behavior of the request.
// GET https://graph.microsoft.com/v1.0/me/eventsfinal EventCollectionResponse events = graphClient.me().events().get( requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "outlook.timezone=\"Pacific Standard Time\"");
});
PHP
// 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();
PowerShell
# 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""" }
Python
# 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)
TypeScript
// GET https://graph.microsoft.com/v1.0/me/eventsconst events = await graphClient
.api('/me/events')
.header('Prefer', 'outlook.timezone="Pacific Standard Time"')
.get();
Provide custom query parameters
For SDKs that support the fluent style, you can provide custom query parameter values using the QueryParameters object. For template-based SDKs, the parameters are URL-encoded and added to the request URI. For PowerShell and Go, defined query parameters for a given API are exposed as parameters to the corresponding command.
Microsoft Graph provides access to data stored across Microsoft 365 services. In this module, you'll learn how to access Microsoft 365 data to show a user's default calendar in a JavaScript application by using Microsoft Graph APIs and SDKs. To make sure that the web app only shows what's immediately relevant to the user, you'll access and display occurrences and instances of events for a given period.