Статусы и жизненный цикл

Большинство изменений в ZennoHosting выполняется асинхронно. Успешный ответ на запись означает только то, что сервер принял работу, — машина, сеть, резервная копия или правило проброса портов дойдут до нужного состояния позже. Читать это состояние следует по одному полю: status.

Одно поле для состояния

У виртуальных машин, сетей и публичных IP-адресов есть поле status с пятью возможными значениями. Это и есть то, что стоит показывать в интерфейсе и на что стоит опираться в автоматизации.

creating — ресурс создаётся и ещё не готов к работе.
active — ресурс существует и находится в обычном, готовом к работе состоянии.
updating — к ресурсу применяется изменение: запуск, остановка, перезагрузка, изменение конфигурации или пересборка.
deleting — ресурс удаляется.
failed — ресурс попал в состояние, из которого не может выйти сам, и требует вмешательства команды провайдера.

active не означает «всё прошло успешно»

Значение active возвращается и после неудачной операции, если сбой был обработан штатно. Запуск, остановка, перезагрузка или изменение конфигурации, которые можно просто повторить, оставляют машину в состоянии active; неудавшееся удаление, обработанное штатно, тоже оставляет ресурс целым и активным. Поэтому по полю status нельзя судить об исходе конкретной операции — для этого есть сама операция. Значение failed означает другое: ресурс сломан и сам не восстановится.

Два вопроса — два источника

Разделяйте вопрос «в каком состоянии ресурс» и вопрос «чем закончилась моя операция». Первый отвечает status ресурса, второй — запись операции.

status ресурса — что показывать пользователю и когда можно переходить к следующему действию.
status операции — исход: Queued, InProgress, Compensation, Succeeded или Failed.
failureCode операции — причина, по которой она завершилась неудачей: insufficientCapacity, timeout или internal.
bootStatus машины — включено питание или нет: Running либо Stopped. Поле не устарело и остаётся нужным, когда важно именно питание, а не жизненный цикл.

1
Отправьте изменяющий запрос
Создание, обновление, восстановление, подключение к сети и правила проброса портов выполняются асинхронно, а не мгновенным переходом состояния.
2
Сохраните идентификаторы из ответа
Сохраните commandId и идентификаторы ресурсов, которые уже были известны из контекста запроса. У части эндпоинтов commandId — внутренний идентификатор, и запросить его нельзя; у остальных это настоящий идентификатор операции для опроса. Что именно вернул конкретный эндпоинт, написано в его описании в справочнике.
3
Опрашивайте ресурс, а не ответ на запись
Читайте машину, сеть, резервную копию или публичный адрес через соответствующий эндпоинт и смотрите на status. Фоновая задача сверки обновляет состояние примерно раз в 10 секунд, поэтому небольшая задержка — норма, а не признак сбоя.
4
Если нужна причина неудачи — читайте операцию
Запросите операции проекта и найдите свою по идентификатору. Поле failureCode отвечает на вопрос «почему», а currentState — необязательная диагностическая метка текущего шага; её набор значений не стабилен, полагаться на неё в коде нельзя.

Где это особенно важно

Создание машины, запуск, остановка и перезагрузка.
Создание приватной сети, подключение и отключение машин.
Создание резервной копии и восстановление из неё.
Создание, обновление и удаление правил проброса портов.

Пока идёт операция, ресурс заблокирован: параллельные изменения того же ресурса завершаются с 409 Conflict, пока текущая операция не закончится.

Устаревшие поля

В ответах остаются поля предыдущего поколения. Они сохранены только для обратной совместимости — в новом коде используйте замену.

operation и operationStatus у ресурса — низкоуровневая пара, из которой status и выводится. Вместо них читайте status.
lastError у операции больше не возвращается: причину неудачи даёт failureCode.
vmCount у проекта помечен устаревшим — используйте resourceCounts.vms.

Практическое правило

Стройте автоматизацию вокруг наблюдаемого состояния ресурса, а не вокруг ответа на запись. Ответ с кодом 202 говорит, что работа началась. Поле status говорит, где ресурс находится сейчас. Запись операции говорит, чем закончилась конкретная попытка.