svc-api: переход на Gateway (lk-api-gateway), User-Agent+Referer для DDoS-Guard, метод Виталия /instanceOperations/default/{id} с dataDescriptor, LEGACY-пометки везде

2026-07-16 13:48:34 +04:00
parent b9130fdd79
commit f5547c0465
87 changed files with 505 additions and 288 deletions
@@ -33,30 +33,84 @@

 ---

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

-Поскольку прямого эндпоинта со списком всех определений параметров нет, используется паттерн "Черновик операции".
+> **Это канонический метод получения ВСЕХ параметров, включая подполя map-fixed.**
+> Источник: Виталий Зайцев (DevOps Nubes), 15.07.2026.

-### Шаг А: Создание черновика
-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`: Подсказка по заполнению.
+**Шаг 1: найти svcId по имени сервиса**
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" $URL/services | jq '.results[] | select(.svc == "ApacheKafka") | .svcId'
+# → 116
+```
+
+**Шаг 2: найти svcOperationId нужной операции**
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" $URL/services/116 | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
+# → 148
+```
+
+**Шаг 3: получить параметры с подполями и допустимыми значениями**
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" $URL/instanceOperations/default/148 | jq '.svcOperation.cfsParams[]'
+```
+
+### Почему `/instanceOperations/default/{id}` а не `/serviceOperation/{id}`:
+
+| Данные | `/serviceOperation/{id}` | `/instanceOperations/default/{id}` |
+|--------|--------------------------|-------------------------------------|
+| ID, code, тип, isRequired | ✅ | ✅ |
+| `valueList` (допустимые значения) | ❌ | ✅ `['false','true']`, `['HOT','COLD']` |
+| `dataDescriptor` (подполя map-fixed) | ❌ | ✅ cpu, memory, replicas, disk... |
+| `isModifiable` | ❌ | ✅ на уровне подполей |
+| `regex`, `maxLength`, `minValue`... | ❌ | ✅ |
+| `isSensitive` | ❌ | ✅ |
+
+### Структура dataDescriptor (подполя map-fixed):
+
+```json
+{
+  "svcOperationCfsParamId": 788,
+  "svcOperationCfsParam": "clusterConfiguration",
+  "dataType": "map-fixed",
+  "dataDescriptor": {
+    "cpu": {
+      "svcOperationCfsSubparamId": 109,
+      "dataType": "integer > 0",
+      "isRequired": true,
+      "valueList": ""
+    },
+    "replicas": {
+      "svcOperationCfsSubparamId": 135,
+      "dataType": "integer > 0",
+      "isRequired": true,
+      "valueList": "1,3,5,7"
+    }
+  }
+}
+```
+
+### Формат valueList:
+
+- Для **верхнеуровневых** параметров: JSON-массив `["false", "true"]`
+- Для **подполей** dataDescriptor: comma-separated строка `"1,3,5,7"`
+- Для `boolean`: всегда `"false,true"` или `["false","true"]`
+
+### URL для разных стендов:
+
+| Стенд | Базовый URL |
+|-------|-------------|
+| test (новый Gateway) | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` |
+| test (старый proxy) | `https://deck-api-test.ngcloud.ru/api/v1/index.cfm?endpoint=` |
+| dev | `https://deck-api-dev.ngcloud.ru/api/v1/index.cfm?endpoint=` |
+| prod | `https://deck-api.ngcloud.ru/api/v1/index.cfm?endpoint=` |
+
+### Старый метод (через черновик) — НЕ ИСПОЛЬЗОВАТЬ:
+
+Ранее использовался паттерн "Черновик операции" (POST /instanceOperations → GET с ?fields=cfsParams).
+Он НЕ даёт dataDescriptor и valueList. Вместо него использовать `/instanceOperations/default/{id}`.

 ---

@@ -1,7 +1,7 @@
 # Taffy API Technical Manual for AI Agents

 ## 1. Authentication & Security
-**Base URL**: `https://deck-api.ngcloud.ru/api/v1/index.cfm`
+**Base URL**: `https://lk-api-gateway.ngcloud.ru/api/v1/svc`  <!-- ⛔ LEGACY: was deck-api.ngcloud.ru/api/v1/index.cfm -->

 All requests MUST include these headers (as indicated by CORS `access-control-allow-headers`):
 - `Authorization`: `Bearer <TOKEN>`