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 | Получение списка вольюмов | Внешний клиент или управляющий сервис |
Основные параметры:
volume- имя вольюма;storageClass- класс хранения вольюма.
Для операции листинга дополнительно могут использоваться:
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/set_external_offsets | Замена внешних offset | Администратор или служба сопровождения |
POST | /admin/background_scan | Принудительный запуск фонового сканирования | Администратор или служба сопровождения |
GET | /admin/extended_status | Получение расширенного статуса узла | Администратор, мониторинг или служба сопровождения |
Что важно учитывать при использовании API
При работе с API ZDS рекомендуется соблюдать следующие правила:
- не смешивать внешние и внутренние endpoint’ы в интеграционных сценариях;
- использовать внутренние методы только в рамках самого кластера;
- ограничивать доступ к административным endpoint’ам;
- заранее учитывать, что операции с файлами завязаны на вольюмы и внутреннюю схему хранения.
Связанные статьи
Общее описание роли сервиса приведено в статье Что такое ZDS.
Параметры адресов, портов и служебных настроек см. в статье Конфигурация ZDS.