API ZDS

Назначение API

API ZDS делится на три группы:

внешнее API для клиентских операций нижнего слоя хранения;
внутреннее API для обмена между узлами кластера;
административное API для сопровождения и служебных действий.

Такое разделение важно сохранять и в документации, и в конфигурации сервиса. Внешний клиентский запрос и межузловой обмен не должны описываться как один и тот же тип операций.

Внешнее API

Внешнее API используется для операций с файлами и вольюмами на уровне самого сервиса ZDS.

Операции с файлами

Метод	Путь	Назначение	Кто вызывает
`GET`	`/get_file`	Получение файла	Внешний клиент или вышестоящий сервис
`PUT`	`/upload_file`	Загрузка файла	Внешний клиент или вышестоящий сервис
`GET`	`/stat_file`	Получение информации о файле	Внешний клиент или вышестоящий сервис
`DELETE`	`/delete_file`	Удаление файла	Внешний клиент или вышестоящий сервис
`GET`	`/count_files`	Получение количества файлов	Внешний клиент или вышестоящий сервис
`GET`	`/status`	Получение статуса узла	Внешний клиент или служба мониторинга

Основные параметры файловых операций:

volume - имя вольюма;
key - ключ объекта;
revisionId - идентификатор версии объекта;
partRevisionId - идентификатор версии части объекта;
number - номер части объекта.

В зависимости от операции могут использоваться дополнительные параметры запроса.

Операции с вольюмами

Метод	Путь	Назначение	Кто вызывает
`POST`	`/volume/init`	Создание вольюма	Внешний клиент или управляющий сервис
`DELETE`	`/volume/destroy`	Удаление вольюма	Внешний клиент или управляющий сервис
`GET`	`/volume/status`	Получение статуса вольюма	Внешний клиент или управляющий сервис
`GET`	`/volume/scan`	Листинг файлов вольюма	Внешний клиент или управляющий сервис
`GET`	`/volume/list`	Получение списка вольюмов	Внешний клиент или управляющий сервис
`GET`	`/volume/policies`	Получение доступных политик хранения	Внешний клиент или управляющий сервис

Основные параметры:

volume — имя вольюма. Допустимые символы: латинские и русские буквы (строчные и заглавные), цифры, ., -, _. Две точки подряд (..) недопустимы. При нарушении возвращается код 400;
storageClass — допустимые значения определяются политиками хранения, возвращаемыми методом /volume/policies.

Параметры политики хранения (опциональны — если не указаны, применяется политика по умолчанию):

Для EC-вольюма: data — количество частей данных, parity — количество частей чётности.
Для FC-вольюма: replicas — целевое число реплик, minReplicas — минимальное число синхронных реплик.

Комбинация storageClass и схемы хранения валидируется на стороне ZDS: схема должна быть доступна для выбранного класса хранения в соответствующей группе хранения.

Метод GET /volume/policies возвращает список доступных политик хранения, определённых в конфигурации кластера. Используется для выбора параметров при создании вольюма через /volume/init.

Пример ответа:

1[
2  { "mode": "EC", "storageClass": "SSD", "data": 2, "parity": 1 },
3  { "mode": "FC", "storageClass": "SSD", "minReplicas": 1, "replicas": 2 }
4]

Методы /volume/status и /volume/list дополнительно возвращают параметры политики хранения вольюма: allowEC, data, parity, allowFC, minReplicas, replicas.

Для операции листинга дополнительно могут использоваться:

token - continuation token;
limit - ограничение количества файлов.

Внутреннее API

Внутреннее API используется только для взаимодействия узлов ZDS между собой. Эти методы не являются внешним пользовательским интерфейсом и должны рассматриваться как внутрикластерные.

Метод	Путь	Назначение
`GET`	`/inner/status`	Получение состояния узла или кластера
`GET`	`/inner/get_metadata`	Получение метаданных с другого узла
`GET`	`/inner/get_metadata_batch`	Получение пакета метаданных
`GET`	`/inner/upload_metadata`	Передача метаданных на другой узел
`POST`	`/inner/drive/{driveIdx}/upload_part`	Загрузка части файла на внешний узел
`GET`	`/inner/drive/{driveIdx}/get_part`	Получение части файла с внешнего узла
`GET`	`/inner/drive/{driveIdx}/stat_part`	Получение информации о части файла
`DELETE`	`/inner/drive/{driveIdx}/delete_part`	Удаление части файла
`GET`	`/inner/ops`	Получение журнала операций
`POST`	`/inner/volume/init`	Инициализация вольюма на удалённом узле
`DELETE`	`/inner/volume/destroy`	Удаление вольюма на удалённом узле

Эти методы используются автоматически в процессе:

синхронизации;
обмена метаданными;
размещения частей;
восстановления после отказов.

Административное API

Административное API используется для служебного сопровождения кластера.

Метод	Путь	Назначение	Кто вызывает
`POST`	`/admin/vacuum/start`	Принудительный запуск вакуума	Администратор или служба сопровождения
`POST`	`/admin/vacuum/stop`	Принудительная остановка вакуума	Администратор или служба сопровождения
`POST`	`/admin/scan/start`	Ручной запуск сканирования с начала (checkpoint сбрасывается)	Администратор или служба сопровождения
`POST`	`/admin/scan/stop`	Принудительная остановка текущего сканирования	Администратор или служба сопровождения
`POST`	`/admin/set_external_offsets`	Замена внешних offset	Администратор или служба сопровождения
`GET`	`/admin/extended_status`	Получение расширенного статуса узла	Администратор, мониторинг или служба сопровождения

Управление фоновыми процессами

Сканирование и вакуум поддерживают два режима запуска:

Автоматический — по расписанию (workers.scan.schedule для сканирования, vacuum.windows для вакуума). Процесс запускается только внутри настроенных временных окон. При выходе из окна останавливается и сохраняет checkpoint — при следующем запуске по расписанию продолжается с места остановки. Вне окна автозапуска не происходит.
Ручной — через /admin/scan/start или /admin/vacuum/start. Работает независимо от расписания: запускается в любое время, в том числе вне настроенных окон и при полностью отключённом фоновом процессе. Checkpoint при ручном запуске сбрасывается — процесс начинается с начала.

За ходом выполнения сканирования и вакуума можно наблюдать на дашборде в панели Background Jobs.

Что важно учитывать при использовании API

При работе с API ZDS рекомендуется соблюдать следующие правила:

не смешивать внешние и внутренние endpoint’ы в интеграционных сценариях;
использовать внутренние методы только в рамках самого кластера;
ограничивать доступ к административным endpoint’ам;
заранее учитывать, что операции с файлами завязаны на вольюмы и внутреннюю схему хранения.

Связанные статьи

Общее описание роли сервиса приведено в статье Что такое ZDS.

Параметры адресов, портов и служебных настроек см. в статье Конфигурация ZDS.

Смотрите также

Что такое ZDS

Конфигурация ZDS