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

Отрасль: Облака и хостинг. Актуально на 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-токен>. Токен живёт ограниченное время — получай новый заранее, например раз в час.

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 и т. д.

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}, тоже через операцию.

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 — повтори через несколько секунд.

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
• Обработка ошибок
• Объект Operation
• IamToken.Create
• Cloud.List
• Folder.List
• Compute Instance API
• Документация Yandex Cloud на GitHub

---

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