7.3 Асинхронное использование API

Возможно как синхронное, так и асинхронное использование API endpoint. При синхронном использовании результат запроса возвращается по факту выполнения, однако иногда это может быть неприемлемо для длительных задач.

Для асинхронного выполнения (task) необходимо использовать URI /.api/V4/.async/.req/. Результат выполнения можно проверить отдельным методом task().

В качестве идентификатора task используется JSON RPC id оригинального запроса. Метод task() может аналогично использоваться для запросов, отправленных синхронно, но завершившихся таймаутом.

Если исходный запрос еще не был обработан, то поле result->data->replied будет содержать 0/false, а поле result->data->response будет иметь значение null.

Пример: запрос vm-list с RPC id==dd408526-563a-11ea-9bec-920e9c0cd5ca был выполнен асинхронно. Позже его результат был запрошен с помощью метода task().

Асинхронный запрос:

{
    "jsonrpc":  "2.0",
    "method":   "vm-list",
    "id":       "dd408526-563a-11ea-9bec-920e9c0cd5ca"
}

Ответ на асинхронный запрос:

{
    "id":       "dd408526-563a-11ea-9bec-920e9c0cd5ca",
    "jsonrpc":  "2.0",
    "result": {
        "code": 999,
        "data": "request queued"
    }
}

Запрос task:

{
    "jsonrpc":  "2.0",
    "method":   "task",
    "id":       "803d1f16-b823-11e9-a040-52ed8478de0e",
    "params": {
        "id":   "dd408526-563a-11ea-9bec-920e9c0cd5ca"
    }
}

Ответ task:

{
   "id":    "803d1f16-b823-11e9-a040-52ed8478de0e",
   "jsonrpc":   "2.0",
   "result": {
      "code":   1,
      "data": {
         "method":  "vm-list",
         "replied": 1,
         "reply_time":  1562568328,
         "request": {
            "id":   "dd408526-563a-11ea-9bec-920e9c0cd5ca",
            "jsonrpc":  "2.0",
            "method":   "vm-list"
         },
         "response": {
            "id":   "dd408526-563a-11ea-9bec-920e9c0cd5ca",
            "jsonrpc":  "2.0",
            "result": {
               "code":  1,
               "data": [
                  {
                     "os_profile":  6,
                     "os_type":     1,
                     "vdc_id":      2,
                     "vm_id":       "41",
                     "vm_name":     "FreeBSD vxlan test net30 #1",
                     "vm_status":   1
                  },
                  {
                     "os_profile":  6,
                     "os_type":     1,
                     "vdc_id":      2,
                     "vm_id":       "42",
                     "vm_name":     "FreeBSD vxlan test net30 #2",
                     "vm_status":   1
                  },
                  {
                     "os_profile":  4,
                     "os_type":     6,
                     "vdc_id":      2,
                     "vm_id":       "71",
                     "vm_name":     "CentOS7 io PerfTest #30",
                     "vm_status":   3
                  },
                  {
                     "os_profile":  4,
                     "os_type":     6,
                     "vdc_id":      2,
                     "vm_id":       "72",
                     "vm_name":     "CentOS7 io PerfTest #31",
                     "vm_status":   3
                  },
                  {
                     "os_profile":  4,
                     "os_type":     6,
                     "vdc_id":      2,
                     "vm_id":       "73",
                     "vm_name":     "CentOS7 io PerfTest #32",
                     "vm_status":   3
                  },
                  {
                     "os_profile":  4,
                     "os_type":     6,
                     "vdc_id":      2,
                     "vm_id":       "74",
                     "vm_name":     "CentOS7 io PerfTest #33",
                     "vm_status":   3
                  },
                  {
                     "os_profile":  4,
                     "os_type":     6,
                     "vdc_id":      2,
                     "vm_id":       "76",
                     "vm_name":     "CentOS7 io PerfTest #35",
                     "vm_status":   3
                  }
               ]
            }
         },
         "sync_req":    0,
         "ts":      1562568328
      }
   }
}