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

Рекомендации по работе с 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.

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

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

  • Применение минимальных прав. Предоставляйте пользователям и приложениям лишь разрешение с наименьшими правами, необходимое для вызова 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.3 или 1.2 для поддержки всех возможностей 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 требуются при сообщении о проблемах на сайте Вопросы и ответы Майкрософт или службе поддержки Майкрософт.