Библиотеки служб пакета SDK для Microsoft Graph предоставляют класс клиента, который будет использоваться в качестве отправной точки для создания всех запросов API. Существует два стиля клиентского класса: один использует интерфейс fluent для создания запроса (например, client.Users["user-id"].Manager), а другой принимает строку пути (например, api("/users/user-id/manager")). При наличии объекта запроса можно указать различные параметры, такие как фильтрация и сортировка, и, наконец, выбрать тип операции, которую вы хотите выполнить.
# 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();
Используйте $select для управления возвращаемыми свойствами
При получении сущности не все свойства извлекаются автоматически; иногда их необходимо явно выбрать. Кроме того, возвращать набор свойств по умолчанию не требуется в некоторых сценариях. Выбор только необходимых свойств может повысить производительность запроса. Вы можете настроить запрос, включив $select параметр запроса со списком свойств.
// 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();
Получение списка сущностей
Получение списка сущностей аналогично получению одной сущности, за исключением других параметров для настройки запроса. Параметр $filter запроса может уменьшить результирующий набор только в тех строках, которые соответствуют предоставленному условию. Параметр $orderby запроса запрашивает, чтобы сервер предоставил список сущностей, отсортированных по указанным свойствам.
Примечание.
Для некоторых запросов Microsoft Entra ресурсов требуется использование расширенных возможностей запросов. Если вы получите ответ, указывающий на неправильный запрос, неподдерживаемый запрос или ответ, содержащий непредвиденные результаты, включая $count параметр запроса и ConsistencyLevel заголовок, может позволить запросу выполнить успешное выполнение. Дополнительные сведения и примеры см. в разделе Расширенные возможности запросов к объектам каталогов.
Объект, возвращаемый при получении списка сущностей, скорее всего, будет страничной коллекцией. Дополнительные сведения о том, как получить полный список сущностей, см. в разделе Разбиение по страницам по коллекции.
Доступ к элементу коллекции
Для пакетов SDK, поддерживающих стиль fluent, доступ к коллекциям сущностей можно получить с помощью индекса массива. Для пакетов SDK на основе шаблонов достаточно внедрить идентификатор элемента в сегмент пути, следующий за коллекцией. В PowerShell идентификаторы передаются в качестве параметров.
// 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();
Использование $expand для доступа к связанным сущностям
Фильтр можно использовать для $expand запроса связанной сущности или коллекции сущностей в то же время, когда вы запрашиваете main сущность.
// 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();
Удаление сущности
Запросы на удаление создаются так же, как запросы для получения сущности, но используют DELETE запрос вместо 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();
Создание сущности с помощью POST
Для пакетов SDK на основе свободного стиля и шаблонов новые элементы можно добавлять в коллекции с помощью POST метода . В PowerShell команда принимает параметры, New-* сопоставляемые с добавляемой сущностью. Созданная сущность возвращается из вызова.
// 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();
Большинство обновлений в Microsoft Graph выполняется с помощью PATCH метода, поэтому необходимо только включить свойства, которые требуется изменить, в передаваемый объект.
// 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);
Использование заголовков HTTP для управления поведением запросов
Пользовательские заголовки можно вложить в запрос с помощью Headers коллекции. В PowerShell добавление заголовков возможно только с помощью Invoke-GraphRequest метода . В некоторых сценариях Microsoft Graph для настройки поведения запроса используются пользовательские заголовки.
// 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();
Предоставление настраиваемых параметров запроса
Для пакетов SDK, поддерживающих стиль fluent, можно указать пользовательские QueryParameters значения параметров запроса с помощью объекта . Для пакетов SDK на основе шаблонов параметры кодируются в формате URL-адреса и добавляются в URI запроса. Для PowerShell и Go определенные параметры запроса для заданного API предоставляются в качестве параметров для соответствующей команды.