Синтаксис запросов
Интерфейс GraphQL API в настоящий момент находится в разработке, в связи с чем часть возможностей языка и системы может быть недоступна.
Для наиболее эффективного взаимодействия с GraphQL API необходимо понимать структуру и синтаксис запросов. Для полного понимания всех возможностей и ограничений языка рекомендуется ознакомиться со спецификацией GraphQL. В данной же статье описаны основные компоненты запросов и примеры их применения, основанные на схеме АЛОР Брокер GraphQL API.
Структура запроса
Основные компоненты
Структура запросов к GraphQL API оперирует двумя основными сущностями: операциями и полями.
- Операция (Operation) — метод взаимодействия с данными, хранящимися в системе.
- Поле (Field) — единица данных, запрошенная у системы или указатель пути к ней.
query {
instrument(symbol: "SBER", exchange: "MOEX", board: "TQBR") {
basicInformation {
description
shortName
type
market
}
currencyInformation {
nominal
settlement
}
}
}
Где:
query
— тип операцииinstrument
,basicInformation
,currencyInformation
и прочие — поля, указывающие путь к запрашиваемым данным
Параметры symbol
, exchange
и board
— обязательные аргументы поля instrument
, без которых запрос к нему не может быть выполнен. Подробнее об аргументах в разделе Дополнительные компоненты.
Подробнее о каждом из компонентов:
Операции
GraphQL API торговой системы АЛОР Брокер поддерживает только один тип операций — query
.
Сообщения этого типа операций обеспечивают однократное взаимодействие с сервером и используются для получения данных от системы. В качестве транспортного протокола для этого типа операций используется HTTP. По функционалу операции этого типа схожи с GET-запросами к HTTP API, но выполняются при этом с помощью POST-запросов.
Для обозначения типа операции добавьте его на корневой уровень запроса.
- Можно не указывать тип операции, если тело запроса содержит только одну операцию, в которой не используются переменные и директивы. В противном случае тип операции должен быть указан
- Для добавления аргументов (например, объявления переменных) в корень запроса операция должна иметь имя
Поля
Поля — основа запроса в GraphQL. Полями описываются как сами данные, к которым обращён запрос, так и путь до них. Для удобства можно разделить их следующим образом:
- Поле данных — поле, непосредственно указывающее на данные, которые можно запросить у системы
- Поле пути — указатель пути до поля данных согласно структуры схемы
query {
instrument(symbol: "SBER", exchange: "MOEX", board: "TQBR") {
basicInformation {
description
shortName
type
market
}
currencyInformation {
nominal
settlement
}
}
}
В запросе выше присутствуют оба типа полей:
instrument
,basicInformation
иcurrencyInformation
— поля пути, имеющие собственные вложения и указывающие путь к данным согласно структуры схемыdescription
,shortName
и прочие — поля данных, определяющие сами данные для возвращения сервером
В схеме поля могут быть представлены как type
, object
или interface
(или их содержимое) в зависимости от роли поля в структуре данных.
Так, например, запрос выше включает в себя interface Instrument
, type BasicInformation
, type CurrencyInformation
и их содержимое.
- В теле запроса должно быть указано как минимум одно поле данных
- Все поля пути, составляющие путь к полю данных, должны быть указаны в теле запроса согласно схеме
Дополнительные компоненты
Помимо основных компонентов, характеризующих структуру запрашиваемых данных, GraphQL поддерживает также ряд дополнительных параметров, упрощающих работу с системой:
- Именованная операция — возможность присвоить операции уникальное имя. Именование операций не только помогает отличать различные операции друг от друга в системе, но и требуется для использования некоторых других возможностей языка, например, назначения переменных.
- Аргумент (Argument) — дополнительный параметр запроса, уточняющий поиск данных или ограничивающий их выдачу.
- Псевдоним (Alias) — заданное отправителем запроса имя поля, объекта или интерфейса, под которым система вернёт запрошенные данные вместо определённого системой.
- Переменная (Variable) — инструмент параметризации запроса, позволяющий указывать и передавать значения аргументов не напрямую в теле операции, а с помощью отдельного словаря переменных.
- Фрагмент (Fragment) — инструмент, дающий возможность переиспользовать поля, объекты и интерфейсы в нескольких запросах без необходимости прописывать их для каждого запроса отдельно.
- Директива (Directive) — инструмент динамического управления запросами, определяющий выполняемые в рамках операции действия и условия в соответствии с переданными данными.
В некоторых случаях аргументы могут быть обязательным параметром для выполнения запроса. Если в схеме у объекта, интерфейса или операции прописаны аргументы с восклицательным знаком !
после формата значения — этот аргумент обязателен для заполнения и без него запрос не будет выполнен.
query customQueryName($customSymbolName1: String!, $customSymbolName2: String!, $getBasicInfo: Boolean!, $getCurrencyInfo: Boolean!) {
CustomInstrument1: instrument(symbol: $customSymbolName1, exchange: "MOEX", board: "TQBR") {
basicInformation @include(if: $getBasicInfo) {
...basicInfoSelectionSet
}
currencyInformation @include(if: $getCurrencyInfo) {
...currencyInfoSelectionSet
}
}
CustomInstrument2: instrument(symbol: $customSymbolName2, exchange: "MOEX", board: "TQBR") {
basicInformation @include(if: $getBasicInfo) {
...basicInfoSelectionSet
}
currencyInformation @include(if: $getCurrencyInfo) {
...currencyInfoSelectionSet
}
}
}
fragment basicInfoSelectionSet on BasicInformation {
description
shortName
type
market
}
fragment currencyInfoSelectionSet on CurrencyInformation {
settlement
nominal
}
{
"customSymbolName1": "SBER",
"customSymbolName2": "VTBR",
"getBasicInfo": true,
"getCurrencyInfo": false
}
Где:
customQueryName
— имя операции$customSymbolName1
,$customSymbolName2
,$getBasicInfo
и$getCurrencyInfo
— переменные, чьи значения подставляются в текст запроса при его обработке системой. Значения переменных заданы в отдельном словаре переменных в формате JSONCustomInstrument1
иCustomInstrument2
— псевдонимы интерфейсаinstrument
, позволяющие в одном запросе получить данные по одинаковым полям для разных инструментовbasicInfoSelectionSet
иcurrencyInfoSelectionSet
— фрагменты, позволяющие переиспользовать входящие в объектыBasicInformation
иCurrencyInformation
строки в нескольких интерфейсах@include(if: $getBasicInfo)
и@include(if: $getCurrencyInfo)
— директивы, указывающие на добавление объектовBasicInformation
иCurrencyInformation
в зависимости от значений переменных$getBasicInfo
и$getCurrencyInfo
- Всё, что заключено в круглые скобки — аргументы задействованных объектов, интерфейсов и операций
Подробнее о каждом из компонентов:
Имя операции
Каждой операции в сообщении, передаваемом системе для обработки, можно назначить уникальное имя. Присвоение имени операции полезно, когда требуетс я:
- Объявить в операции переменные, которые задаются как аргументы имени операции
- Передать в одном документе несколько операций с возможностью их идентификации
Объявление переменных описано ниже, в связи с чем остановимся на идентификации нескольких операций в одном документе.
Документом в GraphQL называется тело сообщения, в котором передаётся вся полезная нагрузка, обрабатываемая сервером, за исключением значений переменных, которые передаются в отдельном словаре.
В одном документе может размещаться одновременно несколько не связанных друг с другом операций, которые могут передаваться как по одной за раз, так и все разом. Присвоение операции уникального имени позволяет идентифицировать её среди прочих и передавать только те операции, которые соответствуют текущим потребностям.
Имена операций не зависят от схемы напрямую и определяются самим пользователем. Предзаданные в схеме имена операций должны расцениваться пользователем как вызванная структурой схемы необходимость или вариант обозначения той или иной операции.
Для присвоения операции собственного имени достаточно указать его после типа операции:
query Instrument {
instrument(symbol: SBER, exchange: MOEX, board: TQBR) {
basicInformation {
...
}
}
}
Где:
Instrument
— имя операции
- Имя операции должно быть уникальным для документа
- Количество имён операций на один документ не ограничени
- Заданное имя не должно полностью повторять имена других компонентов запроса, схемы или служебных элементов GraphQL (например,
type
)
Аргументы
Аргументы позволяют указать дополнительные параметры операции или поля. В случае с полями такие дополнительные параметры позволяют уточнить или ограничить возвращаемые системой данные, тогда как для операций аргументы позволяют объявить используемые в запросе переменные. Ближайшим аналогом аргументов в GraphQL можно назвать Query-параметры запросов к HTTP API.
Для полей перечень доступных аргументов определяется схемой и заключается в круглые скобки:
instrument(symbol: String!, exchange: String!, board: String!): Instrument
Где:
Instrument
— интерфейс, поля которого будут использованы при поиске данных и составлении ответа системойinstrument
— псевдоним, которым вызывается интерфейс. Именно псевдоним выступает в качестве поля в запросеsymbol
,exchange
,board
— аргументы псевдонима для уточнения запросаString
— формат данных, которому должно соответствовать передаваемое значение
Следуя схеме, запрос с аргументами будет выглядеть следующим образом:
{
instrument(symbol: "SBER", exchange: "MOEX", board: "TQBR") {
basicInformation {
...
}
}
}