add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Алгоритмы обнаружения ресурсов и параметров API Deck
+
+Этот документ описывает последовательность действий для получения полного списка ресурсов и их конфигурационных параметров через API Deck (`https://deck-api.ngcloud.ru/api/v1`).
+
+---
+
+## 1. Получение списка всех инстансов (Resources)
+
+Для получения всех ресурсов, которыми владеет текущий пользователь:
+
+1. **Запрос:** `GET /v1/index.cfm/instances`
+2. **Параметры:** `?fields=instanceUid,displayName,serviceId,svc,state,explainedStatus`
+3. **Алгоритм обработки:**
+    - Итерировать по массиву `results`.
+    - Для каждого инстанса:
+        - `instanceUid`: Уникальный ID (используется для импорта в TF).
+        - `svc`: Человеческое название типа сервиса.
+        - `state.params`: Текущие примененные параметры (Discovery).
+        - `state.out`: Выходные данные от оркестратора (IP, имена сетей и т.д.).
+
+---
+
+## 2. Получение списка доступных типов сервисов (Service Inventory)
+
+Для понимания того, какие сервисы в принципе можно создать:
+
+1. **Запрос:** `GET /v1/index.cfm/services`
+2. **Результат:** Список объектов сервисов.
+3. **Ключевые поля:**
+    - `svcId`: ID сервиса (нужен для создания операций).
+    - `svc`: Название (например, "Виртуальный датацентр").
+    - `orchestratorName`: Имя бэкенда.
+
+---
+
+## 3. Обнаружение схемы параметров для сервиса (Parameter Scheme Discovery)
+
+Поскольку прямого эндпоинта со списком всех определений параметров нет, используется паттерн "Черновик операции".
+
+### Шаг А: Создание черновика
+1. **Запрос:** `POST /v1/index.cfm/instanceOperations`
+2. **Тело:** 
+   ```json
+   {
+     "operation": "create",
+     "serviceId": <svcId_из_шага_2>,
+     "instanceUid": null
+   }
+   ```
+3. **Результат:** Заголовок `Location` или тело ответа содержат `instanceOperationUid` (UUID).
+
+### Шаг Б: Получение метаданных параметров
+1. **Запрос:** `GET /v1/index.cfm/instanceOperations/{instanceOperationUid}?fields=cfsParams`
+2. **Анализ `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`.
+
+**Прямой связи по ключам нет**, поэтому используется эвристика или ручной маппинг:
+1. Смотрим `instance.state.params` -> находим ключ, например, `vdcUid`.
+2. Смотрим `cfsParams` из Шага 3 -> находим параметр с `label`, похожим на "VDC UUID".
+3. Используем его `svcOperationCfsParamId` для последующих операций `modify`.
+
+---
+
+## Примеры фильтрации через `curl` и `jq`
+
+**Список всех Edge Gateway:**
+```bash
+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):**
+```bash
+# 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, так как состав полей в облаке может меняться.