Рекомендации по работе с Microsoft Graph

  • Статья

В этой статье описаны рекомендации, которые можно применить, чтобы помочь приложениям максимально эффективно использовать Microsoft Graph, независимо от того, в том, что касается изучения Microsoft Graph, повышения производительности приложения или повышения надежности приложения для конечных пользователей.

Знакомство с API с помощью песочницы Graph

Самый простой способ ознакомиться с данными, доступными через Microsoft Graph, — использовать песочницу Graph. Песочница Graph позволяет создавать запросы REST (с полной поддержкой CRUD), адаптировать заголовки HTTP-запросов и просматривать ответы с данными. Песочница Graph также содержит примеры запросов, которые помогут вам приступить к работе.

Поэкспериментируйте с новыми API, прежде чем интегрировать их в приложение.

Аутентификация

Для доступа к данным с помощью Microsoft Graph приложению необходимо получить маркер доступа OAuth 2.0 и предоставить его службе Microsoft Graph в одном из следующих вариантов:

  • заголовок HTTP-запроса Authorization, в виде токена Bearer;
  • конструктор клиента Graph при использовании клиентской библиотеки Microsoft Graph.

Чтобы получить маркер доступа к Microsoft Graph, используйте API библиотеки проверки подлинности (Майкрософт) — MSAL.

Реализуя согласие и авторизацию в приложении, следуйте приведенным ниже рекомендациям.

  • Применение минимальных прав. Предоставляйте пользователям и приложениям лишь разрешение с наименьшими правами, необходимое для вызова API. Ознакомьтесь с разделом разрешений в статьях о методах (например, в статье Создание пользователя) и выберите минимальные разрешения. Например, если приложение будет читать только профиль вошедшего в настоящий момент пользователя, предоставьте разрешение User.Read вместо User.ReadBasic.All. Если приложение не читает календарь пользователя, не предоставляйте ему разрешение Calendars.Read. Полный список разрешений представлен в справочнике по разрешениям.

  • Используйте типы разрешений, подходящие для соответствующих сценариев. Избегайте использования одновременно разрешений приложений и делегированных разрешений в одном приложении. Если вы создаете интерактивное приложение, в котором присутствует вошедший пользователь, оно должно использовать делегированные разрешения. Однако если приложение работает без вошедшего пользователя (например, фоновая служба или управляющая программа), следует использовать разрешения приложений.

    Предостережение

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

  • Будьте внимательны при настройке приложения. Это непосредственно повлияет на работу пользователей и администраторов, а также на внедрение приложений и их безопасность. Примеры:

    • Название, логотип, домен, состояние проверки издателя, заявление о конфиденциальности и условия использования вашего приложения будут отображаться в запросе согласия и других интерфейсах. Внимательно настройте эти параметры, чтобы они были понятны конечным пользователям.
    • Учитывайте, кто будет предоставлять согласие вашему приложению — пользователи или администраторы, — и настройте запрашиваемые разрешения соответствующим образом.
    • Убедитесь, что вы понимаете разницу между статическим, динамическим и добавочным согласиями.

  • Учитывайте мультитенантные приложения. Помните, что у клиентов могут быть разные правила относительно приложений и согласия в разных состояниях. Примеры:

    • Администраторы клиентов могут запретить пользователям предоставлять согласие приложениям. В этом случае администратор должен предоставить согласие от имени своих пользователей.
    • Администраторы клиентов могут устанавливать специальные политики авторизации, например запрещать пользователям просматривать профили других пользователей или разрешать самостоятельное создание групп только определенным пользователям. В этом случае приложение должно уметь обрабатывать ошибку 403 Forbidden при работе от имени пользователя.

Эффективная обработка ответов

В зависимости от того, какие запросы отправляются в Microsoft Graph, приложения должны быть готовы обрабатывать различные ответы. Ниже представлены некоторые важные рекомендации, соблюдении которых обеспечит надежную работу приложения.

Разбивка на страницы

Запрашивая информацию из коллекции ресурсов, следует ожидать, что Microsoft Graph вернет набор результатов на нескольких страницах, так как размер страниц на стороне сервера ограничен. Если набор результатов занимает несколько страниц, Microsoft Graph возвращает в ответе свойство @odata.nextLink, содержащее URL-адрес следующей страницы результатов.

Допустим, нужно получить список сообщений вошедшего пользователя:

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

Ответ будет содержать свойство @odata.nextLink, если размер набора результатов превышает максимальный размер страницы на стороне сервера.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

Примечание.

Приложение всегда должно учитывать возможность разбивки ответов на страницы и использовать свойство @odata.nextLink, чтобы получить следующий разбитый на страницы набор результатов, пока не будут считаны все страницы результирующего набора. Последняя страница не будет содержать свойство @odata.nextLink. В запросе следующей страницы результатов в свойство @odata.nextLink следует включить полный URL-адрес, рассматривая его как непрозрачную строку.

Дополнительные сведения см. в этой статье.

Обработка ожидаемых ошибок

Приложение должно обрабатывать все ошибки (в диапазонах 400 и 500), но некоторым ожидаемым ошибкам и ответам следует уделять особое внимание. Они перечислены в приведенной ниже таблице.

Тема Код ошибки HTTP Рекомендация
У пользователя нет доступа 403 Эта ошибка может возникнуть в запущенном приложении, даже если ему были предоставлены необходимые разрешения через интерфейс согласия. В этом случае наиболее вероятно, что у вошедшего пользователя нет прав на доступ к запрашиваемому ресурсу. Приложение должно показывать вошедшему пользователю обычное сообщение "Отказано в доступе".
Не найдено 404 В некоторых случаях запрашиваемый ресурс может быть не найден. К примеру, ресурс может не существовать, так как он еще не был подготовлен (как, например, фотография пользователя) или был удален. Некоторые удаленные ресурсы можно полностью восстановить в течение 30 дней после удаления. К таким ресурсам относятся пользователи, группы и приложения, поэтому ваше приложение также должно это учитывать.
Регулирование 429 API могут регулировать количество запросов в любой момент по ряду причину, поэтому приложение всегда должно быть готово обрабатывать ответы 429. Эта ошибка включает поле Retry-After в заголовке HTTP-ответа. Самый быстрый способ избавиться от регулирования — отложить запросы с помощью задержки Retry-After. Дополнительные сведения см. в этой статье.
Служба недоступна 503 Скорее всего, служба занята. Следует применять ту же стратегию, что и при обработке ошибки 429. Кроме того, повторные запросы следует всегда выполнять через новое подключение HTTP.

Обработка будущих участников в изменяемых перечислениях

Добавление членов в существующие перечисления может нарушить работу приложений, уже использующих эти перечисления. Изменяемые перечисления — это механизм, который API Microsoft Graph использует для добавления новых членов в существующие перечисления без внесения каких-либо изменений в приложения.

У изменяемых перечислениях есть общий элемент sentinel под названием unknownFutureValue, который разграничит известные элементы, которые были определены в перечислении изначально, и неизвестные элементы, которые добавляются впоследствии или будут определены в будущем. Внутри организации известные элементы сопоставляются с числовыми значениями, которые меньше, чем элемент sentinel, а неизвестные элементы больше, чем элемент sentinel. В документации для изменяемого перечисления перечислены возможные значения строки в порядке возрастания: известные элементы, за которыми следуют unknownFutureValue, за которыми следуют неизвестные элементы. Как и в других типах перечисления, необходимо всегда ссылаться на элементы изменяемых перечислений по их значениям строк.

По умолчанию операция GET возвращает только известные элементы для свойств типов изменяемых перечислений, и приложение должно обрабатывать только известные элементы. Если вы разрабатываете приложение для обработки неизвестных элементов, вы можете отказаться от получения этих элементов с помощью заголовка HTTP-запроса Prefer:

Prefer: include-unknown-enum-members

Локальное хранение данных

В идеальном случае приложение должно вызывать Microsoft Graph для получения данных в реальном времени. Кэшировать данные или хранить их локально следует, только если это требуется для определенного сценария и если этот вариант использования предусмотрен условиями использованиями и политикой конфиденциальности, а также не противоречит условиям использования API Microsoft. В приложении также необходимо реализовать надлежащие политики хранения и удаления.

Оптимизация

Как правило, из соображений производительности и даже безопасности или конфиденциальности, следует получать только те данные, которые действительно необходимы приложению.

Использование проекций

Выбирайте только те свойства, которые действительно необходимы приложению. Это позволит сэкономить сетевой трафик и снизить нагрузку на приложение (и службу), связанную с обработкой данных.

Примечание.

Используйте параметр запроса $select, чтобы по запросу возвращались только свойства, необходимые приложению.

Например, при получении сообщений вошедшего пользователя можно указать, что необходимо вернуть только свойства from и subject:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

При выполнении запроса GET без использования $select для ограничения объема данных свойств Microsoft Graph включает свойство @microsoft.graph.tips , которое предоставляет рекомендации по использованию $select , аналогичное следующему сообщению:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Получение минимальных ответов

В случае некоторых операций, например PUT и PATCH (а в некоторых случаях — POST), если приложению не нужны полезные данные ответа, можно просить API возвращать минимальное количество данных. Обратите внимание, что некоторые службы уже возвращают ответ для операций 204 No Content PUT и PATCH.

Примечание.

Запрашивайте минимальное представление ответов, используя заголовок Prefer , для которого задано значение return=minimal, где поддерживается. Для операций создания этот заголовок может быть неуместным, так как ваше приложение может ожидать, что служба будет создана id для только что созданного объекта в ответе.

Отслеживание изменений: разностный запрос и уведомления веб-перехватчиков

Если приложению нужно знать об изменениях данных, вы можете получать уведомление веб-перехватчика при каждом их изменении. Это эффективнее, чем регулярные опросы.

Используйте уведомления веб-перехватчиков, чтобы получать push-уведомления при изменении данных.

Если приложение должно кэшировать или сохранять данные Microsoft Graph локально и поддерживать их в актуальном состоянии либо отслеживать изменения данных по каким-либо другим причинам, следует использовать разностный запрос. Это избавит приложение от необходимости лишних вычислений для получения данных, уже доступных приложению, уменьшит количество сетевого трафика и снизит вероятность достижения порога регулирования.

Используйте разностный запрос, чтобы эффективно поддерживать данные в актуальном состоянии.

Использование веб-перехватчиков вместе с разностным запросом

Как правило, веб-перехватчики и разностный запрос эффективнее работают вместе, так как при использовании разностного запроса необходимо подобрать подходящий интервал опроса. Если он слишком короткий, будет возвращаться много пустых ответов, что приведет к трате ресурсов. Если же он слишком длинный, ваши данные могут устареть. Используя уведомления веб-перехватчиков в качестве триггера для отправки разностных запросов, вы получаете преимущества обеих функций.

Используйте уведомления веб-перехватчиков в качестве триггера для отправки разностных запросов. Кроме того, следует убедиться, что в приложении задан предельный порог опроса на тот случай, если уведомлений не будет.

Пакетная обработка

Пакетная обработка JSON позволяет оптимизировать приложение, объединив несколько запросов в один объект JSON. Объединение отдельных запросов в один позволяет значительно снизить задержку в сети и сэкономить ресурсы подключения.

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

Надежность и поддержка

Чтобы обеспечить надежность и поддержку приложения следуйте приведенным ниже рекомендациям.

  • Используйте TLS 1.2 для поддержки всех возможностей Microsoft Graph. Дополнительные сведения о прекращении поддержки Microsoft Graph TLS 1.0 и 1.1 см. в статье Включение поддержки TLS 1.2 в среде.
  • Учитывайте срок жизни DNS и задайте соответствующий срок жизни для подключения. Это гарантирует доступность в случае отработки отказа.
  • Откройте подключения ко всем объявленным ответам DNS.
  • Обеспечьте создание уникального GUID и его отправку при каждом запросе REST Microsoft Graph. Это позволит Майкрософт быстрее изучить ошибки, если вы сообщите о проблеме с Microsoft Graph.
    • При каждом запросе Microsoft Graph должен создаваться уникальный GUID, а затем отправляться в заголовке HTTP-запроса client-request-id. Регистрируйте его в журналах приложения.
    • Всегда регистрируют и request-idDate из заголовков HTTP-ответов. Они, а также client-request-id требуются при сообщении о проблемах на сайте Вопросы и ответы Майкрософт или службе поддержки Майкрософт.