3. Запросы из внешних систем / 3.2. Запросы на изменение настроек
3. Запросы из внешних систем / 3.2. Запросы на изменение настроек

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

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);
    • 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 – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные;
    • 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 запросов. Кэшируется только текст запроса, но не переменные.
  • 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;
    • 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 запросов.

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;
      • 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.1.6. Взаимодействие с kafka