Поделиться через


Вызовы API с помощью пакетов SDK Microsoft Graph

Библиотеки служб пакета SDK для Microsoft Graph предоставляют класс клиента, который будет использоваться в качестве отправной точки для создания всех запросов API. Существует два стиля клиентского класса: один использует интерфейс fluent для создания запроса (например, client.Users["user-id"].Manager), а другой принимает строку пути (например, api("/users/user-id/manager")). При наличии объекта запроса можно указать различные параметры, такие как фильтрация и сортировка, и, наконец, выбрать тип операции, которую вы хотите выполнить.

Существует также пакет SDK Для Microsoft Graph PowerShell, который не имеет клиентского класса. Вместо этого все запросы представлены в виде команд PowerShell. Например, чтобы получить диспетчер пользователя, команда имеет значение Get-MgUserManager. Дополнительные сведения о поиске команд для вызовов API см. в статье Навигация по пакету SDK Microsoft Graph PowerShell.

Чтение сведений из Microsoft Graph

Чтобы считывать сведения из Microsoft Graph, сначала необходимо создать объект запроса, а затем выполнить GET метод в запросе.

// GET https://graph.microsoft.com/v1.0/me
var user = await graphClient.Me
    .GetAsync();

Используйте $select для управления возвращаемыми свойствами

При получении сущности не все свойства извлекаются автоматически; иногда их необходимо явно выбрать. Кроме того, возвращать набор свойств по умолчанию не требуется в некоторых сценариях. Выбор только необходимых свойств может повысить производительность запроса. Вы можете настроить запрос, включив $select параметр запроса со списком свойств.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
var user = await graphClient.Me
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Select =
            ["displayName", "jobTitle"];
    });

Получение списка сущностей

Получение списка сущностей аналогично получению одной сущности, за исключением других параметров для настройки запроса. Параметр $filter запроса может уменьшить результирующий набор только в тех строках, которые соответствуют предоставленному условию. Параметр $orderby запроса запрашивает, чтобы сервер предоставил список сущностей, отсортированных по указанным свойствам.

Примечание.

Для некоторых запросов Microsoft Entra ресурсов требуется использование расширенных возможностей запросов. Если вы получите ответ, указывающий на неправильный запрос, неподдерживаемый запрос или ответ, содержащий непредвиденные результаты, включая $count параметр запроса и ConsistencyLevel заголовок, может позволить запросу выполнить успешное выполнение. Дополнительные сведения и примеры см. в разделе Расширенные возможности запросов к объектам каталогов.

// GET https://graph.microsoft.com/v1.0/me/messages?
// $select=subject,sender&$filter=subject eq 'Hello world'
var messages = await graphClient.Me.Messages
    .GetAsync(requestConfig =>
    {
        requestConfig.QueryParameters.Select =
            ["subject", "sender"];
        requestConfig.QueryParameters.Filter =
            "subject eq 'Hello world'";
    });

Объект, возвращаемый при получении списка сущностей, скорее всего, будет страничной коллекцией. Дополнительные сведения о том, как получить полный список сущностей, см. в разделе Разбиение по страницам по коллекции.

Доступ к элементу коллекции

Для пакетов 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();

Фильтр можно использовать для $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"]);

Удаление сущности

Запросы на удаление создаются так же, как запросы для получения сущности, но используют 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();

Создание сущности с помощью 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);

Обновление существующей сущности с помощью PATCH

Большинство обновлений в 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);

Использование заголовков HTTP для управления поведением запросов

Пользовательские заголовки можно вложить в запрос с помощью Headers коллекции. В PowerShell добавление заголовков возможно только с помощью Invoke-GraphRequest метода . В некоторых сценариях Microsoft Graph для настройки поведения запроса используются пользовательские заголовки.

// GET https://graph.microsoft.com/v1.0/me/events
var events = await graphClient.Me.Events
    .GetAsync(requestConfig =>
    {
        requestConfig.Headers.Add(
            "Prefer", @"outlook.timezone=""Pacific Standard Time""");
    });

Предоставление настраиваемых параметров запроса

Для пакетов SDK, поддерживающих стиль fluent, можно указать пользовательские QueryParameters значения параметров запроса с помощью объекта . Для пакетов SDK на основе шаблонов параметры кодируются в формате URL-адреса и добавляются в URI запроса. Для PowerShell и Go определенные параметры запроса для заданного API предоставляются в качестве параметров для соответствующей команды.

// GET https://graph.microsoft.com/v1.0/me/calendarView?
// startDateTime=2023-06-14T00:00:00Z&endDateTime=2023-06-15T00:00:00Z
var events = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.StartDateTime =
            "2023-06-14T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime =
            "2023-06-15T00:00:00Z";
    });