Основные службы и компоненты в Microsoft Graph
Microsoft Graph позволяет интегрировать приложение с лучшими службами Microsoft 365, Windows 10 и Enterprise Mobility + Security в Microsoft 365, используя REST API и клиентские библиотеки. Кроме того, в нем имеются функции аналитики системы безопасности, с помощью которых можно повысить эффективность работы пользователей, стимулировать творчество и совместную работу в группах, а также защищать бизнес-ресурсы и данные пользователей.
Пользователи и группы
В основе Microsoft Graph лежит концепция пользователя и группы.
Пользователь в Microsoft Graph — это один из миллионов людей, которые используют облачные службы Microsoft 365. Это центральная точка, чье удостоверение защищено и доступ к которой хорошо управляется. Данные пользователя — это то, на чем основан бизнес. Службы Microsoft Graph делают эти данные доступными для организаций в функциональных контекстах, обновлениях в режиме реального времени и результатах глубокой аналитики. Доступ к данным всегда предоставляется только при наличии соответствующих разрешений.
Группа Microsoft 365 — это фундаментальный объект, с помощью которого пользователи могут вести совместную работу. Она интегрируется с другими службами, что позволяет использовать более функциональные сценарии при планировании задач, работе в группах, обучении и т. д.
| Компонент | Вспомогательные службы | Описание | Дополнительные сведения |
|---|---|---|---|
| Пользователи | Azure AD и большая часть служб для повышения производительности труда, совместной работы, аналитики и обучения | Пользователь — это основной объект в Microsoft Graph, для которого во многих службах Microsoft Graph создаются функции, ориентированные на пользователей. | Обзор пользователей в Microsoft Graph |
| Группы | Azure AD, OneDrive, OneNote, Outlook, Планировщик | Группа Microsoft 365 — это основа для совместной работы. В группах пользователи могут обмениваться беседами, файлами, заметками, календарями планами и т. д. | Обзор групп Microsoft 365 в Microsoft Graph |
Соединение данных пользователей, служб Microsoft 365 и ваших приложений
Используя пользователей и группы в качестве основы, Microsoft Graph создает сеть служб и компонентов Microsoft 365, которые управляют данными, защищают и извлекают их для поддержки широкого спектра сценариев. С помощью Microsoft Graph вы можете получить доступ к огромному количеству данных пользователей, выполнив при этом необходимую авторизацию.
Рекомендации по работе с Microsoft Graph
Эта статья содержит рекомендации по эффективному использованию Microsoft Graph в приложениях, независимо от текущей задачи — знакомство с Microsoft Graph, увеличение производительности или повышение надежности приложения.
Знакомство с API с помощью песочницы Graph
Самый простой способ ознакомиться с данными, доступными через Microsoft Graph, — использовать песочницу Graph. Песочница Graph позволяет создавать запросы REST (с полной поддержкой CRUD), адаптировать заголовки HTTP-запросов и просматривать ответы с данными. Песочница Graph также содержит примеры запросов, которые помогут вам приступить к работе.
Поэкспериментируйте с новыми API, прежде чем интегрировать их в приложение.
Аутентификация
Для доступа к данным в Microsoft Graph приложению необходимо получить маркер доступа OAuth 2.0 и предоставить его службе Microsoft Graph в одном из следующих элементов:
Чтобы получить маркер доступа к Microsoft Graph, используйте API библиотеки проверки подлинности (Майкрософт) — MSAL.
Согласие и авторизация
Реализуя согласие и авторизацию в приложении, следуйте приведенным ниже рекомендациям.
Руководствуйтесь принципом минимальных прав. Запрашивайте только те разрешения, которые совершенно необходимы, и только тогда, когда они нужны. По каждому API, вызываемому приложением, ознакомьтесь с разделом «Разрешения» в посвященной ему статье (например, статье Создание пользователя) и выберите минимальные разрешения. Полный список разрешений представлен в справочнике по разрешениям.
Используйте типы разрешений, подходящие для соответствующих сценариев. Если вы создаете интерактивное приложение, в котором присутствует вошедший пользователь, то оно должно использовать делегированные разрешения (то есть приложению делегируется разрешение действовать от имени вошедшего пользователя при вызове Microsoft Graph). Однако если приложение работает без вошедшего пользователя (как, например, фоновая служба или управляющая программа), то следует использовать разрешения приложений.
Примечание. При использовании разрешений для приложений в интерактивных сценариях могут возникать риски, связанные с соответствием требованиям и безопасностью. Права пользователя на доступ к данным могут быть непреднамеренно повышены в обход политик, настроенных администратором.
Будьте внимательны при настройке приложения. Это непосредственно повлияет на работу пользователей и администраторов, а также на внедрение приложений и их безопасность. Примеры:
Учитывайте мультитенантные приложения. Помните, что у клиентов могут быть разные правила относительно приложений и согласия в разных состояниях. Например:
Эффективная обработка ответов
В зависимости от того, какие запросы отправляются в Microsoft Graph, приложения должны быть готовы обрабатывать различные ответы. Ниже представлены некоторые важные рекомендации, соблюдении которых обеспечит надежную работу приложения.
Разбивка на страницы
Допустим, нужно получить список сообщений вошедшего пользователя:
Дополнительные сведения см. в этой статье.
Обработка ожидаемых ошибок
Приложение должно обрабатывать все ошибки (в диапазонах 400 и 500), но некоторым ожидаемым ошибкам и ответам следует уделять особое внимание. Они перечислены в приведенной ниже таблице.
| Тема | Код ошибки HTTP | Рекомендация |
|---|---|---|
| У пользователя нет доступа | 403 | Эта ошибка может возникнуть в запущенном приложении, даже если ему были предоставлены необходимые разрешения через интерфейс согласия. В этом случае наиболее вероятно, что у вошедшего пользователя нет прав на доступ к запрашиваемому ресурсу. Приложение должно показывать вошедшему пользователю обычное сообщение «Отказано в доступе». |
| Не найдено | 404 | В некоторых случаях запрашиваемый ресурс может быть не найден. К примеру, ресурс может не существовать, так как он еще не был подготовлен (как, например, фотография пользователя) или был удален. Некоторые удаленные ресурсы можно полностью восстановить в течение 30 дней после удаления. К таким ресурсам относятся пользователи, группы и приложения, поэтому ваше приложение также должно это учитывать. |
| Регулирование | 429 | API могут регулировать количество запросов в любой момент по ряду причину, поэтому приложение всегда должно быть готово обрабатывать ответы 429. Эта ошибка включает поле Retry-After в заголовке HTTP-ответа. Самый быстрый способ избавиться от регулирования — отложить запросы с помощью задержки Retry-After. Дополнительные сведения см. в этой статье. |
| Служба недоступна | 503 | Скорее всего, служба занята. Следует применять ту же стратегию, что и при обработке ошибки 429. Кроме того, повторные запросы следует всегда выполнять через новое подключение HTTP. |
Обработка будущих участников в изменяемых перечислениях
Добавление членов в существующие перечисления может нарушить работу приложений, уже использующих эти перечисления. Изменяемые перечисления — это механизм, который API Microsoft Graph использует для добавления новых членов в существующие перечисления без внесения каких-либо изменений в приложения.
По умолчанию операция GET возвращает только известные элементы для свойств типов изменяемых перечислений, и приложение должно обрабатывать только известные элементы. Если вы разрабатываете приложение для обработки неизвестных элементов, вы можете отказаться от получения этих элементов с помощью заголовка HTTP-запроса Prefer :
Локальное хранение данных
В идеальном случае приложение должно вызывать Microsoft Graph для получения данных в реальном времени. Кэшировать данные или хранить их локально следует, только если это требуется для определенного сценария и если этот вариант использования предусмотрен условиями использованиями и политикой конфиденциальности, а также не противоречит условиям использования API Microsoft. В приложении также необходимо реализовать надлежащие политики хранения и удаления.
Оптимизация
Как правило, из соображений производительности и даже безопасности или конфиденциальности, следует получать только те данные, которые действительно необходимы приложению.
Использование проекций
Выбирайте только те свойства, которые действительно необходимы приложению. Это позволит сэкономить сетевой трафик и снизить нагрузку на приложение (и службу), связанную с обработкой данных.
Например, при получении сообщений вошедшего пользователя можно указать, что необходимо вернуть только свойства from и subject:
Получение минимальных ответов
В случае некоторых операций, например PUT и PATCH (а в некоторых случаях — POST), если приложению не нужны полезные данные ответа, можно просить API возвращать минимальное количество данных. Обратите внимание, что некоторые службы уже возвращают ответ 204 No Content для операций PUT и PATCH.
Примечание. Запрашивайте ответы с минимальным представлением, используя заголовок HTTP-запроса: Prefer: return=minimal. Обратите внимание, что в случае операций создания это может быть неуместно, так как приложение может ожидать сгенерированный службой id для нового объекта в ответе.
Отслеживание изменений: разностный запрос и уведомления веб-перехватчиков
Если приложению нужно знать об изменениях данных, вы можете получать уведомление веб-перехватчика при каждом их изменении. Это эффективнее, чем регулярные опросы.
Используйте уведомления веб-перехватчиков, чтобы получать push-уведомления при изменении данных.
Если приложение должно кэшировать или сохранять данные Microsoft Graph локально и поддерживать их в актуальном состоянии либо отслеживать изменения данных по каким-либо другим причинам, следует использовать разностный запрос. Это избавит приложение от необходимости лишних вычислений для получения данных, уже доступных приложению, уменьшит количество сетевого трафика и снизит вероятность достижения порога регулирования.
Используйте разностный запрос, чтобы эффективно поддерживать данные в актуальном состоянии.
Использование веб-перехватчиков вместе с разностным запросом
Как правило, веб-перехватчики и разностный запрос эффективнее работают вместе, так как при использовании разностного запроса необходимо подобрать подходящий интервал опроса. Если он слишком короткий, будет возвращаться много пустых ответов, что приведет к трате ресурсов. Если же он слишком длинный, ваши данные могут устареть. Используя уведомления веб-перехватчиков в качестве триггера для отправки разностных запросов, вы получаете преимущества обеих функций.
Используйте уведомления веб-перехватчиков в качестве триггера для отправки разностных запросов. Кроме того, следует убедиться, что в приложении задан предельный порог опроса на тот случай, если уведомлений не будет.
Пакетная обработка
Пакетная обработка JSON позволяет оптимизировать приложение, объединив несколько запросов в один объект JSON. Объединение отдельных запросов в один позволяет значительно снизить задержку в сети и сэкономить ресурсы подключения.
Используйте пакетную обработку в тех случаях, когда задержка сети может существенно повлиять на производительность.
Надежность и поддержка
Чтобы обеспечить надежность и поддержку приложения следуйте приведенным ниже рекомендациям.
Обзор Microsoft Graph
Microsoft Graph открывает доступ к данным и средствам искусственного интеллекта в Microsoft 365. Благодаря этому вы получите единую модель программируемости, которую можно использовать для доступа к колоссальному объему данных в Microsoft 365, Windows 10 и Enterprise Mobility + Security. Используйте многочисленные данные в Microsoft Graph и создавайте приложения с миллионной аудиторией для организаций и пользователей.
Данные и службы для расширения возможностей платформы Microsoft 365
Три основных компонента платформы Microsoft 365 упрощают доступ к данным и их поток:
Одновременное использование API Microsoft Graph, соединителей и подключения к данным позволяет расширить возможности платформы Microsoft 365. Благодаря доступу к данным Microsoft Graph и другим наборам данных вы можете получить статистику и аналитику, расширить возможности Microsoft 365 и создавать уникальные интеллектуальные приложения.
Из чего состоит Microsoft Graph?
Microsoft Graph предоставляет интерфейсы REST API и клиентские библиотеки для доступа к данным в нижеуказанных облачных службах Майкрософт:
Что можно делать с помощью Microsoft Graph?
Microsoft Graph позволяет обрабатывать уникальный контекст пользователя и делать его более результативным. Представьте приложение, которое.
В качестве примера выберите первый сценарий поиска участников собрания. С помощью API Microsoft Graph вы можете:
С помощью связей вы можете перейти к другим ресурсам:
Microsoft Graph продолжает открывать возможности платформы Microsoft 365 для разработчиков, но исключительно при наличии соответствующих разрешений.
Популярные запросы API
Ознакомьтесь с некоторыми из популярных сценариев работы с API Microsoft Graph. Ссылки ведут на песочницу Graph.
| Операция | URL-адрес |
|---|---|
| GET мой профиль | https://graph.microsoft.com/v1.0/me |
| Получение своих файлов | https://graph.microsoft.com/v1.0/me/drive/root/children |
| Получение своей фотографии | https://graph.microsoft.com/v1.0/me/photo/$value |
| Получение своей почты | https://graph.microsoft.com/v1.0/me/messages |
| GET моя почта высокой важности | https://graph.microsoft.com/v1.0/me/messages?$filter=importance%20eq%20’high’ |
| GET события в моем календаре | https://graph.microsoft.com/v1.0/me/events |
| GET мой руководитель | https://graph.microsoft.com/v1.0/me/manager |
| GET последний пользователь, изменивший файл foo.txt | https://graph.microsoft.com/v1.0/me/drive/root/children/foo.txt/lastModifiedByUser |
| Получение групп Microsoft 365, участником которых я являюсь | https://graph.microsoft.com/v1.0/me/memberOf/$/microsoft.graph.group?$filter=groupTypes/any(a:a%20eq%20’unified’) |
| GET пользователи в моей организации | https://graph.microsoft.com/v1.0/users |
| GET группы в моей организации | https://graph.microsoft.com/v1.0/groups |
| GET пользователи, связанные со мной | https://graph.microsoft.com/v1.0/me/people |
| GET элементы, популярные в моей компании | https://graph.microsoft.com/beta/me/insights/trending |
| GET мои заметки | https://graph.microsoft.com/v1.0/me/onenote/notebooks |
Перенос данных из внешнего источника контента в Microsoft Graph
Используйте соединители Microsoft Graph для переноса данных, не входящих в Microsoft Cloud, в Microsoft Graph. Примерами таких данных могут быть база данных отдела кадров организации или каталог продуктов, размещенные локально, в общедоступных или частных облаках.
Соединители Microsoft Graph позволяют создавать подключения к внешним источникам данных, индексировать данные и хранить их как внешние настраиваемые элементы и файлы. После индексирования эти элементы могут отображаться в Поиске (Майкрософт), а также для приложений, использующих API Поиска (Майкрософт).
Масштабируемый доступ к данным Microsoft Graph с помощью подключения к данным Microsoft Graph
Используйте подключение к данным Microsoft Graph для получения масштабируемого доступа к данным в Microsoft Graph, предоставляя администраторам точечные разрешения и полный доступ к этим данным. Подключение к данным помогает оптимизировать их доставку в Microsoft Azure.
С помощью средств Azure можно создавать интеллектуальные приложения с такими функциями:
Когда следует использовать API Microsoft Graph или подключение к данным?
Microsoft Graph Data Connect предоставляет новый способ взаимодействия с данными, доступными с помощью интерфейсов API Microsoft Graph. Подключение к данным предоставляет уникальный набор инструментов, которые помогают оптимизировать создание интеллектуальных приложений в рамках облака Майкрософт.
Microsoft Graph — это единый API для современной работы
Используйте данные и аналитику в Microsoft 365 для создания приложений, взаимодействующих с миллионами пользователей.
Расширенный контекст
Получайте расширенный контекст для приложений, например: на месте ли пользователь, кто его руководитель, с какими документами он работал в последнее время.
Глубокая аналитика
Получайте подробную статистику о тенденциях использования. Узнавайте, какие документы наиболее востребованы, в какое время лучше проводить собрания и с кем пользователи обычно работают.
Обновления в режиме реального времени
Реагируйте на изменения в данных Microsoft Graph в режиме реального времени. Изменяйте расписание собраний на основе ответов, уведомляйте остальных пользователей при изменении файлов и продолжайте процессы после их утверждения.
Широкая аудитория
Создавайте решения для корпоративных пользователей в Azure и Microsoft 365, пользователей служб Office Online (Outlook.com и OneDrive.com) или для всех категорий пользователей.
Последние новости о Microsoft Graph
Общие сведения о едином входе Azure AD для приложений Microsoft Teams
Для единого входа отсутствует одно определение, что порождает путаницу. Узнайте о подходах единого входа, используемых в Microsoft Commercial Marketplace (магазине приложений) и в приложении, запущенном в Microsoft Teams, чтобы вы могли начать создание единого входа для приложения Teams.
Давайте займемся расшифровкой: единый вход на вкладках Microsoft Teams
Microsoft 365 Code | Decode — это серия, посвященная разбору тем для разработчиков с целью лучшего понимания концепций. В этом сегменте Боб и Рабия расшифровывают единый вход (SSO) в приложении на вкладке Teams.
Go-разработчики теперь могут получить доступ к Microsoft Graph с помощью упрощенной проверки подлинности и не только
Go-разработчики теперь могут интегрировать свое приложение в Microsoft Graph с помощью нового пакета SDK Microsoft Graph Go.
Разработка Microsoft Teams: все, что вам нужно знать
Microsoft Teams — это современное приложение для обмена сообщениями в организации. Microsoft Teams предоставляет рабочее пространство для совместной работы, общения, проведения собраний и обмена файлами в режиме реального времени. Приложение Teams можно расширить несколькими способами. В этой записи блога объясняется, как это сделать.
Разработка приложений для совместной работы в режиме реального времени с использованием Azure, Microsoft 365, Power Platform и GitHub
Приложения для совместной работы, созданные для платформы совместной работы, например Microsoft Teams, Slack, Google Workspace и т. д., — это приложения, в основе которых лежит взаимодействие и которые предназначены для гибкой гибридной работы. Вы можете создавать приложения для совместной работы с помощью инструментов, которые вы используете каждый день, и ваших имеющихся навыков разработки!
Существенные изменения в отчете об участии в API OnlineMeeting Microsoft Graph (бета-версия)
Сегодня мы объявляем о предстоящих существенных изменениях для разработчиков, использующих API Microsoft Graph для получения отчетов об участии в собраниях по сети, начиная с 19 ноября 2021 г.
Ignite 2021: создание приложений для совместной работы в гибридном мире
Добро пожаловать на Ignite 2021. В этом блоге представлена сводка новостей для разработчиков на платформе Microsoft 365 в новой эре гибридной работы. Ознакомьтесь с новыми возможностями и не пропустите ничего важного!
Присоединяйтесь к программе разработчиков Microsoft 365
Получите готовую песочницу, инструменты и ресурсы, чтобы создавать решения для платформы Microsoft 365, в том числе:
Краткое руководство по Microsoft Graph: вопросы и ответы
В этой статье представлены ответы на вопросы, связанные с краткими руководствами по Microsoft Graph.
Общая схема
В примерах, содержащихся в кратких руководствах, показано, как использовать всю мощь Microsoft Graph. В этих примерах выполняется доступ к двум службам с использованием одной проверки подлинности: к учетной записи Майкрософт и Outlook. В каждом кратком руководстве используются сведения из профилей пользователей с учетными записями Майкрософт и отображаются события из их календаря.
В каждом кратком руководстве необходимо выполнить четыре действия:
В итоге вы получите приложение, готовое к запуску.
Предварительные условия
Все примеры быстрого запуска требуют доступа к личной учетной записи Майкрософт с почтовым ящиком на Outlook.com или к учетной записи Microsoft work или school с Exchange Online почтовым ящиком. Если у вас нет учетной записи Майкрософт, существует несколько вариантов получения бесплатной учетной записи:
Общие вопросы, касающиеся примеров из краткого руководства
Можно ли получить код из краткого руководства, не выполняя скачивание на странице краткого руководства?
Да, конечно! Каждый скачиваемый экземпляр краткого руководства основан на учебнике по Microsoft Graph, поэтому у вас есть два других варианта для получения такого же исходного кода:
Учебники и репозитории GitHub
В таблице ниже перечислены соответствующие учебники и репозитории GitHub для каждого примера из краткого руководства.
| Краткое руководство | Учебник | Репозиторий GitHub |
|---|---|---|
| Android | Учебник | GitHub |
| Angular | Учебник | GitHub |
| ASP.NET MVC | Учебник | GitHub |
| iOS Swift | Учебник | GitHub |
| iOS Objective-C | Учебник | GitHub |
| Node.js | Учебник | GitHub |
| PHP | Учебник | GitHub |
| Python | Учебник | GitHub |
| React | Учебник | GitHub |
| Ruby | Учебник | GitHub |
| UWP | Учебник | GitHub |
| Xamarin | Учебник | GitHub |
Почему в примерах из краткого руководства нет вариантов использования расширенной проверки подлинности?
Примеры из краткого руководства используются для ознакомления с функцией проверки подлинности и вызовов API Microsoft Graph. Дополнительные сведения о других потоках проверки подлинности см. в документации Azure Active Directory.
Что делать при возникновении непредвиденной ошибки или проблемы с кратким руководством?
Если не удается обеспечить правильную работу при использовании краткого руководства, опубликуйте проблему в соответствующем репозитории GitHub.
Известные проблемы
При запуске краткого руководства ASP.NET отображается ошибка «Не удается найти часть пути [. ]\Graph Tutorial\graph-tutorial\bin\roslyn\csc.exe».
Это вызвано проблемой с Visual Studio и компилятором Roslyn. Исправить эту ошибку можно одним из следующих вариантов:
При запуске краткого руководства возникает ошибка «AADSTS50011: URL-адрес ответа, указанный в запросе, не совпадает с URL-адресами ответов, настроенными для приложения».
Это указывает на проблему с регистрацией приложения для краткого руководства. Когда вы скачиваете краткое руководство со страницы кратких руководств Microsoft Graph, для вас создается регистрация приложение и выполняется настройка URL-адреса ответа (другое название — URL-адрес перенаправления), совпадающего с URL-адресом по умолчанию, который используется примером проекта. Если изменить URL-адрес, нарушается соответствие регистрации приложения, и может возникнуть эта ошибка. Чтобы устранить эту ошибку, обратитесь к файлу README.md, включенному в проект краткого руководства, за инструкциями о том, как создать регистрацию приложения и настроить ее в примере кода.
После регистрации мне говорят, что мне нужно утверждение администратора.
После подписания в один из примеров быстрого запуска вы можете увидеть сообщение с утверждением необходимости администратора «XXX Учебник нуждается в разрешении на доступ к ресурсам в вашей организации, которые может предоставить только администратор. Пожалуйста, попросите администратора предоставить разрешение этому приложению, прежде чем вы сможете использовать его.» Это не ошибка с образцом! Ни один из быстрых стартов не запрашивает Graph области разрешений, которые по умолчанию требуют согласия администратора. Администраторы клиентов могут отключить возможность согласия на Graph области разрешений для любых приложений, которые они не одобрили. В этом случае вы увидите эту ошибку.
Вам потребуется работать с администраторами, чтобы получить утверждение, использовать личную учетную запись Майкрософт (Outlook.com) или использовать тестовый Microsoft 365 с Exchange Online.
Не нашли то, что искали?
Если в этой статье вы не нашли ответ на интересующий вас вопрос касательно одного или нескольких кратких руководств, сообщите нам об этом в разделе Отзыв ниже.
