Содержание статьи
Майкл Голод
Недавняя дискуссия на graphql-europe заставила меня понять, что GraphQL станет отличным API для администрирования баз данных.
Вы знаете это множество функций и опций для контроля деталей безопасности, индексирования, метаданных, кластеризации и других операций?
Я использовал поездку домой в поезде, чтобы создать конечную точку администратора GraphQL для Neo4j, показывая все доступные процедуры в виде запросов или мутаций. Используя Kotlin, это, к счастью, было всего несколькими строками (200) кода. И это сработало на удивление хорошо.
Если вы знаете любую другую базу данных, открывающую свой админ-API через GraphQL, пожалуйста, сообщите мне в комментариях — я хотел бы посмотреть.
И если вы получите вдохновение, чтобы основать некоторые свои работы на этой идее, я буду благодарен, тем более со ссылкой на авторство 🙂
TL; DR
Вы можете получить ваш Neo4j Admin API по адресу /graphql/admin путем установки последней версии neo4j-graphqlрасширение. В Neo4j Desktop просто нажмите «Установить GraphQL» в разделе «Плагины» базы данных (version 3.4.0.1). Возможно, вам понадобится настроить a основное название авторизации для учетных пользовательских данных базы данных. Тогда вы готовы спросить свой новый блестящий администратор API через GraphiQL или GraphQL Playground.
Конечная точка есть не ограничиваясь встроенными процедурами. Внешние библиотеки, такие как APOC, graph-algorithms или neo4j-spatial, открываются автоматически.
Преимущества
В моей книге наибольшим преимуществом является то самодокументирующий характер API GraphQL на основе предоставленной строгой схемы.
Надежная типизация, документация и параметры по умолчанию как для типов ввода, так и для вывода увеличивают четкость и уменьшить количество попыток и ошибок. Специальный выбор исходных полей и дополнительный более глубокий обход структур результатов позволяет быстро настроить то, что вы хотите получить.
С четкое разделение в запросах чтения и мутациях записи легко рассуждать о влиянии на вызов.
И конечно же удивительное автозаполнение со встроенной справкой а автоматически доступная документация в GraphiQL и GraphQL-Playground оказывают взаимодействие с таким API в удовольствие. ?
Параметрирование все входящие данные и ограничение размеров результатов – это просто вишен на ?.
Еще одно преимущество в том, что вы можете комбинировать несколько запросов в один звонок. Вся релевантная информация для полноэкранного режима получается в одном запросе.
Конечно, вы можете использовать все доступные инструменты GraphQL в качестве промежуточного программного обеспечения или библиотеки для быстрого создания внешних программ (apollo-tools, React, semantic-ui, victory и т.п.). Это позволяет быстро интегрировать эти API в ваши сценарии мониторинга/администрирования или информационные панели.
Детали внедрения
Как и обычная конечная точка GraphQL в neo4j-graphql, это расширение сервера, обслуживающего конечные точки GET, POST и OPTIONS. Они принимают запросы, переменные и названия операций выполнить внутри одной транзакции. После выполнения, в результаты или ошибки возвращаются клиенту в виде JSON.
Необходимая схема graphql построена из доступных определенных пользователем процедур, развернутых в Neo4j.
Вы должны четко разрешить открыть процедуры через настройки конфигурации graphql.admin.procedures.(read/write) с синтаксисом процедуры Neo4j или именами полей конечной точки администратора. Например, вы можете установить его на:
graphql.admin.procedures.read=db.*,dbms.components,dbms.queryJ*graphql.admin.procedures.write=db.create*,dbIndexExplicitFor*Определенные пользователем процедуры
В 2016 году Neo4j 3.0 получил новую точку расширения. Вы можете предоставить аннотированные методы Java как определенные пользователем процедуры, которые затем можно было вызвать как отдельно, так и часть запросов в базу данных. Поскольку наш (на основе React) Neo4j-браузер перешел от HTTP к бинарному транспорту, начальные REST-API управления были дополнены процедурами, обеспечивающими ту же функциональность.
Каждая процедура может занять параметры и возвращает a поток данных со столбцами с индивидуальными названиями, подобными результатам обычных запросов. Как входы, так и выходы могут использовать типы данных из системы типов Cypher.
call dbms.listConfig('dbms.connector.http') yield name, value, description;╒══════════════════════════════╤═══════╤════════════════════════╕│"name" │"value"│"description" │╞══════════════════════════════╪═══════╪════════════════════════╡│"dbms.connector.http.enabled" │"true" │"Enable this connector."│├──────────────────────────────┼───────┼────────────────────────┤│"dbms.connector.https.enabled"│"true" │"Enable this connector."│└──────────────────────────────┴───────┴────────────────────────┘С тех пор большое количество функциональных возможностей было перемещено в процедуры и функции, что дало нам широкий выбор вещей для раскрытия через GraphQL.
Чтобы построить схему, я перебрал доступные процедуры, создав одну поле для каждой процедуры.
Я взял названные параметры процедуры как входные аргументы и использовался специальные типы вывода (за процедуру), содержащую возвращенные столбцы. Входящие параметры со значениями по умолчанию могут быть обнуляется, другие определяются как ненулевые. Описания процедур превратились в описания полейи депрессия также была передана информация.
Я сопоставил основные скалярные типы и списки с типами GraphQL.
Только для Map (dict/object) нужно ли сопоставить тип a List<Attribute> где каждый атрибут
type Attribute { name: String! value: String type: String! = "String"}который удивительно хорошо работал как для входов, так и выходов.
Подобным образом я создал специальные типы для Node, Relationship и Path.
Для этих четырех пользовательских типов я добавил соответствующий код (де)сериализации. Остальные неизвестные типы были переведены в строки.
The резольвер только для каждого поля выполняет завернутую процедуру с входными аргументами из среды. Затем результаты отображаются в поля типа исходных данных (по желанию трансформируются) и возвращаются к конечной точке.
На основе их метаданных я объединил поля в типы объектов для запросов и мутаций соответственно.
И это было в основном.
Я сам был удивлен, когда запустил GraphiQL после развертывания расширения, которое я мог интуитивно вызвать любой из запросов и мутаций без ошибок.
Проблемы
Мой самый большой вызов – это отсутствие пространств имен в GraphQL. Хотя вы можете хорошо структурировать запросы с помощью вложенных типов, то же недоступно для мутаций.
Я решил, чтобы имена API были последовательными для обоих не подструктурировать запросы и подобные мутации, а вместе объединили части пространства имен и процедуры с прописной буквы вместе.
Поэтому db.labels превращается в dbLabels .
Еще одной небольшой проблемой было отсутствие информации об операциях чтения и записи в файле DBMS и SCHEMA объемы процедур Neo4j Поэтому мне пришлось использовать a белый список для определения «лишь для чтения», чего, конечно, недостаточно.
Знатные особы
То, что не встроено в другие технологии API, и это действительно круто, это возможность выбирать любое количество запросов или мутаций, которые вы хотите запустить в единственный запрос.
Если необходимо, вы можете создать псевдоним для нескольких вызовов одного запроса с различными параметрами (подумайте о статистике для каждой базы данных).
И вы даже можете запускать алгоритмы графиков или операторы шифрования как часть этого API, что очень круто.
Следующие шаги
Теперь я непосредственно открываю пользователям параметры и результаты процедур. В дальнейшем было бы неплохо выводить типы высшего уровня, предлагающие собственные (динамические) поля запроса, например
- тип метки, который также может возвращать количество
- тип сервера, который может придавать свою роль кластеру или другую локальную информацию
- добавление более динамических полей с параметрами к типу узла или связи для пользовательского обхода
Я хотел бы? пучок ммониторинг и управление мобильными, веб-приложениями и клиентами командной строки строить этаж tего API управления.
Я рад увидеть, где мы можем улучшить удобство использования и какие отзывы и запросы мы получаем. Конечно, первой целью было бы графическое приложение для Neo4j Desktop. Так что если вас интересует что-то из этого, пожалуйста, свяжитесь и поговорим.
Счастливого взлома! – Майкл
Если у вас возникнут проблемы, пожалуйста, добавьте комментарий или устраните проблему на GitHub.