---
slug: "yandex-cloud"
name: "Yandex Cloud API (IAM, Resource Manager, Compute Cloud)"
vendor: "Яндекс"
industry: "cloud"
docsUrl: "https://yandex.cloud/ru/docs/api-design-guide/"
version: 2
updatedAt: "2026-10-24"
---

# Yandex Cloud API (IAM, Resource Manager, Compute Cloud)

Отрасль: Облака и хостинг. Актуально на 2026-10-24.

REST API облачной платформы Yandex Cloud. В файл вошли базовые сервисы: получение IAM-токена, облака и каталоги (Resource Manager), виртуальные машины Compute Cloud (список, создание, запуск, остановка, перезапуск, удаление) и отслеживание асинхронных операций. У каждого сервиса свой хост на `api.cloud.yandex.net`; те же методы доступны через gRPC.

## Сценарии

### Получить IAM-токен для запросов к API

Первый шаг любой автоматизации Yandex Cloud: обменять ключ сервисного аккаунта или OAuth-токен на IAM-токен.

1. Для скриптов и серверов создай сервисный аккаунт с нужными ролями и авторизованный ключ к нему. Подпиши им JWT (алгоритм PS256, aud = https://iam.api.cloud.yandex.net/iam/v1/tokens).
2. Обменяй: POST /iam/v1/tokens на iam.api.cloud.yandex.net с полем jwt. Для своего аккаунта на Яндексе вместо jwt передай yandexPassportOauthToken — ровно одно из полей.
3. Передавай токен во всех запросах: Authorization: Bearer <IAM-токен>. Токен живёт ограниченное время — получай новый заранее, например раз в час.

```python
import time, jwt, requests  # pip install pyjwt cryptography requests

key = {"service_account_id": "<id сервисного аккаунта>", "id": "<id ключа>", "private_key": open("private.pem").read()}
now = int(time.time())
token = jwt.encode({"aud": "https://iam.api.cloud.yandex.net/iam/v1/tokens", "iss": key["service_account_id"],
                    "iat": now, "exp": now + 3600},
                   key["private_key"], algorithm="PS256", headers={"kid": key["id"]})
iam = requests.post("https://iam.api.cloud.yandex.net/iam/v1/tokens", json={"jwt": token}).json()["iamToken"]
```

### Найти каталог и посмотреть виртуальные машины

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

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
```

### Создать виртуальную машину и дождаться готовности

Поднять сервер из скрипта: для теста, CI или временной нагрузки.

1. Отправь запрос: POST /compute/v1/instances с folderId, zoneId (например, ru-central1-a), platformId, resourcesSpec (memory в байтах, cores, coreFraction), bootDiskSpec с образом и networkInterfaceSpecs с подсетью. Числа int64 передаются строками.
2. Ответ — объект Operation: создание идёт асинхронно. Сохрани его id.
3. Проверяй статус: GET /operations/{operationId} на operation.api.cloud.yandex.net. done = true — операция завершилась; если есть error — с ошибкой, иначе в response будет созданная ВМ.
4. Удалить машину — DELETE /compute/v1/instances/{instanceId}, тоже через операцию.

```bash
OP=$(curl -s -X POST https://compute.api.cloud.yandex.net/compute/v1/instances \
  -H "Authorization: Bearer $IAM_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "folderId": "<id каталога>",
        "name": "test-vm",
        "zoneId": "ru-central1-a",
        "platformId": "standard-v3",
        "resourcesSpec": {"memory": "2147483648", "cores": "2", "coreFraction": "20"},
        "bootDiskSpec": {"diskSpec": {"size": "21474836480", "imageId": "<id образа>"}},
        "networkInterfaceSpecs": [{"subnetId": "<id подсети>", "primaryV4AddressSpec": {"oneToOneNatSpec": {"ipVersion": "IPV4"}}}],
        "metadata": {"user-data": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAA..."}
      }' | jq -r .id)

curl https://operation.api.cloud.yandex.net/operations/$OP -H "Authorization: Bearer $IAM_TOKEN"
```

### Выключать машины на ночь и включать утром

Экономия на тестовых стендах: ВМ работают только в рабочее время.

1. По расписанию вечером вызывай POST /compute/v1/instances/{instanceId}:stop для каждой машины стенда, утром — POST /compute/v1/instances/{instanceId}:start.
2. Каждый вызов возвращает Operation — проверь итог через GET /operations/{operationId}.
3. Удобно помечать такие ВМ метками (labels, например env = test) и выбирать их фильтром в GET /compute/v1/instances.
4. Если сервис ответил 409 ABORTED (параллельная операция над той же машиной) или 503 — повтори через несколько секунд.

```bash
for ID in $(curl -s -G https://compute.api.cloud.yandex.net/compute/v1/instances -H "Authorization: Bearer $IAM_TOKEN" \
              -d folderId=<id каталога> | jq -r '.instances[] | select(.labels.env == "test") | .id'); do
  curl -s -X POST "https://compute.api.cloud.yandex.net/compute/v1/instances/$ID:stop" -H "Authorization: Bearer $IAM_TOKEN"
done
```

## Базовые 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-токен>
```

## Методы

### POST /iam/v1/tokens — Получение IAM-токена

Хост `iam.api.cloud.yandex.net`. Передаётся ровно одно из полей.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `yandexPassportOauthToken` | body | string | нет | OAuth-токен аккаунта на Яндексе, до 4000 символов |
| `jwt` | body | string | нет | JWT сервисного аккаунта, до 8000 символов |

### 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 — без метаданных, или полный вид |

### POST /compute/v1/instances — Создание виртуальной машины

Асинхронная операция; её можно отменить, пока она выполняется.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `folderId` | body | string | да | ID каталога |
| `zoneId` | body | string | да | Зона доступности |
| `platformId` | body | string | да | Аппаратная платформа |
| `resourcesSpec.memory` | body | string | да | Объём памяти в байтах |
| `resourcesSpec.cores` | body | string | да | Число ядер |
| `resourcesSpec.coreFraction` | body | string | нет | Гарантированная доля vCPU: 0, 5, 20, 50, 100 |
| `resourcesSpec.gpus` | body | string | нет | Число GPU: 0, 1, 2, 4 |
| `bootDiskSpec` | body | object | да | Загрузочный диск: diskSpec (size, imageId, typeId) или diskId |
| `networkInterfaceSpecs` | body | array | да | Сетевые интерфейсы |
| `name` | body | string | нет | Имя ВМ |
| `description` | body | string | нет | Описание, до 256 символов |
| `labels` | body | object | нет | Метки ключ:значение |
| `metadata` | body | object | нет | Метаданные (в том числе пользовательские ключи) |
| `secondaryDiskSpecs` | body | array | нет | Дополнительные диски, до 3 |
| `hostname` | body | string | нет | Имя хоста |
| `schedulingPolicy` | body | object | нет | Политика планирования |
| `serviceAccountId` | body | string | нет | Сервисный аккаунт для аутентификации изнутри ВМ |

### POST /compute/v1/instances/{instanceId}:start — Запуск виртуальной машины

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

### POST /compute/v1/instances/{instanceId}:stop — Остановка виртуальной машины

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

### POST /compute/v1/instances/{instanceId}:restart — Перезапуск виртуальной машины

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

### DELETE /compute/v1/instances/{instanceId} — Удаление виртуальной машины

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

### GET /operations/{operationId} — Статус операции

Хост `operation.api.cloud.yandex.net`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `operationId` | path | string | да | ID операции |

Пример запроса:

```
GET https://operation.api.cloud.yandex.net/operations/fcmq0j5033e516c56ctq
```

## Нюансы

- Каждая операция, изменяющая ресурс, возвращает объект 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` из ответа.

## Ошибки

| Код | Описание |
|---|---|
| `400` | INVALID_ARGUMENT, FAILED_PRECONDITION или OUT_OF_RANGE — некорректные параметры или не выполнены условия операции |
| `401` | UNAUTHENTICATED — нужна аутентификация |
| `403` | PERMISSION_DENIED — недостаточно полномочий |
| `404` | NOT_FOUND — ресурс не найден |
| `409` | ALREADY_EXISTS или ABORTED — ресурс уже существует или конфликт параллельных операций |
| `429` | RESOURCE_EXHAUSTED — превышен лимит запросов |
| `499` | CANCELLED — операция прервана клиентом |
| `500` | UNKNOWN, INTERNAL или DATA_LOSS — ошибка сервера |
| `501` | NOT_IMPLEMENTED — операция не поддерживается |
| `503` | UNAVAILABLE — сервис недоступен, повторите через несколько секунд |
| `504` | DEADLINE_EXCEEDED — превышено время ожидания |

## Источники

- [Принципы API Yandex Cloud](https://yandex.cloud/ru/docs/api-design-guide/)
- [Обработка ошибок](https://yandex.cloud/ru/docs/api-design-guide/concepts/errors)
- [Объект Operation](https://yandex.cloud/ru/docs/api-design-guide/concepts/operation)
- [IamToken.Create](https://yandex.cloud/ru/docs/iam/api-ref/IamToken/create)
- [Cloud.List](https://yandex.cloud/ru/docs/resource-manager/api-ref/Cloud/list)
- [Folder.List](https://yandex.cloud/ru/docs/resource-manager/api-ref/Folder/list)
- [Compute Instance API](https://yandex.cloud/ru/docs/compute/api-ref/Instance/)
- [Документация Yandex Cloud на GitHub](https://github.com/yandex-cloud/docs)

---

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