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 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
--header 'schema: admin' \
--data '{"query":"query{ user{ list{ username } } } "}'
Далее приведены все типы запросов на чтение или изменение основных настроек TDG. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.
3.2.1.1. Запросы на получение информации по текущим настройкам и состоянию (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 — возвращает список агрегатов модели данных;
- tdg-version — проверяет версию TDG при применении конфигурации (только в схеме admin);
- unlinked_space_list — возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
- clock_delta — данные по рассинхронизации времени на внутренних (системных)
часах экземпляров. Может возвращать следующие значения:
token — чтение информации о токенах приложений:
- list — выводит список всех токенов приложений;
- get — выводит информацию о токене по его имени;
get_mail_servers — возвращает настройки почтового сервера для отправки оповещений;
expiration — чтение настроек устаревания данных:
- get_list — возвращает настройки устаревания данных для всех агрегатов модели данных;
config — чтение настроек кластера:
- vshard-timeout — возвращает таймаут выполнения удаленного вызова для
операции модуля Tarantool
vshard
; - force_yield_limits — возвращает количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности;
- hard_limits — возвращает текущие настройки ограничений при выполнении
GraphQL-запросов. Может возвращать следующие значения:
- scanned — ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
- returned — ограничение числа записей, которые могут быть возвращены в ответе на запрос;
- graphql_query_chache_size — возвращает ограничение количества кэшируемых уникальных GraphQL-запросов. Кэшируется только текст запроса, но не переменные;
- locked_sections_list — список закрепленных секций.
Если в список закрепленных секций добавить любую секцию, например, секцию
metrics
, а потом загрузить новый файл конфигурации, в котором секцииmetrics
не будет, то эта секция не удалится — вместо нее будет использована последняя загруженная версия секцииmetrics
. Прописать закрепленные секции в файле конфигурации явным образом нельзя. Список обновляется посредством мутаций.
- vshard-timeout — возвращает таймаут выполнения удаленного вызова для
операции модуля Tarantool
3.2.1.2. Запросы на внесение изменений в настройки (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
;config — изменение настроек кластера:
- vshard-timeout — таймаут выполнения удаленного вызова для
операции модуля Tarantool
vshard
; - force_yield_limits — количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности;
- hard_limits — ограничения при выполнении GraphQL запросов. Возможные аргументы:
- scanned — ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
- returned — ограничение числа записей, которые могут быть возвращены в ответе на запрос;
- graphql_query_chache_size — ограничение количества кэшируемых уникальных GraphQL запросов;
- locked_sections_add — добавление секции в список закрепленных секций файла конфигурации;
- locked_sections_delete — удаление секции из списка закрепленных секций файла конфигурации. Больше информации про закрепленные секции.
- vshard-timeout — таймаут выполнения удаленного вызова для
операции модуля Tarantool
3.2.2. Настройки 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. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.
3.2.2.1. Запросы на получение информации по текущим настройкам и состоянию кластера (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 — возвращает информацию по наборам реплик кластера.
3.2.2.2. Запросы на внесение изменений в настройки (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
вместо данной функции.