# Асинхронные операции

Некоторые операции MoreLogin принимают задание до того, как связанный браузер, облачный телефон, файл, приложение или выполнение RPA достигнет конечного состояния. Успешный ответ на отправку означает, что запрос принят, но не всегда означает, что запрошенное состояние уже достигнуто.

## Модель состояний на клиенте

| Состояние | Смысл | Действие клиента |
|  --- | --- | --- |
| Отправлено | API принял команду или создал задачу | Сохраните возвращённые ID и `requestId`; не отправляйте ту же запись сразу повторно |
| Ожидает или выполняется | Последующая операция всё ещё идёт | Опрашивайте задокументированный эндпоинт состояния/результата с растущими интервалами |
| Успешно | Целевой ресурс или задача достигла успешного конечного состояния | Прекратите опрос и продолжайте сценарий |
| Неудачно | Эндпоинт состояния/результата сообщает об ошибке или конечной бизнес-ошибке | Прекратите автоматические повторы; сохраните ID, детали ошибки и `requestId` |
| Результат неизвестен | Запись завершилась тайм-аутом или соединение закрылось без пригодного ответа | Прежде чем решать о повторе, запросите текущее состояние ресурса или задачи |


## Правила опроса

- Начинайте примерно с 1 секунды, затем увеличивайте интервал до 2, 4, 8 секунд с ограничением 15–30 секунд.
- Добавляйте дрожание, чтобы несколько клиентов не опрашивали в один момент.
- Останавливайтесь на задокументированном конечном состоянии; не опрашивайте бесконечно.
- Считайте `data: null` ожиданием только тогда, когда эндпоинт явно документирует такое поведение.
- Тайм-аут передачи при записи не является доказательством неудачи.


## Задокументированные сценарии

| Сценарий | Операция отправки | Операция наблюдения | Конечное состояние |
|  --- | --- | --- | --- |
| Запуск/остановка облачного браузера | `POST /cloudbrowser/start` или `/cloudbrowser/stop` | `POST /cloudbrowser/page` | Среда выполнения достигает нужного состояния или исчезает после остановки |
| Питание облачного телефона | `POST /cloudphone/powerOn` или `/cloudphone/powerOff` | `POST /cloudphone/page` | `envStatus=4` включён или `envStatus=2` выключен; `1` — ошибка создания |
| Загрузка файла на облачный телефон | Загрузите по подписанному URL, затем `POST /cloudphone/uploadFile` | `POST /cloudphone/uploadFileResult` | `status=1` успех или `status=2` неудача; `data: null` и `status=0` — ожидание |
| Скачивание с облачного телефона | `POST /cloudphone/download` | `POST /cloudphone/download/result` | `status=20` успех, `30` неудача или `40` отменено; `10` — выполняется |
| Установка приложения | `POST /cloudphone/app/install` | `POST /cloudphone/app/installedList` | Запрошенный пакет появляется в списке установленных приложений |
| Расписание/выполнение RPA | `POST /cloudphone/rpa/task/save` или `/onceTask/save` | `POST /cloudphone/rpa/task/page`, `/subTask/page` и `/subTask/detail/{id}` | `taskState=2` завершено или `3` отменено; проверьте `handleResult` (`0` неудача, `1` успех) |
| Прямые трансляции | `POST /cloudphone/live/start` или `/live/end` | `POST /cloudphone/live/status` | Статус подтверждает, что трансляция началась или остановлена |
| Загрузка в облачное хранилище | `POST /cloudstorage/upload/init`, затем `PUT` в объектное хранилище | `POST /cloudstorage/upload/complete` после успеха каждого необходимого PUT | Запрос завершения успешен; никогда не вызывайте complete до успешной загрузки объекта |


Аналоги в Local API используют префикс `/api` там, где это задокументировано. Рекомендации по каждой операции см. в [Матрице повторов и завершения операций](/ru/api-reference/getting-started/endpoint-behavior).

## Пример восстановления после тайм-аута

```python
try:
    submit_operation()
except TimeoutError:
    # The write may already have succeeded.
    current = query_current_state()
    if current.is_terminal_success:
        pass
    elif current.is_pending:
        poll_until_terminal()
    else:
        decide_whether_retry_is_safe(current)
```

Публичный API сейчас не определяет общий заголовок ключа идемпотентности. Поэтому ID ресурсов, ID задач, запросы состояния и `requestId` критичны для безопасного восстановления.