Microsoft Graph или устаревшие конечные точки REST: руководство по принятию решений до 2026 года

Вопрос немного неверен

Любой, кто подключает приложение к сервисам Microsoft 365, Entra ID, Teams или Outlook, рано или поздно сталкивается с вопросом вроде «REST API или Microsoft Graph?». Кажется, что это разумный выбор между двумя вариантами, но на самом деле это не совсем так. Сам Microsoft Graph является REST API. Обычно люди имеют в виду следующее:

Стоит ли продолжать использовать старые REST-концовки для отдельных сервисов (Azure AD Graph, Outlook REST API, SharePoint REST, EWS и т. д.) или перейти на единый API Microsoft Graph?

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

Упорядочивание названий

REST — это архитектурный стиль, а не продукт, который устанавливают. API, использующее HTTP-действия вроде GET, POST, PATCH и DELETE, обращающееся к ресурсам по их URL и обычно обменивающееся данными в формате JSON, может с полным основанием считаться RESTful. Согласно этому определению Microsoft Graph, Azure AD Graph, устаревший Outlook REST API и SharePoint REST относятся к этой категории.

Microsoft Graph — это единый REST API, охватывающий Microsoft 365 и Entra ID. Не нужно переключаться между разными конечными точками: одной для почты, другой для файлов и третьей для данных каталогов. Всё находится по адресу https://graph.microsoft.com/: пользователи, группы, почта, календари, чаты в Teams, файлы, уведомления об угрозах безопасности, а также ИИ-агенты.

Поэтому полезным сравнением является единый Graph по сравнению с устаревшими, специфичными для отдельных сервисов REST-интерфейсами. То, в каком состоянии находятся эти устаревшие API сейчас, имеет большое значение, поскольку ситуация быстро менялась за прошедший год.

Что будет работать в 2026 году

Если какие-либо из ваших ресурсов всё ещё обращаются к graph.windows.net, вы уже опаздываете; начиная с середины июля 2026 года эта возможность исчезнет в течение нескольких недель. Старый REST API Outlook отсутствует уже более двух лет. Доступ сторонних приложений к Exchange Online через EWS будет прекращён этой осенью. Почти все аргументы, которые раньше оправдывали использование нативных REST-эндпоинтов, либо уже устарели, либо вот-вот устареют.

Microsoft уже неоднократно изменяла эти сроки, поэтому перед планированием миграции обязательно уточните актуальные дедлайны на сайте Microsoft Learn. Однако общая тенденция не менялась на протяжении многих лет: всё сосредотачивается вокруг Graph.

Graph по сравнению с устаревшими эндпоинтами

В повседневной работе наиболее важны три различия.

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

За более чем десять лет существования этой технологии накопилось множество вариантов аутентификации: Basic Auth, NTLM, Kerberos, а также Azure Access Control Service, от которого зависели дополнения SharePoint. Для задач Microsoft 365 все они были заменены. Graph всегда принимал только OAuth 2.0 через Microsoft Entra ID. Это обеспечивает один способ получения токенов, одну модель разрешений и одно место для аудита того, кто может получить доступ к чему. Это улучшает безопасность для администраторов, а не только предоставляет более удобный API для разработчиков.

Запросы и группировка

Один запрос к Graph, подобный приведённому ниже, может фильтровать, обрабатывать и отображать постранично почту за один запрос:

GET https://graph.microsoft.com/v1.0/me/messages
    ?$select=subject,receivedDateTime,from
    &$filter=receivedDateTime ge 2026-07-01T00:00:00Z
    &$top=25
    &$orderby=receivedDateTime desc

При работе с более старыми, менее гибкими конечными точками для получения того же результата часто требовалось несколько ограниченных запросов или фильтрации на стороне клиента. С использованием параметра $batch можно объединить до 20 независимых операций в один HTTP-запрос, смешивая операции чтения и записи для совершенно разных типов ресурсов.

Ограничение скорости

Graph применяет несколько ограничений одновременно: по приложению для всех арендаторов, по арендатору для всех приложений и по приложению внутри одного арендатора. Конкретные цифры различаются в зависимости от сервиса — почта, файлы, каталоги и чаты в Teams имеют свои собственные лимиты. Как только будет достигнут любой из лимитов, возвращается код 429 Too Many Requests вместе с заголовком Retry-After, указывающим, сколько времени следует ждать. По сравнению с устаревшими API, где ограничения часто не описывались и их приходилось выяснять в процессе работы, это значительный прогресс. Совет остается актуальным: используйте $select, чтобы загружать только необходимые поля, предпочитайте групповые и дельта-запросы опросам, и всегда соблюдайте указание Retry-After, а не сразу повторять попытку.

Когда другие инструменты всё ещё имеют смысл

Graph пока не охватывает всё, и в некоторых случаях действительно требуется другой API.

• Подробное управление сайтом SharePoint. Полная информация о уровнях разрешений, некоторые операции с группами сайтов, а также части управления схемами типов контента и списков доступны только в SharePoint REST по адресу _api/web/.... В зрелых проектах SharePoint повседневная работа с файлами, списками и дисками обычно выполняется с использованием Graph, а SharePoint REST применяется лишь там, где это необходимо.
• Веб-части SPFx. Среда выполнения SharePoint Framework уже предоставляет готовый контекст SharePoint REST, поэтому для настройки внутри страницы это часто самый простой способ, хотя та же веб-часть может использовать и Graph.

Exchange Server на предприятии. Ограничение, вступающее в силу в октябре 2026 года, касается только Exchange Online, поэтому EWS продолжает работать с Exchange на предприятии. Для полностью локальной почтовой системы реальным выбором остаются EWS или миграция сначала в Exchange Online.

Крупные одноразовые задачи администрирования. Массовая очистка разрешений, подготовка отчетов для абонентов и масштабное создание сайтов часто выполняются с помощью более сложных инструментов, таких как PnP PowerShell, который внутри себя использует как Graph, так и SharePoint REST.

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

Как принять решение

Оцените любую новую интеграцию с помощью следующих вопросов:

1. Это новая версия приложения? Используйте Microsoft Graph. Новые функции сначала появляются там, и это единственная технология, в которую Microsoft продолжает вкладывать ресурсы.
2. Приложение, уже существующее, использует Azure AD Graph, Outlook REST API или дополнения SharePoint на основе ACS? Outlook REST и ACS уже вышли из активного развития, а Azure AD Graph будет устаревшим 31 июля 2026 года. Рассматривайте это как срочную задачу.
3. Приложение от стороннего разработчика использует EWS для взаимодействия с Exchange Online? Microsoft начнет блокировать такие запросы 1 октября 2026 года. Начните переход на конечные точки почты и календаря Graph уже сейчас.
4. Вам нужна функция SharePoint, которой пока нет в Graph? Для таких запросов используйте SharePoint REST, а для всего остального — Graph. Сначала ознакомьтесь с документацией SharePoint-in-Graph, поскольку список отсутствующих функций постоянно сокращается.

Является среда доступна только локально? EWS и другие протоколы локальной среды по-прежнему работают там. Microsoft Graph ориентирован прежде всего на облачную среду и не может напрямую подключаться к локальным серверам Exchange или SharePoint.

Для практически всех это сводится к одному правилу: используйте Microsoft Graph, если у вас нет конкретной, задокументированной причины этого не делать.

Та же самая заявка — раньше и сейчас

Вот устаревший запрос Outlook REST v2.0, показанный исключительно в целях сравнения:

GET https://outlook.office.com/api/v2.0/me/messages
Authorization: Bearer {token}

С марта 2024 года этот конечный пункт возвращает ответ HTTP 410 Gone. Версия запроса в формате Graph выглядит следующим образом:

GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,from,receivedDateTime&$top=10
Authorization: Bearer {token}

REST-интерфейс SharePoint, который по-прежнему поддерживается, считывает элементы списка следующим образом:

GET https://{tenant}.sharepoint.com/sites/{site}/_api/web/lists/getbytitle('Documents')/items
Authorization: Bearer {token}
Accept: application/json;odata=verbose

Там, где Graph поддерживает ту же операцию, вызов будет выглядеть так:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items
Authorization: Bearer {token}

Механизмы HTTP остаются одинаковыми в обеих эпохах. Graph добавляет единый базовый URL, единую модель аутентификации и единые правила формата JSON, независимо от того, с каким именно сервисом Microsoft 365 вы взаимодействуете.

Миграция с устаревшего API

Если вы только что поняли, что что-то в вашем тенанте всё ещё зависит от устаревающего API, ознакомьтесь с этим списком:

1. Узнайте, что на самом деле использует это API. Entra предлагает два рекомендуемых варианта — «Миграция приложений» и «Миграция сервисных принципалов», которые показывают реальное использование Azure AD Graph в вашем тенанте за последние 30 дней. Это значительно лучше, чем пытаться догадаться на основе исходного кода.
2. Явно сопоставьте разрешения. Устаревшие разрешения не переводятся один к одному в диапазоны Graph. Ориентируйтесь на официальные справочники Microsoft по сопоставлению разрешений, вместо того чтобы предполагать, что два диапазона с похожими названиями эквивалентны.
3. Перенесите механизм аутентификации в MSAL. Все, что всё ещё использует старую библиотеку аутентификации Azure AD (ADAL), требует отдельной миграции, поскольку поддержка ADAL прекращена уже много лет.
4. Меняйте SDK, а не только URL. Официальные Graph SDK для .NET, JavaScript и TypeScript, Python, Java, Go и PowerShell автоматически обрабатывают группировку запросов, повторные попытки и пагинацию. Не пишите вручную простые HTTP-запросы, если только это действительно не необходимо.
5. Будьте осторожны с бета-версиями. Если та или иная функция доступна только через конечную точку Graph beta, её интерфейс может измениться без предупреждения. Либо подготовьтесь к этому, либо дождитесь её полной доступности.
6. Обнаруживайте ошибки 429 на этапе тестирования. Проводите нагрузочные тесты с реалистичным объёмом запросов, чтобы вы столкнулись с ограничениями скорости раньше, чем это сделают ваши пользователи.
7. Запишите реальную дату окончания в свой календарь и проверьте её в официальной документации Microsoft непосредственно перед тем, как полагаться на неё. Эти даты уже менялись раньше, поэтому считайте любую дату, полученную из внешних источников, включая эту страницу, предварительной.

Graph — это также место управления агентами ИИ

Есть ещё одна причина, по которой разрыв продолжает увеличиваться. Graph превращается в плоскость управления экосистемой агентов ИИ Microsoft. В 2026 году Microsoft добавила конечные точки Graph для управления агентами и приложениями Microsoft 365 Copilot, ведения учёта агентов и получения более подробных отчётов об использовании Copilot, а также функций, связанных с более новыми лицензиями, такими как Agent 365. Ничего из этого нет в Azure AD Graph, Outlook REST или EWS, и никогда не появится. Если ваша организация планирует развивать возможности Copilot или создавать собственных агентов, это ещё один путь, который ведёт только к Graph.

Что это означает для вас

На вопрос, затронутый в заголовке, в 2026 году существует довольно четкий ответ:

• Начинаете что-то новое в Microsoft 365 или Entra ID? Используйте Microsoft Graph. Больше нет ситуаций, когда новый проект следует запускать с помощью специфического REST API устаревшего сервиса.
• Обслуживаете старую интеграцию? Сравните её с таблицей статусов выше. Если она связана с Azure AD Graph, Outlook REST, дополнениями SharePoint на основе ACS или доступом через EWS от сторонних поставщиков, у вас есть сроки, причем некоторые из них уже близки.
• В Graph отсутствует какая-то функция SharePoint? Для этого отдельного запроса используйте SharePoint REST, а всё остальное оставьте в Graph.

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