Почему используйте пакет SDK Для Microsoft Graph

Когда прокси-сервер разработки обнаруживает, что приложение выполняет запросы API Microsoft Graph без использования пакета SDK, он предлагает миграцию в пакет SDK. Это руководство существует, так как пакеты SDK Microsoft Graph значительно упрощают работу с API Microsoft Graph и помогают создавать более надежные приложения.

Преимущества пакетов SDK Microsoft Graph

Пакеты SDK Microsoft Graph предоставляют множество преимуществ при выполнении необработанных HTTP-вызовов.

Встроенная обработка проверки подлинности

Пакеты SDK интегрируются с библиотеками проверки подлинности, такими как MSAL (Microsoft Authentication Library), автоматически обрабатывая получение, обновление и управление токенами. Вам не нужно реализовать поток OAuth 2.0 вручную или беспокоиться об истечении срока действия токена.

Автоматическая логика повторных попыток для регулирования

Службы Microsoft 365 реализуют ограничение скорости для обеспечения надежности службы. Когда ваше приложение получает 429 Too Many Requests ответ, пакет SDK автоматически обрабатывает повторные попытки с соответствующими временными задержками, соблюдая заголовок Retry-After, возвращаемый Microsoft Graph.

Правильная обработка разбиения на страницы

Многие конечные точки Microsoft Graph возвращают результаты с разбивкой на страницы. Пакеты SDK предоставляют встроенные итераторы, которые прозрачно обрабатывают получение последующих страниц, поэтому вам не нужно вручную отслеживать @odata.nextLink значения и выполнять другие запросы.

Безопасность типов и IntelliSense

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

Поддержка пакетной обработки

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

Дельта-запросы

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

Архитектура ПО промежуточного слоя для настройки

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

Согласованные шаблоны API

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

Что упускают необработанные HTTP-вызовы

При выполнении необработанных http-вызовов к Microsoft Graph необходимо реализовать несколько критически важных функций самостоятельно.

Реализация логики повторных попыток вручную

Без пакета SDK необходимо реализовать логику повторных попыток для обработки 429 responses, включая:

• Анализ значений заголовков Retry-After
• Реализация экспоненциальной обратной передачи
• Обработка различных сценариев ошибок
• Избегайте повторных штормов под тяжелой нагрузкой

Обработка разбиения на страницы вручную

Вам нужно:

• Проверьте каждый ответ для @odata.nextLink
• Создание дополнительных запросов для каждой страницы
• Сводные результаты по страницам
• Обработка частичных сбоев во время разбиения на страницы

Типовая заготовка обработки ошибок

Microsoft Graph может возвращать различные ответы на ошибки с различными структурами. Без пакета SDK необходимо:

• Анализ тел ответа на ошибки
• Обработка различных кодов состояния HTTP соответствующим образом
• Извлечение значимых сообщений об ошибках для журналирования
• Реализация резервного поведения для непредвиденных ошибок

Сложность проверки подлинности

Для управления проверкой подлинности вручную требуется:

• Реализация потоков OAuth 2.0
• Хранение и защита токенов
• Обработка обновления токена перед истечением срока действия
• Управление различными сценариями проверки подлинности (делегированные разрешения и разрешения приложения)

Доступные пакеты SDK

Корпорация Майкрософт предоставляет официальные пакеты SDK для следующих платформ:

Альтернативные варианты использования пакета SDK

Хотя пакеты SDK рекомендуются в большинстве случаев, существуют случаи, когда другие подходы могут быть лучше.

Клиент, созданный Kiota

Если приложение использует только небольшое подмножество API Microsoft Graph, рассмотрите возможность создания клиента с Kiota вместо использования полного пакета SDK. Kiota создает легковесный, строго типизированный клиент, адаптированный к конкретным API, которые вам необходимы, уменьшая объем зависимостей, при этом сохраняя типобезопасность и построение запросов.

Минимальное использование API

Если вы пишете быстрый скрипт или инструмент, который делает только несколько вызовов API, затраты на настройку пакета SDK могут быть не оправданы. В таких случаях прямые HTTP-вызовы могут быть проще. Однако вам по-прежнему нужно самостоятельно обрабатывать ответы на проверку подлинности и ошибки , что может быстро добавить сложность даже для простых сценариев.

Неподдерживаемый язык

Если вы используете язык программирования, который не имеет официального пакета SDK, необходимо выполнить прямые HTTP-вызовы. Вы также можете использовать Kiota для создания клиента для вашего языка, если Kiota поддерживает его.

Если пакет SDK еще не поддерживает определенную функцию

Microsoft Graph постоянно добавляет новые возможности. Иногда новый API или компонент может не иметь простой API в пакете SDK немедленно. В большинстве случаев пакет SDK по-прежнему можно использовать для выполнения произвольных запросов с помощью строки пути, которая дает преимущества ПО промежуточного слоя пакета SDK (проверка подлинности, повторные попытки, ведение журнала) без необходимости вводить построители запросов. Если пакет SDK вообще не поддерживает запрос, вы можете вернуться к прямым HTTP-вызовам до добавления поддержки пакета SDK.

Среды с учетом производительности

В таких сценариях, как бессерверные функции или пограничные вычисления, где важны время холодного запуска и размер пакета, более легкий подход с использованием клиентов, созданных в Kiota, или прямых HTTP-вызовов может быть более подходящим.

Дальнейшие шаги

Узнайте, как обновить приложение для использования пакета SDK Microsoft Graph:

Связанный контент

• Общие сведения о пакете SDK для Microsoft Graph
• Выбор поставщика проверки подлинности Microsoft Graph
• Установка пакета SDK Microsoft Graph
• Рекомендации по работе с Microsoft Graph