109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
# Обращение к API облака
|
||
|
||
## Базовые URL
|
||
|
||
| Стенд | URL |
|
||
|-------|-----|
|
||
| dev | `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc` |
|
||
| test | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` |
|
||
| prod | `https://lk-api-gateway.ngcloud.ru/api/v1/svc` |
|
||
|
||
## Аутентификация
|
||
|
||
Bearer-токен в заголовке: `Authorization: Bearer <TOKEN>`
|
||
|
||
Токены лежат в `secrets/`:
|
||
- `secrets/dev.token`
|
||
- `secrets/test.token`
|
||
- `secrets/prod.token`
|
||
|
||
## ⚠️ ОБЯЗАТЕЛЬНО: User-Agent
|
||
|
||
**Без `User-Agent: Mozilla/5.0` вернёт Forbidden!** DDoS-Guard блокирует curl по умолчанию.
|
||
|
||
## Примеры curl
|
||
|
||
```bash
|
||
URL="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"
|
||
TOKEN=$(tr -d '\n' < secrets/dev.token)
|
||
UA="Mozilla/5.0"
|
||
|
||
# Список сервисов
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services | jq '.results[] | {svcId, svc}'
|
||
|
||
# Детали сервиса (все операции)
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services/90 | jq '.svc.operations[] | {svcOperationId, operation}'
|
||
|
||
# Полные параметры операции (valueList, dataDescriptor, isModifiable)
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/instanceOperations/default/19 | jq '.svcOperation.cfsParams[]'
|
||
```
|
||
|
||
## Получение параметров сервиса (как в YAML-генераторе)
|
||
|
||
3 шага:
|
||
|
||
```bash
|
||
URL="https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc"
|
||
TOKEN=$(tr -d '\n' < secrets/dev.token)
|
||
UA="Mozilla/5.0"
|
||
|
||
# Шаг 1: найти svcId по имени
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services | jq '.results[] | select(.svc == "PostgreSQL") | .svcId'
|
||
|
||
# Шаг 2: найти svcOperationId для операции "create"
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/services/90 | jq '.svc.operations[] | select(.operation == "create") | .svcOperationId'
|
||
|
||
# Шаг 3: получить параметры (с valueList, dataDescriptor)
|
||
curl -s --max-time 10 -H "Authorization: Bearer $TOKEN" -H "User-Agent: $UA" $URL/instanceOperations/default/19 | jq '.svcOperation.cfsParams[]'
|
||
```
|
||
|
||
## Ключевые эндпоинты
|
||
|
||
| Метод | Путь | Назначение |
|
||
|-------|------|------------|
|
||
| GET | `/services` | Список сервисов |
|
||
| GET | `/services/{svcId}` | Детали + операции |
|
||
| GET | `/instances` | Инстансы пользователя |
|
||
| GET | `/instanceOperations/default/{svcOperationId}` | **Полные параметры** (valueList, dataDescriptor, isModifiable) |
|
||
## Эндпоинты (полный список)
|
||
|
||
| Метод | Путь | Назначение |
|
||
|-------|------|------------|
|
||
| GET | `/services` | Список сервисов |
|
||
| GET | `/services/{svcId}` | Детали + операции |
|
||
| GET | `/instances?pageSize=200&page=N` | Инстансы (пагинация!) |
|
||
| GET | `/instanceOperations/default/{svcOperationId}` | **Полные параметры** (valueList, dataDescriptor, isModifiable) |
|
||
| POST | `/instances` | Создать инстанс → Location: instanceUid |
|
||
| POST | `/instanceOperations` | Создать операцию → Location: opUid |
|
||
| POST | `/instanceOperationCfsParams` | Задать параметр операции |
|
||
| POST | `/instanceOperations/{opUid}/run` | **Запустить операцию** (обязательно!) |
|
||
|
||
## Поток CREATE
|
||
|
||
См. подробный документ: [`api-create-flow.md`](api-create-flow.md)
|
||
|
||
```
|
||
1. GET /services/{svcId} → svcOperationId для "create"
|
||
2. GET /instanceOperations/default/{svcOpId} → параметры
|
||
3. POST /instances → instanceUid (из Location)
|
||
4. POST /instanceOperations → opUid (из Location)
|
||
5. POST /instanceOperationCfsParams (×N) → задать параметры
|
||
6. POST /instanceOperations/{opUid}/run → ЗАПУСК
|
||
7. GET /instances?pageSize=200 (поллинг) → ждать running
|
||
```
|
||
|
||
## ⚠️ Важно
|
||
|
||
- `/instanceOperations/default/{id}` даёт **полные** параметры (valueList, dataDescriptor, isModifiable)
|
||
- `/serviceOperation/{id}` даёт **базовые** параметры (без valueList и dataDescriptor) — НЕ использовать
|
||
- Все параметры `--max-time 10` обязательны — чтобы не висло
|
||
- Токен **без** переносов строк: `tr -d '\n'`
|
||
- **UUID в Location — uppercase** (не lowercase как в БД)
|
||
- **displayName должен быть уникальным** — добавлять timestamp
|
||
- **`/run` обязателен!** Без него операция не стартует (auto-start только в UI)
|
||
- **Array параметры — JSON-строка:** `"[\"test\"]"`, не голый массив
|
||
- **Все paramValue — строки:** даже числа и булевы
|
||
- **Пустое тело = `{}`:** никогда не слать `null` (DDoS-Guard режет)
|
||
- **Пагинация:** инстансов может быть >200, проверять page=1, page=2...
|
||
- **DDoS-Guard:** с локальной машины может не работать, curl через ВМ 213 (`ssh naeel@5.172.178.213`)
|