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. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

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);
- 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 – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
- token – чтение информации о токенах приложений:
  - list – выводит список всех токенов приложений;
  - get – выводит информацию о токене по его имени;
- get_mail_servers – возвращает настройки почтового сервера для отправки оповещений;
- expiration – чтение настроек устаревания данных:
  - get_list – возвращает настройки устаревания данных для всех агрегатов модели данных;
- config – чтение настроек кластера:
  - vshard-timeout – возвращает таймаут выполнения удаленного вызова операции vshard;
  - force_yield_limits – возвращает количество чтений записей спейса, после которых происходит принудительный yield для обеспечения кооперативной многозадачности;
  - hard_limits – возвращает текущие настройки ограничений при выполнении GraphQL запросов. Может возвращать следующие значения:
    - scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
    - returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос;
  - graphql_query_chache_size – возвращает ограничение количества кэшируемых уникальных GraphQL запросов. Кэшируется только текст запроса, но не переменные.
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 – имя токена;
- 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);
- 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;
- 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 – таймаут выполнения удаленного вызова операции vshard;
  - force_yield_limits – количество чтений записей спейса, после которых происходит принудительный yield для обеспечения кооперативной многозадачности;
  - hard_limits – ограничения при выполнении GraphQL запросов. Возможные аргументы:
    - scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса;
    - returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос;
  - graphql_query_chache_size – ограничение количества кэшируемых уникальных GraphQL запросов.

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. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

query – запросы на получение информации по текущим настройкам и состоянию кластера:
- cluster – управление кластером:
  - self – позволяет получить информацию о текущем сервере (который выполняет запрос);
  - schema – возвращает схему модели данных в формате строки (YAML). Данная функция недоступна в TDG;
  - failover – возвращает текущий статус включения функции failover;
  - failover_params – возвращает текущие настройки функции failover. Может возвращать следующие значения:
    - tarantool_params – параметры подключения:
      - uri – адрес подключения;
      - password – пароль для подключения;
    - mode – режим работы (disabled, eventual или stateful);
    - state_provider – тип внешнего хранилища для режима работы stateful;
  - 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 – возвращает информацию по наборам реплик кластера;
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 вместо данной функции.

Версия:

3.2. Запросы на изменение настроек¶

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

3.2.2. Настройки Tarantool Cartridge¶