Microsoft Graph

Microsoft Graph — это RESTful API и платформа для доступа к данным и аналитике в облачных сервисах Microsoft 365, Azure Active Directory (Azure AD), Windows 10/11 и Enterprise Mobility + Security. Предоставляет единую программную модель для взаимодействия с такими продуктами, как Outlook, OneDrive, Teams, SharePoint, Excel, Planner, To Do, Power BI и другими.

Архитектура и принцип работы

Microsoft Graph построен на концепции единого графа данных, связывающего пользователей, группы, устройства, контент и действия. Вместо отдельных API для каждого сервиса (например, API Outlook или API SharePoint) Graph предоставляет унифицированную конечную точку https://graph.microsoft.com/v1.0/ и https://graph.microsoft.com/beta/ (для предварительных версий).

Основные компоненты

• RESTful API — запросы выполняются через HTTP-методы (GET, POST, PATCH, DELETE) с использованием форматов JSON или OData.
• Аутентификация и авторизация — основана на протоколе OAuth 2.0 и OpenID Connect. Для доступа требуется регистрация приложения в Azure AD, получение токена доступа и указание необходимых разрешений (делегированных или прикладных).
• Графовая модель — данные представлены как сущности (пользователи, сообщения, файлы, события) и связи между ними (например, «пользователь отправил сообщение», «файл находится в папке»).
• Пакет SDK — Microsoft предоставляет SDK для .NET, Java, JavaScript, Python, Go, PHP, Ruby и Swift, упрощающие работу с API.

Разрешения (Permissions)

Для доступа к данным через Microsoft Graph приложение должно запросить разрешения. Они делятся на два типа:

• Делегированные — приложение действует от имени вошедшего пользователя. Требуют согласия пользователя или администратора.
• Прикладные — приложение действует как служба без пользователя. Обычно требуют согласия администратора.

Примеры разрешений: User.Read (чтение профиля пользователя), Mail.Read (чтение почты), Files.ReadWrite.All (чтение и запись всех файлов).

Возможности

Microsoft Graph охватывает более 100 сервисов и предоставляет доступ к следующим категориям данных:

Пользователи и группы

• Чтение и обновление профилей пользователей, управление группами, ролями и членством.
• Поиск пользователей по почте, имени или отделу.

Сообщения и календари

• Чтение, отправка и управление электронной почтой (Outlook).
• Создание, изменение и удаление событий календаря, управление встречами и напоминаниями.

Файлы и документы

• Работа с файлами в OneDrive и SharePoint (чтение, загрузка, создание, удаление, перемещение).
• Доступ к версиям файлов и метаданным.

Teams и чаты

• Управление командами, каналами, сообщениями и вложениями в Microsoft Teams.
• Получение списка участников, истории чатов и уведомлений.

Задачи и планирование

• Работа с задачами в Planner, To Do и Outlook Tasks.
• Создание планов, назначение задач, отслеживание прогресса.

Аналитика и отчёты

• Получение отчётов об использовании сервисов (например, активность пользователей, количество отправленных сообщений).
• Аналитика взаимодействия (например, кто с кем общается чаще всего).

Безопасность и управление

• Интеграция с Azure AD для управления доступом и политиками.
• Получение оповещений безопасности от Microsoft Defender for Cloud.

История

Microsoft Graph был анонсирован 19 ноября 2015 года на конференции Microsoft Ignite как эволюция существовавших ранее API для Office 365 и Azure AD. Первоначально назывался «Office 365 Unified API». В 2016 году переименован в Microsoft Graph, чтобы подчеркнуть его роль как единого шлюза ко всем данным Microsoft.

В 2017 году вышла версия 1.0, ставшая стабильной. В последующие годы платформа расширялась: добавлены API для Teams (2018), Power BI (2019), Microsoft To Do (2020) и другие. В 2021 году Microsoft объявила о прекращении поддержки старых API в пользу Graph.

Применение

Microsoft Graph используется в нескольких сценариях:

• Корпоративные приложения — интеграция с Microsoft 365 для автоматизации бизнес-процессов (например, создание задач из писем или синхронизация календарей).
• Разработка мобильных и веб-приложений — доступ к почте, файлам и контактам пользователя.
• Аналитика и отчётность — сбор данных об использовании сервисов для принятия управленческих решений.
• Боты и виртуальные помощники — например, интеграция с Microsoft Teams для отправки уведомлений или поиска информации.
• Образовательные и научные проекты — автоматизация учебных процессов (например, создание групп и заданий).

Ограничения и квоты

Microsoft Graph имеет ограничения на количество запросов в секунду (RPS) и объём данных. Для большинства сервисов действуют следующие квоты:

• Пользовательские запросы — до 10 000 запросов на 10 секунд на приложение.
• Прикладные запросы — до 2 000 запросов в секунду на приложение.
• Размер ответа — не более 4 МБ для одного запроса.
• Пагинация — для больших наборов данных используется постраничный вывод (skip token).

При превышении лимитов API возвращает код ошибки 429 (Too Many Requests) с заголовком Retry-After.

Критика

Основные замечания к Microsoft Graph связаны с:

• Сложностью настройки разрешений — для доступа к данным требуется точное указание прав, что часто вызывает путаницу у разработчиков.
• Неполнотой документации — некоторые функции (особенно в бета-версии) описаны поверхностно или имеют устаревшие примеры.
• Зависимостью от Azure AD — без подписки на Azure AD или Microsoft 365 Enterprise часть возможностей недоступна.
• Изменчивостью бета-версии — API в версии /beta может меняться без обратной совместимости, что создаёт риски для приложений.

Безопасность

Microsoft Graph использует шифрование TLS 1.2+ для всех запросов. Аутентификация через OAuth 2.0 требует регистрации приложения в Azure AD. Администраторы могут управлять разрешениями через портал Azure, а также включать политики условного доступа (например, требовать многофакторную аутентификацию).

Примеры запросов

Получение профиля текущего пользователя

`` GET https://graph.microsoft.com/v1.0/me Authorization: Bearer {token} ``

Список сообщений в папке «Входящие»

`` GET https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages Authorization: Bearer {token} ``

Создание события в календаре

``` POST https://graph.microsoft.com/v1.0/me/events Content-Type: application/json Authorization: Bearer {token}

{ "subject": "Встреча с командой", "start": { "dateTime": "2025-03-01T10:00:00", "timeZone": "Europe/Moscow" }, "end": { "dateTime": "2025-03-01T11:00:00", "timeZone": "Europe/Moscow" } } ```

Источники

• Microsoft Graph documentation (Microsoft Learn)
• Microsoft Graph REST API v1.0 reference
• Microsoft Graph SDK overview
• Azure Active Directory documentation
• Microsoft Ignite 2015 announcements