Общие сведения
GraphQL API предоставляет сторонним приложениям гибкий интерфейс для запроса информации, содержащейся в Системе.
Данный API позволяет запрашивать ровно тот набор информации, который необходим, уменьшая число запросов к API и уменьшая сложность фильтрации и последующей обработки данных. Также GraphQL позволяет упростить подключение API к приложениям за счёт строго типизированной схемы.
Выполнение запроса
Чтобы получить данные необходимо выполнить HTTP GET-запрос на URL:
http://{host}/graphql?query={query}
где:
host- хост;query- текст запроса.
Токен необходимо передавать в header: bearer_token
Пример запроса:
https://localhost:44382/graphql?query=query {users{edges{node{id username}}}}
Пример ответа:
{
"data": {
"users": {
"edges": [
{
"node": {
"id": "2eac9e38-f0cd-4ce0-9b72-d61c9a1389dd",
"username": "test"
}
},
{
"node": {
"id": "9d806522-5492-4dbb-8d96-f77e04f6c0dd",
"username": "avanpost"
}
}
]
}
}
}
Аутентификация
Аутентификация осуществляется посредством Access Token, передаваемого в запросе.
Для получения Access Token следует использовать один из двух методов:
- Аутентификацию посредством OAuth 2.0 Client Credentials Flow;
- Аутентификацию посредством OAuth 2.0 Password Flow.
Получение схемы
При развёртывании API на стандартном URI /graphql на том же хосте, что и веб-интерфейс аутентификации Системы, актуальную схему можно получить запросом:
curl -H "Authorization: bearer token" https://host/graphql
где:
token- актуальный OAuth Access Token.;host- хост, на котором размещается сервис.
Более подробно способы получения и работы со схемой описаны в https://graphql.org/learn/introspection/.
Структура данных
AccessObject { # объект доступа
id
code
name
type
category
appId
accessObjectPrivileges {
...
}
}
AccessobjectPrivilege { # право в объекте доступа
id
code
name
}
Application { # приложение
id
name
enabled
visible
type
… # еще много всего
accessObjects {
...
}
}
Group { # группа
id
name
description
…
groupApplications {
...
}
}
Role { # роль
id
name
type
description
accessRolePrivileges { # = AccessobjectPrivilege
...
}
}
UserPinnedToken { # смарт карты
id
tokenType
serialNumber
vendor
model
tokenLabel
pinRequired
}
UserCustomAttribute { # доп.атрибут
id
value
userId
attrId
}
User { # пользователь
id
username
email
firstname
lastname
middlename
isLocked
active
…
userCustomAttributes {
...
}
userRoles {
...
}
userGroups {
...
}
userPinnedTokens {
...
}
}
Примеры запросов
Роли (AccessRole)
Запрос для получения списка ролей, имеющихся в системе необходимо выполнить следующий запрос:
query {
roles {
edges {
node {
id
name
type
description
accessRolePrivileges {
privilege {
id
code
name
}
}
}
}
}
}
Группы (Groups)
Запрос для получения списка групп:
query {
groups {
edges {
node {
id
name
groupApplications {
id
name
accessObjects {
id
name
accessObjectPrivileges {
id
code
name
}
}
}
}
}
}
}
Приложения (Applications)
Запрос для получения списка приложений:
query {
applications {
edges {
node {
id
name
type
enabled
visible
accessObjects {
id
name
type
category
code
accessObjectPrivileges {
id
code
name
}
}
}
}
}
}
Пользователи (Users)
Запрос для получения списка пользователей:
query {
users {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
userPinnedTokens {
id
serialNumber
vendor
tokenLabel
pinRequired
tokenType
}
userCustomAttributes {
id
attrId
userId
value
}
userGroups {
id
name
description
groupApplications {
id
name
type
accessObjects {
id
name
accessObjectPrivileges {
privilege {
id
code
name
}
}
}
}
}
userRoles {
id
name
accessRolePrivileges {
privilege {
id
code
name
}
}
}
}
}
}
}
Запрос поиска пользователя по уникальному идентификатору:
query {
users (where: {id: {eq: "9d806522-5492-4dbb-8d96-f77e04f6c0dd"}}) {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
}
}
}
}
Запрос поиска пользователя по имени пользователя:
query {
users (where: {username: {eq: "avanpost"}}) {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
}
}
}
}
Запрос поиска пользователей-членов определённой группы:
query {
users (where: {userGroups: {some: {id: {eq: "f782c15d-cf73-4dd4-b923-7331765a2fb8"}}}}) {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
}
}
}
}
Запрос поиска пользователей по роли:
query {
users (where: {userRoles: {some: {id: {eq: "edb7e968-547d-4773-80e1-8712998e62da"}}}}) {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
userRoles {
id
name
}
}
}
}
}
Запрос поиска пользователей, у которых есть доступ к приложению:
query {
users (where: {userGroups: {some: {groupApplications: {some: {id: {eq: "21aa4df5-74ea-4176-acf0-53b84aa164d1"}}}}}}) {
edges {
node {
id
username
email
firstname
lastname
middlename
isLocked
phoneNumberConfirmed
phoneNumberUnconfirmed
preferredLanguage
userRoles {
id
name
}
}
}
}
}
Запрос на получение дополнительных атрибутов пользователя по его идентификатору:
query {
userCustomAttributes (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
id
value
}
}
Запрос на получение ролей пользователя по его идентификатору:
query {
userRoles (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
id
name
}
}
Запрос на получение групп пользователя по его идентификатору:
query {
userGroups (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
id
name
}
}
Запрос на получение перечня приложений пользователя по его идентификатору:
query {
userApplications (uid:"9d806522-5492-4dbb-8d96-f77e04f6c0dd") {
id
name
accessObjects {
id
accessObjectPrivileges {
id
}
}
}
}