Алгоритмы обнаружения ресурсов и параметров API Deck

Этот документ описывает последовательность действий для получения полного списка ресурсов и их конфигурационных параметров через API Deck (https://deck-api.ngcloud.ru/api/v1).

1. Получение списка всех инстансов (Resources)

Для получения всех ресурсов, которыми владеет текущий пользователь:

Запрос: GET /v1/index.cfm/instances
Параметры: ?fields=instanceUid,displayName,serviceId,svc,state,explainedStatus
Алгоритм обработки:
- Итерировать по массиву results.
- Для каждого инстанса:
  - instanceUid: Уникальный ID (используется для импорта в TF).
  - svc: Человеческое название типа сервиса.
  - state.params: Текущие примененные параметры (Discovery).
  - state.out: Выходные данные от оркестратора (IP, имена сетей и т.д.).

2. Получение списка доступных типов сервисов (Service Inventory)

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

Запрос: GET /v1/index.cfm/services
Результат: Список объектов сервисов.
Ключевые поля:
- svcId: ID сервиса (нужен для создания операций).
- svc: Название (например, "Виртуальный датацентр").
- orchestratorName: Имя бэкенда.

3. Обнаружение схемы параметров для сервиса (Parameter Scheme Discovery)

Поскольку прямого эндпоинта со списком всех определений параметров нет, используется паттерн "Черновик операции".

Шаг А: Создание черновика

Запрос: POST /v1/index.cfm/instanceOperations

Тело:

{
  "operation": "create",
  "serviceId": <svcId_из_шага_2>,
  "instanceUid": null
}

Результат: Заголовок Location или тело ответа содержат instanceOperationUid (UUID).

Шаг Б: Получение метаданных параметров

Запрос: GET /v1/index.cfm/instanceOperations/{instanceOperationUid}?fields=cfsParams
Анализ cfsParams:
- svcOperationCfsParamId: Числовой ID параметра (например, 8). Критично для работы провайдера.
- label: Имя поля в UI (например, "UUID VDC").
- dataType: Тип (string, boolean, list, uuid).
- isRequired: Обязательность.
- descr: Подсказка по заполнению.

4. Маппинг параметров при импорте (Discovery Recipe)

При импорте существующего ресурса (Data Source в TF), необходимо сопоставить значения из instance.state.params с svcOperationCfsParamId.

Прямой связи по ключам нет, поэтому используется эвристика или ручной маппинг:

Смотрим instance.state.params -> находим ключ, например, vdcUid.
Смотрим cfsParams из Шага 3 -> находим параметр с label, похожим на "VDC UUID".
Используем его svcOperationCfsParamId для последующих операций modify.

Примеры фильтрации через `curl` и `jq`

Список всех Edge Gateway:

curl -s -H "Authorization: Bearer $TOKEN" \
"https://deck-api.ngcloud.ru/api/v1/index.cfm/instances?fields=instanceUid,displayName,serviceId,svc" | \
jq '.results[] | select(.serviceId == 22)'

Все параметры для создания VM (serviceId 28):

# 1. Создать черновик
OP_UID=$(curl -s -H "Authorization: Bearer $TOKEN" -X POST ... -d '{"operation":"create","serviceId":28,"instanceUid":null}' | jq -r .instanceOperationUid)

# 2. Прочитать схему
curl -s -H "Authorization: Bearer $TOKEN" \
"https://deck-api.ngcloud.ru/api/v1/index.cfm/instanceOperations/$OP_UID?fields=cfsParams" | jq .cfsParams

5. Эталонный snapshot реальных Output-полей

Сохранён baseline-снимок реальных output-полей по инстансам в статусах running/suspended:

Каталог: docs/70_api/output_inventory_snapshot_2026-03-02/
Основной файл для docs: running_suspended_output_fields_for_docs.json
Описание и сводка: README.md

Назначение:

использовать как шаблон при наполнении страниц Output params;
затем перепроверять актуальность на live API, так как состав полей в облаке может меняться.

5.4 KiB Raw Blame History Unescape Escape