3.2. Запросы на изменение настроек¶
Этот раздел посвящен различным запросам, позволяющим изменять настройки TDG.
Все запросы на изменение настроек TDG передаются по протоколу HTTP в формате GraphQL.
При этом они должны иметь соответствующий заголовок для авторизации.
Примечание
Для выполнения 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 обладает встроенными механизмами обмена этой информацией с клиентским программным обеспечением, выполняющим запросы. Описания параметров и аргументов приведены в исключительном порядке для отдельных случаев, требующих пояснения.
3.2.1. Основные настройки TDG¶
Для выполнения запроса, его необходимо направить по протоколу HTTP на HTTP порт
любого инстанса кластера с указанием адреса ресурса (endpoint) /graphql
и
заголовком admin
, а также данными авторизации.
Пример выполнения запроса при помощи утилиты curl
:
curl --request POST \
--url http://172.19.0.2:8080/graphql \
--header 'auth-token: 2fc136cf-8cae-4655-a431-7c318967263d' \
--header 'schema: admin' \
--data '{"query":"query{ user{ list{ username } } } "}'
Далее приведены все типы запросов на чтение или изменение основных настроек TDG. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.
- query – запросы на получение информации по текущим настройкам и состоянию:
- jobs – чтение ремонтной очереди неудавшихся отложенных работ (попытка
выполнения которых закончилась неудачно, вкладка
Failed jobs
):- get_list – возвращает список объектов ремонтной очереди отложенных работ;
- repair_list – возвращает список объектов, находящихся в ремонтной очереди
(вкладка
Repair
); - get_logs – возвращает записи общего журнала событий (логи);
- tasks – чтение списка задач:
- get_list – возвращает список задач и результатов их исполнения;
- password_generator – генерация и проверка валидности паролей, чтение
настроек требований к сложности паролей:
- generate – возвращает сгенерированный пароль;
- validate – выполняет проверку переданного пароля на соответствие имеющимся требованиям к сложности пароля;
- config – возвращает текущие настройки требований к сложности пароля;
- output_processor – чтение данных ремонтной очереди объектов на отправку
(вкладка
Output Processor
):- get_list – возвращает список объектов в ремонтной очереди на отправку (объекты, отправка которых не удалась);
- servers – возвращает информацию о состоянии экземпляров TDG в кластере;
- access_role – чтение настроек ролевой модели:
- actions_list – возвращает список всех возможных действий, доступ к которым настраивается при помощи ролевой модели;
- get_access_role_actions – возвращает список действий, доступных для
роли по ее
id
; - list – возвращает список ролей;
- get – возвращает данные о роли по ее
id
;
- cartridge – чтение данных из конфигурации:
- test_soap_data – возвращает текст подсказки по умолчанию на вкладке
Test
веб-интерфейса; - self – отображает информацию о текущем сервере (экземпляре TDG);
- test_soap_data – возвращает текст подсказки по умолчанию на вкладке
- data_access_action – чтение информации о шаблонах доступа к действиям над
данными:
- list – возвращает список настроенных шаблонов доступа;
- get – возвращает информацию о шаблоне по его
id
;
- user – чтение информации о пользователях и настройке доступа анонимных
пользователей:
- is_anonymous_allowed – возвращает статус настройки, разрешающей доступ без авторизации;
- self – возвращает информацию о текущем пользователе;
- list – возвращает список пользователей;
- model – возвращает модель данных в виде строки;
- notifier_get_users – возвращает список подписчиков (вкладка
Subscribers
); - audit_log – чтение данных о журнале событий безопасности:
- get – возвращает журнал событий безопасности (аудит лог);
- enabled – возвращает статус настройки, отвечающей за включение и отключение ведения журнала аудита;
- maintenance – чтение служебной информации:
- clock_delta – данные по рассинхронизации времени на внутренних (системных)
часах инстансов. Может возвращать следующие значения:
- value – возвращает максимальное текущее значение отклонения часов между инстансами кластера;
- is_threshold_exceeded – отвечает на вопрос: превышено ли предельное значение отклонения часов среди инстансов кластера?;
- get_aggregates – возвращает список агрегатов модели данных;
- unlinked_space_list – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
- clock_delta – данные по рассинхронизации времени на внутренних (системных)
часах инстансов. Может возвращать следующие значения:
- token – чтение информации о токенах приложений:
- list – выводит список всех токенов приложений;
- get – выводит информацию о токене по его имени;
- get_mail_servers – возвращает настройки почтового сервера для отправки оповещений;
- expiration – чтение настроек устаревания данных:
- get_list – возвращает настройки устаревания данных для всех агрегатов модели данных;
- permissions – возвращает настройки доступа к данным через Permission API
(устаревшее API с использованием дискреционной модели доступа). Может
возвращать следующие значения:
- name – имя учетной записи пользователя или токена приложений;
- uid – внутренний идентификатор пользователя или токена приложений;
- agregate – информация по всем агрегатам и доступу к ним для данного пользователя или токена приложений;
- config – чтение настроек кластера:
- vshard_timeout – возвращает таймаут выполнения удаленного вызова операции vshard;
- force_yield_limits – возвращает количество чтений записей спейса, после которых происходит принудительный yield для обеспечения кооперативной многозадачности;
- hard_limits – возвращает текущие настройки ограничений при выполнении
GraphQL запросов. Может возвращать следующие значения:
- scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
- returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос;
- graphql_query_chache_size – возвращает ограничение количества кэшируемых уникальных GraphQL запросов. Кэшируется только текст запроса, но не переменные.
- jobs – чтение ремонтной очереди неудавшихся отложенных работ (попытка
выполнения которых закончилась неудачно, вкладка
- mutation – запросы на внесение изменений в настройки:
- jobs – работа с ремонтной очередью неудавшихся отложенных работ (попытка
выполнения которых закончилась неудачно, вкладка
Failed jobs
):- delete_all_jobs – удалить все отложенные работы из ремонтной очереди отложенных работ;
- try_again_all – выполнить повторную попытку обработки всех отложенных работ из ремонтной очереди отложенных работ;
- try_again – выполнить повторную попытку обработки неудавшейся
отложенной работы по ее
id
; - delete_job – удалить неудавшуюся отложенную работу по ее
id
;
- token – работа с токенами приложений:
- remove – удалить токен приложения по его имени;
- 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 – имя токена;
- state – статус (
- notifier_upsert_user – добавление нового или редактирование существующего
адреса для оповещения (вкладка
Subscribers
). Возможные аргументы:- name – имя контакта для оповещения;
- addr – адрес электронной почты;
- id – внутренний идентификатор (строка);
- clear_repair_queue – очистить ремонтную очередь (вкладка
Repair
); - password_generator – изменение настроек требований к сложности паролей пользователей;
- output_processor – работа с ремонтной очередью на отправку (вкладка
Output processor
):- clear_list – удалить все объекты на отправку из ремонтной очереди;
- try_again_all – выполнить повторную попытку обработки всех объектов на отправку из ремонтной очереди;
- try_again – выполнить повторную попытку обработки объекта на отправку
из ремонтной очереди по его
id
; - delete_from_list – удалить объект на отправку из ремонтной очереди по его
id
;
- access_role – управление настройками ролевой модели:
- delete – удаление роли пользователя по ее
id
; - create – создание новой роли пользователя. Возможные аргументы:
- name – имя новой роли;
- description – описание новой роли (необязательно);
- update – изменение имени или описания роли пользователя;
- update_access_role_actions – изменение прав доступа для роли.
Возможные аргументы:
- id – идентификатор роли;
- actions – список изменяемых прав:
- id – идентификатор права;
- allowed – данные о наличии права для роли (Boolean);
- delete – удаление роли пользователя по ее
- set_mail_server – изменение настроек почтового сервера для отправки
оповещений (см. Подробнее про модуль SMTP).
Возможные аргументы:
- username – имя учетной записи, с которой будет проводиться рассылка;
- password – пароль от учетной записи;
- url – адрес почтового сервера;
- from – адрес, указываемый в поле отправителя сообщения;
- skip_verify_host – при установке
true
позволяет пропускать проверку валидности сертификата хоста; - timeout – таймаут отправки;
- cartridge – изменение конфигурации:
- load_config_example – загружает тестовый пример конфигурации вместо имеющейся конфигурации;
- data_access_action – внесение изменений в шаблоны доступа к действиям
над данным:
- delete – удалить шаблон;
- create – добавить новый шаблон;
- update – отредактировать существующий шаблон;
- user – управление пользователями:
- import – импорт пользователя;
- add – добавление нового пользователя;
- remove – удаление существующего пользователя по его
uid
; - modify – редактирование существующего пользователя по его
uid
; - self_modify – редактирование пароля или имени учетной записи для текущего пользователя (из-под которого выполняется GraphQL запрос);
- set_state – блокирование или разблокирование пользователя;
- reset_password – сброс пароля пользователя по его
uid
;
- model – задание новой модели данных;
- tasks – управление задачами:
- start – запуск задачи по ее
id
; - stop – остановка задачи по ее
id
; - forget – удаляет один из результатов выполнения задачи по его
id
;
- start – запуск задачи по ее
- maintenance – служебные функции:
- drop_unlinked_spaces – удаление спейсов от агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
- truncate_unlinked_spaces – удаление данных из спейсов агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
- audit_log – ведение журнала событий безопасности (аудит лог):
- enabled – включение функции ведения журнала событий безопасности;
- clear – очистка журнала событий безопасности;
- severity – настройка уровня важности событий, которые будут записываться в журнал событий безопасности;
- notifier_delete_user – удаляет запись из списка подписчиков (вкладка
Subscribers
) по ееid
; - expiration – изменение настроек устаревания данных:
- set – установка значений настроек устаревания данных;
- cleanup – очистка (сброс) настроек устаревания данных по имени агрегата;
- repair_all – выполняет повторную попытку обработки всех объектов из
ремонтной очереди (вкладка
Repair
); - repair – выполняет повторную попытку обработки объекта из
ремонтной очереди (вкладка
Repair
) по егоid
; - delete_from_repair_queue – выполняет удаление объекта из
ремонтной очереди (вкладка
Repair
) по егоid
; - permissions – устанавливает настройки доступа к данным через Permission API
(устаревшее API с использованием дискреционной модели доступа). Возможные
аргументы:
- name – имя учетной записи пользователя или токена приложений;
- uid – внутренний идентификатор пользователя или токена приложений;
- agregate – информация по всем агрегатам и доступу к ним для данного пользователя или токена приложений;
- config – изменение настроек кластера:
- vshard_timeout – таймаут выполнения удаленного вызова операции vshard;
- force_yield_limits – количество чтений записей спейса, после которых происходит принудительный yield для обеспечения кооперативной многозадачности;
- hard_limits – ограничения при выполнении GraphQL запросов. Возможные
аргументы:
- scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
- returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос;
- graphql_query_chache_size – ограничение количества кэшируемых уникальных GraphQL запросов.
- jobs – работа с ремонтной очередью неудавшихся отложенных работ (попытка
выполнения которых закончилась неудачно, вкладка
3.2.2. Настройки Tarantool Cartridge¶
Для выполнения запроса, его необходимо направить по протоколу HTTP на HTTP порт
любого инстанса кластера с указанием адреса ресурса (endpoint) /admin/api
,
а также данными авторизации.
Пример выполнения запроса при помощи утилиты curl
:
curl --request POST \
--url http://172.19.0.2:8080/admin/api \
--header 'auth-token: 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 – управление кластером:
- self – позволяет получить информацию о текущем сервере (который выполняет запрос);
- schema – возвращает схему модели данных в формате строки (YAML). Данная функция недоступна в TDG;
- failover – возвращает текущий статус включения функции failover;
- failover_params – возвращает текущие настройки функции failover.
Может возвращать следующие значения:
- tarantool_params – параметры подключения:
- uri – адрес подключения;
- password – пароль для подключения;
- mode – режим работы (disabled, eventual или stateful);
- state_provider – тип внешнего хранилища для режима работы stateful;
- tarantool_params – параметры подключения:
- vshard_bucker_count – возвращает число виртуальных бакетов в кластере;
- users – возвращает список авторизованных пользователей (или информацию об одном из них, если передано имя пользователя). Данная функция недоступна в TDG;
- 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 , используемых для распределенного хранения данных;
- vshard_known_gorups – данная функция недоступна в TDG;
- can_bootstrap_vshard – имеется ли возможность вызвать функцию bootsrap_vshard
- config – возвращает текущую конфигурацию;
- servers – возвращает информацию по серверам кластера;
- replicasets – возвращает информацию по наборам реплик кластера;
- cluster – управление кластером:
- mutation – запросы на внесение изменений в настройки:
- cluster – настройки кластера:
- schema – применение новой модели данных;
- failover – включение или отключение функции автоматического восстановления;
- failover_params – настройка функции автоматического восстановления;
- check_schema – проверяет передаваемую схему модели данных (в формате
YAML строки) на применимость к текущему кластеру. Возвращает ошибку в
случае обнаружения, либо
null
в случае успешного прохождения проверки. Данная функция недоступна в TDG; - config – позволяет применить новую конфигурацию ко всему кластеру. Возвращает примененную конфигурацию в случае успеха. Данная функция недоступна в TDG;
- edit_topology – позволяет задавать топологию кластера (наборы реплик и их роли);
- auth_params – настройка параметров авторизации. Эти параметры относятся
к авторизации в Tarantool Cartridge
, а не к TDG:
- enabled – включена ли функция авторизации;
- cookie_max_age – максимальное время жизни пользовательской cookie (в секундах);
- cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить;
- add_user – добавление пользователя в Tarantool Cartridge. Данная функция недоступна в TDG;
- edit_user – редактирование пользователя в Tarantool Cartridge. Данная функция недоступна в TDG;
- edit_vshard_options – изменение настроек vshard group. Данная функция недоступна в TDG;
- failover_promote – переключение мастера в наборе реплик с указанным
id
на инстанс с указаннымid
. Работает только в stateful режиме функции автоматического восстановления (failover); - remove_user – удаление пользователя в Tarantool Cartridge. Данная функция недоступна в TDG;
- disable_servers – временное отключение инстанса от кластера. Данная функция недоступна в TDG;
- 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
вместо данной функции.
- cluster – настройки кластера: