Знакомство с графовыми API
Привет, Хабр! Мы не перестаем отслеживать тему проектирования API после того, как встретили в портфеле издательства «Manning» вот эту книгу. Сегодня мы решили опубликовать обзорную статью об относительно новых Graph API и предлагаем еще раз задуматься о том, каковы будут новые API после безраздельной популярности REST.
Приятного чтения!
Если в последние 10 лет вам доводилось потреблять API – готов поспорить, что это был REST API. Вероятно, данные были структурированы вокруг ресурсов, в отклики включались id, указывающие на связанные объекты, а при помощи HTTP-команд сообщалось, как поступить с информацией: прочитать, записать и обновить (да, согласен, это вольное определение, а не канонический REST Роя Филдинга). Некоторое время API в стиле REST были доминирующим стандартом в нашей индустрии.
Однако, у REST есть свои проблемы. Клиент может привыкнуть извлекать лишние данные, запрашивая целый ресурс в случае, когда ему нужны лишь один-два фрагмента информации. Либо клиенту могут регулярно требоваться несколько объектов одновременно, но он не может извлечь их все в одном запросе – тогда возникает так называемое «недоизвлечение» данных. Что касается поддержки, изменения в REST API могут приводить к тому, что клиенту потребуется обновить всю интеграцию, чтобы программа соответствовала новой структуре API или схемам откликов.
Для решения подобных проблем в последние годы все активнее разрабатываются принципиально иные API, именуемые «графовыми».
Что такое Graph API?
В графовом API клиент формулирует вызов таким образом, что данные со всех трех ресурсов вытягиваются в один заход. Клиент также может указать те поля, которые для него действительно важны, предоставив более полный контроль над схемой отклика.
Чтобы детально исследовать, как устроен этот механизм, рассмотрим пару кейсов с описанием живых невыдуманных API.
Кейс 1: Графовый API Facebook
Facebook выпустил версию 1.0 своего API в 2010 году и с тех пор проектирует новые версии, вдохновляясь примером графовых баз данных. Существуют узлы, соответствующие, например, постам и комментариям, а также ребра, соединяющие их и указывающие, что данный комментарий «относится» к этому посту. Такой подход обеспечивает всей конструкции не менее качественную обнаружимость, чем у типичного REST API, однако, все равно позволяет клиенту оптимизировать извлечение данных. Возьмем в качестве примера отдельный пост и рассмотрим, какие простые операции можно с ним проделать.
Для начала клиент при помощи запроса GET выбирает пост из корня API, исходя из ID поста.
По умолчанию в таком случае возвращается большинство полей верхнего уровня данного поста. Если клиенту требуется доступ лишь к некоторым элементам поста – например, заголовку и времени создания – то можно запросить только эти поля, указав данную информацию в качестве одного из параметров запроса:
Чтобы выбрать требуемые данные, клиент запрашивает ребро, например, комментарии к посту:
До сих пор все это напоминает функции REST API. Пожалуй, возможность задать подмножество полей – в новинку, но в целом данные воспринимаются во многом как ресурсы. Ситуация становится интереснее, когда клиент собирает вложенный запрос. Вот как еще клиент может выбрать комментарии к посту:
Вышеприведенный запрос возвращает отклик, в котором содержится время создания поста, его заголовок и список комментариев (из каждого сообщения выбирается только id и сообщение). В REST вы бы такое сделать не смогли. Клиенту потребовалось бы сначала выбрать пост, а затем — комментарии.
А что, если клиенту потребуются более глубокие вложения?
В этом запросе выбираются комментарии к посту, в том числе, id и имя автора каждого комментария. Рассмотрим, как это делалось бы в REST. Клиенту потребовалось бы запросить пост, запросить комментарии, а затем в серии отдельных запросов извлечь информацию об авторе каждого комментария. Сразу набирается множество HTTP-вызовов! Однако, при проектировании в виде графа вся эта информация конденсируется в одном вызове, и в этом вызове оказывается лишь та информация, что нужна клиенту.
Наконец, последний момент, который следует отметить о графовом проектировании: любой объект, выбираемый с ребра, сам является узлом и, следовательно, его можно запросить непосредственно. Вот, например, как выбирается дополнительная информация о конкретном комментарии:
Обратите внимание: клиенту не нужно собирать URL вида /posts/
Кейс 2: GitHub V4 GraphQL API
Другим конкурентом графового API можно считать спецификацию под названием GraphQL. Эта концепция значительно отличается от REST, здесь предоставляется всего одна конечная точка, принимающая запросы GET и POST. При всех взаимодействиях с API отправляются запросы, соответствующие синтаксису GraphQL.
В мае 2017 года GitHub выпустил 4-ю версию своего API, соответствующую этой спецификации. Чтобы попробовать, каков из себя GraphQL, давайте рассмотрим отдельные операции, которые можно проделать с репозиторием.
Чтобы выбрать репозиторий, клиент определяет запрос GraphQL:
В данном запросе выбирается ID и описание репозитория “transformer” с ресурса Zapier org. Здесь следует отметить несколько вещей. Во-первых, мы считываем данные с API при помощи POST, поскольку посылаем в запросе тело сообщения. Во-вторых, полезная нагрузка самого запроса записана в формате JSON, что предписано в стандарте GraphQL. В-третьих, структура запроса будет именно такой, какая указана в нашем запросе, <"data": <"repository": <"id": "MDEwOlJlcG9zaXRvcnk1MDEzODA0MQ==", "description": ". ">>> (корневой ключ data – еще один обязательный элемент, который должен присутствовать в откликах GraphQL).
Чтобы выбрать данные, относящиеся к репозиторию – например, задачи и их авторов, клиент применяет вложенный запрос:
Этот запрос выхватывает ID и описание репозитория, название и текст последних 20 задач, созданных в репозитории, а также логин (имя) автора каждой задачи. То есть, в каждом запросе укладывается масса информации. Вообразите, как выглядел бы REST-эквивалент такого запроса – и становится понятно, какие возможности и гибкость обеспечивает клиентам GraphQL в данном отношении.
При обновлении данных GraphQL использует концепцию под названием «мутация». В отличие от REST, где обновление выполняется путем PUT или POST измененной копии ресурса на ту же конечную точку, с которой клиент ее извлек, мутация GraphQL – это явная операция, определяемая API. Если клиенту требуется подкорректировать данные, то требуется знать, какие мутации поддерживаются на сервере. Удобно, что GraphQL позволяет обнаруживать их в рамках процесса под названием «интроспекция схемы».
При наличии подробной схемы GraphQL в обязательном порядке требует, чтобы клиент имел возможность запрашивать эту схему в соответствии с синтаксисом GraphQL. Таким образом клиент может узнать возможности API путем интроспекции.
Если клиенту требуется узнать, какие мутации возможны в GitHub, можно просто запросить:
Надеюсь, эти кейсы наглядно демонстрируют, как развивается дизайн API в SaaS-индустрии. Я не пытаюсь сказать, что за графовыми API будущее, а REST мертв. В таких архитектурах как GraphQL есть собственные проблемы. Но хорошо, что круг возможностей ширится, и в следующий раз, когда вам потребуется создать API, вы сможете взвесить все компромиссы, на которые приходится идти при том или ином варианте дизайна, и выбрать оптимальное решение.
Использование API Microsoft Graph
Microsoft Graph — это соответствующий ограничениям REST веб-API, обеспечивающий доступ к ресурсам службы Microsoft Cloud. После регистрации приложения и получения маркеров аутентификации для пользователя или службы можно отправлять запросы к API Microsoft Graph.
Важно! Изменяется принцип применения политик условного доступа к Microsoft Graph. Вам необходимо обновить свои приложения, чтобы они могли обрабатывать сценарии, в которых выполняется настройка политик условного доступа. Дополнительные сведения и рекомендации см. в статье Руководство для разработчиков по условному доступу в Azure Active Directory.
Пространство имен OData
Вызов метода API REST
Для чтения или записи ресурса, например пользователя или сообщения электронной почты, создайте запрос, показанный ниже:
После создания запроса возвращается ответ, который включает:
Методы HTTP
Чтобы определить функцию запроса, Microsoft Graph использует метод HTTP. API поддерживает перечисленные ниже методы.
Версия
Мы всегда рады отзывам о бета-версиях API. Чтобы оставить отзыв или предложить функцию, посетите наш форум идей для платформы разработчиков Microsoft 365.
Дополнительные сведения о версиях API см. в статье Управление версиями и поддержка.
Ресурс
Ресурс может быть объектом или сложным типом и обычно определяется с помощью свойств. Объекты всегда содержат свойство id, что отличает их от сложных типов.
Для доступа к каждому ресурсу могут потребоваться особые разрешения. Для создания и обновления ресурса часто требуется более высокий уровень разрешений, чем для чтения. Сведения о требуемых разрешениях см. в справочной статье о методе.
Параметры запроса
В качестве параметров запросов могут использоваться системные параметры запроса OData или другие строки, поддерживаемые методом для настройки ответа.
Вы можете использовать необязательные системные параметры запроса OData, чтобы изменять свойства, включаемые в ответ, находить элементы, соответствующие пользовательскому запросу, и указывать дополнительные параметры для метода.
Дополнительные сведения о параметрах запроса OData см. в статье Настройка ответов с помощью параметров запроса.
Инструменты для взаимодействия с Microsoft Graph
Песочница Graph
Песочница Graph — это веб-инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph. Песочница Graph доступна по адресу: https://developer.microsoft.com/graph/graph-explorer.
Вы можете получить доступ к демонстрационным данным без входа или войти в свой клиент. Чтобы отправить запрос, выполните следующее:
В следующем примере показан запрос, возвращающий сведения о пользователях в демонстрационном клиенте:
Примеры запросов представлены в песочнице Graph, чтобы вы могли быстрее запускать распространенные запросы. Чтобы просмотреть доступные примеры, выберите Показать другие примеры. Выберите Вкл для набора примеров, который вы хотите просмотреть, и после закрытия окна выбора должен появиться список готовых запросов.
После отправки запроса отображается код состояния и сообщение, а запрос выводится на вкладке Просмотр отклика.
Postman
Postman — это инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph. Вы можете скачать Postman по адресу: https://www.getpostman.com/. Чтобы взаимодействовать с Microsoft Graph в Postman, используйте коллекцию Microsoft Graph.
Дальнейшие действия
Все готово для настройки Microsoft Graph. Воспользуйтесь кратким руководством или начните с одного из пакетов SDK или примеров кода.
API Microsoft Graph
API Microsoft Graph — это веб-API RESTful, который позволяет получать доступ к ресурсам службы Microsoft Cloud. После регистрации приложения и получения токена проверки подлинности для пользователя или службы можно выполнять запросы к API Microsoft Graph. Дополнительные сведения см. в статье Обзор Microsoft Graph.
Microsoft Graph предоставляет REST API и клиентские библиотеки для доступа к данным в следующих службах Microsoft:
Версии
В настоящее время доступны следующие версии API Microsoft Graph:
Приступая к работе
Для чтения из ресурса (например, пользователя или сообщения электронной почты) или записи в него, создается запрос, который выглядит следующим образом:
Дополнительные сведения об элементах созданного запроса см. в разделе Использование API Microsoft Graph.
Доступны примеры быстрого запуска, которые показывают, как получить доступ к возможностям API Microsoft Graph. В доступных примерах рассматривается доступ к двум службам с использованием одной проверки подлинности: учетная запись Майкрософт и Outlook. При каждом быстром запуске осуществляется доступ к информации из профилей пользователей учетных записей Майкрософт и отображаются события из их календаря. Быстрые запуски можно разделить на четыре этапа:
По завершении быстрого запуска вы получаете готовое к работе приложение. Дополнительные сведения см. в разделе Вопросы и ответы по быстрым запускам в Microsoft Graph. Чтобы приступить к работе с примерами, см. статью Быстрые запуски в Microsoft Graph.
Инструменты
Microsoft Graph Explorer — это веб-инструмент, который можно использовать для создания и тестирования запросов к API Microsoft Graph. Он доступен по адресу https://developer.microsoft.com/graph/graph-explorer.
Postman — это еще один инструмент, который позволяет выполнять запросы к API Microsoft Graph. Скачать его можно по адресу https://www.getpostman.com. Для взаимодействия с Microsoft Graph в Postman используется коллекция Microsoft Graph Postman.
Дальнейшие действия
Дополнительные сведения о Microsoft Graph, включая инструкции и руководства по работе, см. в следующих статьях:
Обзор
API Graph — это основной инструмент для загрузки данных на платформу Facebook и их получения оттуда. Он представляет собой API на базе HTTP, с помощью которого приложения могут программным путем запрашивать данные, публиковать новые истории, управлять рекламой, загружать фото и выполнять множество других задач.
Название API Graph подчеркивает связь этого API с «социальным графом» — системой представления информации на Facebook. Он состоит из узлов, границ контекста и полей. С помощью узлов можно получать данные о конкретном объекте, границы контекста позволяют получать подборки объектов, связанные с отдельным объектом, а поля — получать данные об отдельном объекте или о каждом объекте в подборке. В документации как узел, так и граница контекста могут называться «конечной точкой». Например, «отправьте запрос GET к конечной точке User».
Все данные передаются по протоколу HTTP/1.1, а для работы конечных точек необходим протокол HTTPS. В основе API Graph лежит протокол HTTP, поэтому он работает со всеми языками, в которых есть библиотека HTTP (например, cURL и urllib). Другими словами, API Graph можно использовать прямо в браузере. Например, запрос в браузере URL
эквивалентен следующему запросу cURL:
URL хоста
Маркеры доступа
С помощью маркеров доступа приложение может взаимодействовать с API Graph. Почти для всех конечных точек API Graph необходим тот или иной маркер доступа, поэтому при обращении к конечной точке может потребоваться указание маркера в запросе. Как правило, они выполняют две функции:
Дополнительную информацию см. в нашей документации по маркерам доступа.
Узел — это отдельный объект с уникальным ID. Например, существует множество объектов узлов User, каждый из которых имеет свой уникальный ID и соответствует отдельному человеку на Facebook. Примерами узлов социального графа Facebook являются Page, Group, Post, Photo и Comment.
Следующий пример cURL представляет собой вызов к узлу User:
По умолчанию этот запрос возвращает следующие данные в формате JSON:
Метаданные узла
Для объекта узла, такого как User, Page или Photo, можно получить список всех полей с их именами, описаниями и типами данных. Отправьте запрос GET к ID объекта с параметром metadata=1 :
Ответ JSON будет содержать свойство metadata со списком всех поддерживаемых полей выбранного узла:
Узел /me — это специальная конечная точка, которая преобразуется в ID объекта человека или Страницы, маркер доступа которых используется в вызовах API. Если у вас есть маркер доступа, следующий запрос позволит получить имя и ID пользователя:
Границы контекста
Граница контекста — это связь между двумя узлами. Например, с узлом User могут быть связаны фотографии, а с узлом Photo — комментарии. В примере ниже cURL возвращает список фотографий, которые человек опубликовал на Facebook.
Каждый возвращенный ID представляет узел Photo со сведениями о том, когда именно снимок был загружен на Facebook.
В параметр fields следующего запроса cURL добавлены имя, адрес электронной почты и фото профиля пользователя.
Возвращаемые данные
Комплексные параметры
Тип object также можно задать в синтаксисе JSON, например: <"firstkey": "firstvalue", "secondKey": 123>.
Публикация, обновление и удаление
Информацию о том, как опубликовать что-то на странице Facebook пользователя, см. в нашем руководстве по публикации на Facebook. Сведения о публикации в ленте Страницы Facebook см. в документации по API Pages.
Чтение после записи
Для конечных точек создания и обновления API Graph может моментально считывать успешно опубликованный или обновленный объект и возвращать любые поля, поддерживаемые соответствующей конечной точкой чтения.
По умолчанию возвращается ID созданного или обновленного объекта. Чтобы получить в ответе дополнительную информацию, добавьте в запрос параметр fields и список нужных вам полей. Например, чтобы опубликовать приветствие в ленте пользователя, можно выполнить следующий запрос:
Запрос вернет указанные поля в формате JSON:
Информацию о том, поддерживает ли конечная точка чтение после записи и какие имеются поля, см. в справочной документации по каждой конечной точке.
Ошибки
Если по какой-либо причине считать данные не удалось (например, в запросе указано несуществующее поле), API Graph вернет стандартное сообщение об ошибке. Дополнительные сведения см. в нашем руководстве по обработке ошибок.
Удалить узел (например, Post или Photo) обычно можно с помощью операции DELETE с указанием ID объекта:
Как правило, вы можете удалять только узлы, созданные вами. Подробнее о требованиях к операциям удаления см. в справке по конкретному узлу.
Версии
API Graph имеет несколько версий. Они выпускаются ежеквартально. Чтобы указать версию в вызове, добавьте букву «v» и номер версии в начало пути запроса. Например, так можно вызвать API версии 4.0:
Если номер версии не указан, по умолчанию будет вызвана самая старая доступная версия, поэтому рекомендуется всегда указывать номер нужной версии.
Дополнительные сведения о версиях см. в нашем руководстве по управлению версиями, а все доступные версии перечислены в журнале изменений API Graph.
API, SDK и платформы Facebook
Для подключения различных интерфейсов и разработки для разных платформ вы можете использовать различные API, SDK и платформы Facebook.
Дальнейшие действия
Приступайте к работе с API Graph: ознакомьтесь с социальным графом Facebook с помощью инструмента Graph Explorer и выполните пару запросов, чтобы получить данные.
Общие сведения об API приложений
Чтобы делегировать функции управления удостоверениями и доступом в Azure AD, необходимо зарегистрировать приложение в клиенте Azure AD. При регистрации приложения в Azure AD для него создается конфигурация удостоверения для интеграции с Azure AD.
Зачем использовать приложения и связанные с ними ресурсы?
Интерфейсы API Microsoft Graph позволяют управлять этими ресурсами и действиями, относящимися к приложениям в службе Azure Active Directory.
Управление приложениями
Регистрация приложения включает уведомление Azure AD о вашем приложении, в том числе URL-адрес его расположения, URL-адрес для отправки ответов после проверки подлинности, URI для определения приложения и многое другое. Чтобы управлять приложениями программными средствами, можно использовать интерфейсы API приложений в Microsoft Graph.
Дополнительные сведения о приложениях см. в следующих статьях:
Дополнительные сведения об управлении приложениями см. в следующих статьях:
Доступ к локальной публикации (предварительная версия)
Создание локальных профилей публикаций и управление ими, включая создание локальных агентов и групп агентов. Чтобы управлять локальными профилями публикации программными средствами, можно использовать интерфейсы API локальной публикации в Microsoft Graph.
Дополнительные сведения о локальной публикации см. в следующих статьях:
Чтобы узнать о том, как использовать интерфейсы API локальной публикации, см. следующее руководство и связанные с ним API:
Управление именем субъекта-службы (SPN)
Чтобы получить доступ к ресурсам, защищенным клиентом Azure AD, субъект, которому требуется доступ, должен быть представлен субъектом безопасности. Чтобы управлять субъектами-службами программными средствами, можно воспользоваться интерфейсами API субъекта-службы в Microsoft Graph.
Синхронизация
Можно воспользоваться интерфейсами API синхронизации в Microsoft Graph для управления синхронизацией удостоверений программными средствами, в том числе для:
Дополнительные сведения о синхронизации см. в следующих статьях:
Чтобы узнать о том, как использовать интерфейсы API локальной публикации, см. следующие руководства и связанные с ними API:
