# Yandex Cloud API (IAM, Resource Manager, Compute Cloud): Найти каталог и посмотреть виртуальные машины

Сценарий из mcp-everything. Актуально на 2026-10-24.

Инвентаризация: какие ВМ есть в облаке, в каком они состоянии.

1. Получи облака: GET /resource-manager/v1/clouds на resource-manager.api.cloud.yandex.net.
2. Получи каталоги облака: GET /resource-manager/v1/folders с cloudId.
3. Получи ВМ каталога: GET /compute/v1/instances с folderId на compute.api.cloud.yandex.net. Листай страницы через pageSize и pageToken = nextPageToken из ответа.
4. Подробности по одной машине — GET /compute/v1/instances/{instanceId}; status показывает RUNNING, STOPPED и т. д.

```bash
H="Authorization: Bearer $IAM_TOKEN"
curl -G https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders -H "$H" -d cloudId=<id облака>
curl -G https://compute.api.cloud.yandex.net/compute/v1/instances -H "$H" -d folderId=<id каталога> -d pageSize=100
```

## Базовые URL

- IAM: `https://iam.api.cloud.yandex.net`
- Resource Manager: `https://resource-manager.api.cloud.yandex.net`
- Compute Cloud: `https://compute.api.cloud.yandex.net`
- Операции: `https://operation.api.cloud.yandex.net`

## Авторизация

Тип: Bearer-токен

Все запросы, кроме получения токена, передают IAM-токен в заголовке:

IAM-токен получают методом `POST /iam/v1/tokens` в обмен на OAuth-токен аккаунта на Яндексе или JWT сервисного аккаунта.

```
Authorization: Bearer <IAM-токен>
```

## Методы сценария

### GET /resource-manager/v1/clouds — Список облаков

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `pageSize` | query | string | нет | Размер страницы; при большем числе результатов возвращается nextPageToken |
| `pageToken` | query | string | нет | Токен следующей страницы |
| `filter` | query | string | нет | Фильтр по полю |
| `organizationId` | query | string | нет | ID организации |

### GET /resource-manager/v1/folders — Список каталогов в облаке

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `cloudId` | query | string | да | ID облака |
| `pageSize` | query | string | нет | Размер страницы |
| `pageToken` | query | string | нет | Токен следующей страницы |
| `filter` | query | string | нет | Фильтр по полю |

### GET /compute/v1/instances — Список виртуальных машин

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `folderId` | query | string | да | ID каталога |
| `pageSize` | query | string | нет | Размер страницы |
| `pageToken` | query | string | нет | Токен следующей страницы |
| `filter` | query | string | нет | Фильтр: условия, объединённые AND |
| `orderBy` | query | string | нет | Сортировка, например createdAt desc; по умолчанию id asc |

### GET /compute/v1/instances/{instanceId} — Информация о виртуальной машине

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `instanceId` | path | string | да | ID виртуальной машины |
| `view` | query | string | нет | BASIC — без метаданных, или полный вид |

## Нюансы

- Каждая операция, изменяющая ресурс, возвращает объект Operation: `id`, `created_at`, `created_by`, `modified_at`, `done`, `metadata` и одно из полей `response`/`error`. Отслеживайте статус по `id`.
- `done: true` означает завершение операции, в том числе с ошибкой. Поле `error` может появиться раньше — пока сервис откатывает изменения.
- Для `Create`/`Update` поле `response` содержит созданный или изменённый ресурс.
- Числа int64 (`pageSize`, `memory`, `cores`) передаются строками.
- Пагинация: `pageSize` и `pageToken`, следующая страница — по `nextPageToken` из ответа.

## Другие сценарии

- [Получить IAM-токен для запросов к API](https://mcp-everything.ru/integrations/yandex-cloud/scenarios/poluchit-iam-token-dlya-zaprosov-k-api.md)
- [Создать виртуальную машину и дождаться готовности](https://mcp-everything.ru/integrations/yandex-cloud/scenarios/sozdat-virtualnuyu-mashinu-i-dozhdatsya.md)
- [Выключать машины на ночь и включать утром](https://mcp-everything.ru/integrations/yandex-cloud/scenarios/vyklyuchat-mashiny-na-noch-i-vklyuchat.md)

---

Если этого недостаточно — официальная документация: https://yandex.cloud/ru/docs/api-design-guide/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/yandex-cloud.md