Управление настройками через GraphQL API | Tdg
Reference Управление настройками через GraphQL API

Управление настройками через GraphQL API

Этот раздел посвящен различным запросам, позволяющим просматривать и изменять настройки TDG.

Все запросы на просмотр и изменение настроек TDG передаются по протоколу HTTP в формате GraphQL. При этом они должны иметь соответствующий заголовок для авторизации.

Note

Для выполнения GraphQL-запросов можно использовать встроенный веб-клиент GraphiQL (на вкладке Graphql веб-интерфейса) или любой сторонний GraphQL-клиент, либо иное средство для отправки HTTP-запросов. При этом специализированные GraphQL-клиенты, в отличие от средств отправки HTTP-запросов, могут использовать функции автодополнения и проверки синтаксиса запросов, а также автоматического формирования документации на GraphQL API. Данные стандартные возможности GraphQL позволяют определять состав функций API, а также состав аргументов функций, типы исходных данных и возвращаемых результатов.

GraphQL-запросы от клиентов (за исключением встроенного веб клиента GraphiQL) необходимо направлять на соответствующие адреса (endpoints):

  • /graphql (без указания схемы или с указанием в заголовке схемы default) – используется для запросов к пользовательским данным, хранящимся в TDG. Подробнее смотрите Раздел про GraphQL-запросы к данным.

  • /graphql (с указанием в заголовке схемы admin) – используется для основных настроек TDG.

  • /admin/api – используется для изменения топологии кластера и других настроек Tarantool Cartridge.

Данные по аргументам вызова функций и возвращаемым результатам не приводятся, исходя из того, что GraphQL обладает встроенными механизмами обмена этой информацией с клиентским программным обеспечением, выполняющим запросы. Описания параметров и аргументов приведены в исключительном порядке для отдельных случаев, требующих пояснения.

Основные настройки TDG

Для выполнения запроса направьте его по протоколу HTTP на HTTP-порт экземпляра кластера с ролью connector с указанием адреса ресурса (endpoint) /graphql и заголовком admin, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'schema: admin' \
  --data '{"query":"query{  user{  list{  username  }  }  }  "}'

Далее приведены все типы запросов на чтение или изменение основных настроек TDG. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию (query)

Пример запроса на получение названия роли по ее id (access_role.get):

query {
    access_role {
        get(id: 1) {
            name
        }
    }
}
query.jobs

Чтение ремонтной очереди неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

  • get_list – возвращает список объектов ремонтной очереди отложенных работ.

query.repair_list

Возвращает список объектов, находящихся в ремонтной очереди (вкладка Repair).

query.tasks

Чтение списка задач:

  • get_list – возвращает список задач и результатов их исполнения.

query.password_generator

Генерация и проверка валидности паролей, чтение настроек требований к сложности паролей:

  • generate – возвращает сгенерированный пароль.

  • validate – выполняет проверку переданного пароля на соответствие имеющимся требованиям к сложности пароля.

  • config – возвращает текущие настройки требований к сложности пароля.

query.output_processor

Чтение данных ремонтной очереди объектов на отправку (вкладка Output Processor):

  • get_list – возвращает список объектов в ремонтной очереди на отправку (объекты, отправка которых не удалась).

query.access_role

Чтение настроек ролевой модели:

  • actions_list – возвращает список всех возможных действий, доступ к которым настраивается при помощи ролевой модели.

  • get_access_role_actions – возвращает список действий, доступных для роли по ее id.

  • list – возвращает список ролей.

  • get – возвращает данные о роли по ее id.

query.cartridge

Чтение данных из конфигурации:

  • test_soap_data – возвращает текст подсказки по умолчанию на вкладке Test веб-интерфейса.

  • self – отображает информацию о текущем сервере (экземпляре TDG).

query.data_access_action

Чтение информации о шаблонах доступа к действиям над данными:

  • list – возвращает список настроенных шаблонов доступа.

  • get – возвращает информацию о шаблоне по его id.

query.user

Чтение информации о пользователях и настройке доступа анонимных пользователей:

  • is_anonymous_allowed – возвращает статус настройки, разрешающей доступ без авторизации.

  • self – возвращает информацию о текущем пользователе.

  • list – возвращает список пользователей.

query.notifier_get_users

Возвращает список подписчиков (вкладка Subscribers).

query.audit_log

Чтение данных о журнале событий безопасности:

  • get – возвращает журнал событий безопасности (аудит лог).

  • enabled – возвращает статус настройки, отвечающей за включение и отключение ведения журнала аудита.

query.maintenance

Чтение служебной информации:

  • clock_delta – данные по рассинхронизации времени на внутренних (системных) часах экземпляров. Может возвращать следующие значения:

    • value – возвращает максимальное текущее значение отклонения часов между экземплярами кластера.

    • is_threshold_exceeded – отвечает на вопрос, превышено ли предельное значение отклонения часов среди экземпляров кластера.

  • get_aggregates – возвращает список агрегатов модели данных.

  • current_tdg_version – проверяет версию TDG при применении конфигурации (только в схеме admin).

  • unlinked_space_list – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

query.token

Чтение информации о токенах приложений:

  • list – выводит список всех токенов приложений.

  • get – выводит информацию о токене по его имени. В запрос передается единственный аргумент name – имя токена.

query.get_mail_server

Возвращает настройки почтового сервера для отправки оповещений.

query.config

Чтение настроек кластера:

  • vshard-timeout – возвращает таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.

  • force_yield_limits – возвращает количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.

  • hard_limits – возвращает текущие настройки ограничений при выполнении GraphQL-запросов. Может возвращать следующие значения:

    • scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.

    • returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.

  • graphql_query_cache_size – возвращает ограничение количества кэшируемых уникальных GraphQL-запросов. Кэшируется только текст запроса, но не переменные.

  • locked_sections_list – Список закрепленных секций. Если в список закрепленных секций добавить любую секцию, например, секцию metrics, а потом загрузить новый файл конфигурации, в котором секции metrics не будет, то эта секция не удалится – вместо нее будет использована последняя загруженная версия секции metrics. Прописать закрепленные секции в файле конфигурации явным образом нельзя.

query.account_provider

Управление доступом:

  • ldap – возвращает конфигурацию LDAP.

query.checks

Валидация различных настроек:

  • cron_syntax – проверяет корректность синтаксиса заданного cron-выражения.

  • storage_dir_writable – проверяет возможность записи в заданную директорию.

query.data_type

Доступ к текущей модели данных:

  • model – возвращает текущую модель данных.

  • expiration – возвращает настройки устаревания данных.

  • versioning – возвращает параметры версионирования модели данных.

query.logs

Доступ к общему журналу событий:

  • get – возвращает записи общего журнала событий (логи).

  • config – возвращает конфигурацию журнала событий.

query.metrics

Доступа к метрикам:

  • config – возвращает настройки метрик.

query.migration

Управление миграцией данных:

  • stats – возвращает ход выполнения миграции данных.

query.settings

Настройки учетной записи:

  • get – возвращает настройки учетной записи.

Запросы на внесение изменений в настройки (mutation)

Пример запроса на изменение настроек требований к сложности паролей пользователей (password_generator.config):

mutation {
    password_generator {
        config(lower: true, digits: true, symbols: false, min_length: 6)
    }
}
mutation.jobs

Работа с ремонтной очередью неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

  • delete_all_jobs – удалить все отложенные работы из ремонтной очереди отложенных работ.

  • try_again_all – выполнить повторную попытку обработки всех отложенных работ из ремонтной очереди отложенных работ.

  • try_again – выполнить повторную попытку обработки неудавшейся отложенной работы по ее id.

  • delete_job – удалить неудавшуюся отложенную работу по ее id.

mutation.token

Работа с токенами приложений:

  • removeудалить токен приложения по его имени. В запрос передается единственный аргумент name – имя токена.

  • importимпортировать токен приложения. Возможные аргументы:

    • state_reason (опционально) – пояснение к присвоению текущего статуса.

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • uid – внутренний ID токена.

    • role – имя роли из ролевой модели доступа.

    • state – статус (active/blocked).

    • created_at – дата и время создания в формате Unix time.

    • name – имя токена.

    • last_login (опционально) – дата и время последнего входа в формате Unix time.

    • unblocked_at (опционально) – дата и время последней разблокировки в формате Unix time.

  • addдобавить новый токен приложения. Возможные аргументы:

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • name – имя токена.

    • role – имя роли из ролевой модели доступа.

  • updateотредактировать данные токена приложения (срок действия или роль). Возможные аргументы:

    • expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.

    • name – имя токена.

    • role – имя роли из ролевой модели доступа.

  • set_stateизменить статус токена приложения (заблокировать или разблокировать). Возможные аргументы:

    • state – статус (active/blocked/new).

    • reason (опционально) – пояснение к присвоению нового статуса.

    • name – имя токена.

mutation.notifier_upsert_user

Добавление нового или редактирование существующего адреса для оповещения (вкладка Subscribers). Возможные аргументы:

  • name – имя контакта для оповещения.

  • addr – адрес электронной почты.

  • id – внутренний идентификатор (строка).

mutation.clear_repair_queue

Очистить ремонтную очередь (вкладка Repair).

mutation.password_generator

Изменение настроек требований к сложности паролей пользователей.

mutation.output_processor

Работа с ремонтной очередью на отправку (вкладка Output processor):

  • clear_list – удалить все объекты на отправку из ремонтной очереди.

  • try_again_all – выполнить повторную попытку обработки всех объектов на отправку из ремонтной очереди.

  • try_again – выполнить повторную попытку обработки объекта на отправку из ремонтной очереди по его id.

  • delete_from_list – удалить объект на отправку из ремонтной очереди по его id.

mutation.access_role

Управление настройками ролевой модели:

  • delete – удаление роли пользователя по ее id.

  • create – создание новой роли пользователя. Возможные аргументы:

    • name – имя новой роли.

    • description (опционально) – описание новой роли.

  • update – изменение имени или описания роли пользователя.

  • update_access_role_actions – изменение прав доступа для роли. Возможные аргументы:

    • id – идентификатор роли.

    • actions – список изменяемых прав:

      • id – идентификатор права.

      • allowed – данные о наличии права для роли (Boolean).

mutation.set_mail_server

Изменение настроек почтового сервера для отправки оповещений (см. Подробнее про модуль SMTP). Возможные аргументы:

  • username – имя учетной записи, с которой будет проводиться рассылка.

  • password – пароль от учетной записи.

  • url – адрес почтового сервера.

  • from – адрес, указываемый в поле отправителя сообщения.

  • skip_verify_host – при установке true позволяет пропускать проверку валидности сертификата хоста.

  • timeout – таймаут отправки.

mutation.cartridge

Изменение конфигурации:

  • load_config_example – загружает тестовый пример конфигурации вместо имеющейся конфигурации.

mutation.data_access_action

Внесение изменений в шаблоны доступа к действиям над данным:

  • delete – удалить шаблон.

  • create – добавить новый шаблон.

  • update – отредактировать существующий шаблон.

mutation.user

Управление пользователями:

  • import – импорт пользователя.

  • add – добавление нового пользователя.

  • remove – удаление существующего пользователя по его uid.

  • modify – редактирование существующего пользователя по его uid.

  • self_modify – редактирование пароля или имени учетной записи для текущего пользователя (из-под которого выполняется GraphQL-запрос).

  • set_state – блокирование или разблокирование пользователя.

  • reset_password – сброс пароля пользователя по его uid.

mutation.tasks

Управление задачами:

  • start – запуск задачи по ее id.

  • stop – остановка задачи по ее id.

  • forget – удаляет один из результатов выполнения задачи по его id.

mutation.maintenance

Служебные функции:

  • drop_unlinked_spaces – удаление спейсов от агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

  • truncate_unlinked_spaces – удаление данных из спейсов агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

mutation.audit_log

Ведение журнала событий безопасности (аудит лог):

  • enabled – включение функции ведения журнала событий безопасности.

  • clear – очистка журнала событий безопасности.

  • severity – настройка уровня важности событий, которые будут записываться в журнал событий безопасности.

mutation.notifier_delete_user

Удаляет запись из списка подписчиков (вкладка Subscribers) по ее id.

mutation.repair_all

Выполняет повторную попытку обработки всех объектов из ремонтной очереди (вкладка Repair).

mutation.repair

Выполняет повторную попытку обработки объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.delete_from_repair_queue

Выполняет удаление объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.config

Изменение настроек кластера:

  • vshard-timeout – таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.

  • force_yield_limits – количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.

  • hard_limits – ограничения при выполнении GraphQL-запросов. Возможные аргументы:

    • scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.

    • returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.

  • graphql_query_cache_size – ограничение количества кэшируемых уникальных GraphQL-запросов.

mutation.account_provider

Управление доступом:

  • ldap – позволяет изменить конфигурацию LDAP.

mutation.backup

Управление резервным копированием конфигураций:

  • config_apply – применяет конфигурацию заданной версии.

  • config_delete – удаляет конфигурацию заданной версии.

  • config_save_current – создает резервную копию конфигурации с заданным комментарием.

  • settings – изменяет настройки резервного копирования конфигураций.

mutation.connector

Управление коннекторами:

  • http_request – отправляет заданный объект используя HTTP.

  • soap_request – отправляет заданный объект используя SOAP.

mutation.data_type

Доступ к текущей модели данных:

  • model – позволяет изменить текущую модель данных.

  • expiration – позволяет изменить настройки устаревания данных.

  • versioning – позволяет изменить версию модели данных.

mutation.expiration_cleanup

Очистка (сброс) настроек устаревания данных по имени агрегата.

mutation.logs

Управление общим журналом событий:

  • truncate – очищает журнал событий.

  • config – позволяет изменить конфигурацию журнала событий.

mutation.metrics

Управление метриками:

  • config – позволяет изменить настройки метрик.

mutation.migration

Управление миграцией данных:

  • apply – позволяет поменять настройки миграции данных.

  • dry_run – запускает миграцию данных.

mutation.settings

Управление настройками учетной записи:

  • put – добавляет заданные настройки учетной записи.

  • delete – удаляет заданные настройки учетной записи.

Настройки Tarantool Cartridge

Для выполнения запроса, его необходимо направить по протоколу HTTP на HTTP порт любого экземпляра кластера с указанием адреса ресурса (endpoint) /admin/api, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/admin/api \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'content-type: application/json' \
  --data '{"query":"query{\n  cluster{\n    known_roles{\n      name\n      dependencies\n    }\n  }\n}"}'

Далее приведены все типы запросов на чтение или изменение основных настроек Tarantool Cartridge. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию кластера (query)

Пример запроса на получение информации о пользователе по его имени (cluster.users):

query {
    cluster {
        users { username }
    }
}
query.cluster

Управление кластером:

  • self – позволяет получить информацию о текущем сервере (который выполняет запрос).

  • failover – возвращает текущий статус включения функции failover.

  • failover_params – возвращает текущие настройки функции failover. Может возвращать следующие значения:

    • tarantool_params – параметры подключения:

      • uri – адрес подключения.

      • password – пароль для подключения.

    • mode – режим работы (disabled, eventual или stateful).

    • state_provider – тип внешнего хранилища для режима работы stateful.

  • vshard_bucker_count – возвращает число виртуальных бакетов в кластере

  • issues – возвращает список проблем (issues), зарегистрированных в кластере.

  • auth_param – возвращает параметры авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не в TDG:

    • enabled – включена ли функция авторизации.

    • username – имя текущего пользователя.

    • cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).

    • cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.

    • implements_add_user – в кластере реализована функция добавления пользователей.

    • implements_remove_user – в кластере реализована функция удаления пользователей.

    • implements_edit_user – в кластере реализована функция редактирования пользователей.

    • implements_list_user – в кластере реализована функция вывода списка пользователей.

    • implements_get_user – в кластере реализована функция вывода информации о конкретном пользователе.

    • implements_check_password – в кластере реализована функция проверки аутентификатора пользователя.

  • known_roles – возвращает список всех известных ролей экземпляров и их зависимостей.

  • webui_blacklist – возвращает список страниц веб-интерфейса, которые должны быть скрыты (исключены из отображения). Обычно это те страницы, доступ к которым запрещен (запрет доступа осуществляется другими механизмами).

  • vshard_groups – информация об имеющихся группах модуля vshard, используемых для распределенного хранения данных.

  • can_bootstrap_vshard – имеется ли возможность вызвать функцию bootsrap_vshard.

  • config – возвращает текущую конфигурацию.

query.servers

Возвращает информацию по серверам кластера.

query.replicasets

Возвращает информацию по наборам реплик кластера.

Запросы на внесение изменений в настройки (mutation)

Пример запроса на изменение настроек автоматического восстановления (cluster.failover):

mutation {
    cluster {
        failover(enabled: false)
    }
}
mutation.cluster

Настройки кластера:

  • schema – применение новой модели данных.

  • failover – включение или отключение функции автоматического восстановления.

  • failover_params – настройка функции автоматического восстановления.

  • edit_topology – позволяет задавать топологию кластера (наборы реплик и их роли).

  • auth_params – настройка параметров авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не к TDG:

    • enabled – включена ли функция авторизации.

    • cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).

    • cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.

  • failover_promote – переключение мастера в наборе реплик с указанным id на экземпляр с указанным id. Работает только в stateful-режиме функции автоматического восстановления (failover).

  • edit_server – редактирование основных параметров сервера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • probe_server – проверяет, доступен ли экземпляр по указанному адресу для подключения его к кластеру.

  • edit_replicaset – редактирование основных параметров набора реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • join_server – подключение нового экземпляра к существующему набору реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

  • bootstrap_vshard – при вызове происходит распределение данных по серверам (См. bootsrap_vshard).

  • expel_server – необратимое удаление сервера из кластера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

Found what you were looking for?
Feedback