Вызовы 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 = new string[] { "displayName", "jobTitle"};
    });

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

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

Примечание.

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

// GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

var messages = await graphClient.Me.Messages
    .GetAsync( requestConfig => 
                {
                    requestConfig.QueryParameters.Select = new string[] { "subject", "sender"};
                    requestConfig.QueryParameters.Filter = "<filter condition>";
                    requestConfig.QueryParameters.Orderby = new string[] { "receivedDateTime" };
                });

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

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

Для пакетов SDK, поддерживающих стиль fluent, доступ к коллекциям сущностей можно получить с помощью индекса массива. Для пакетов SDK на основе шаблонов достаточно внедрить идентификатор элемента в сегмент пути после коллекции. В PowerShell идентификаторы передаются в качестве параметров.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy..";
var message = await graphClient.Me.Messages[messageId]
    .GetAsync();

Фильтр можно использовать для $expand запроса связанной сущности или коллекции сущностей одновременно с запросом основной сущности.

// 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" });

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

Запросы на удаление создаются так же, как запросы для получения сущности, но используют DELETE запрос вместо GET.

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy...";
await graphClient.Me.Messages[messageId]
    .DeleteAsync();

Создание запроса POST для создания сущности

Для пакетов SDK, поддерживающих стиль fluent, новые элементы можно добавлять в коллекции с помощью Add метода . Для пакетов 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
    }
};

var teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";

await graphClient.Teams[teamId]
    .PatchAsync(team);

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

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

//  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"};
                });

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

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

//GET https://graph.microsoft.com/v1.0/me/calendarView

var calendar = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration => 
    {
        requestConfiguration.QueryParameters.StartDateTime = "2020-12-01T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime = "2020-12-30T00:00:00Z";
    });