Работа с API

Общая информация

API URL

Для доступа к API используйте URL вида https://domain.com/service/api_version/function/.

domain.com — публичный IP-адрес или домен сервера с VMmanager

service — внутренний сервис для обработки запроса:

auth — сервис авторизации;
ip — IPmanager 6 — сервис для работы с IP-адресами, пулами и сетями;
ldap — LDAP service — сервис синхронизации с каталогом LDAP;
vm — VMmanager API — основной сервис платформы

api_version — текущая версия API:

ip, vm — v3;
auth, ldap — v4

function — функция для выполнения в VMmanager

Методы HTTP-запросов

VMmanager поддерживает методы GET, POST и DELETE.

Параметры POST-запроса

Чтобы передать параметры для POST-запроса, укажите их в теле запроса в формате JSON.

Формат ответа

Ответ на API-запросы приходит в виде JSON-объектов, например:

Сообщение об ошибке в JSON

{
  "error":
  {
    "code": <внутренний код ошибки, int>,
    "msg": <сообщение об ошибке, string>,
    "value": <дополнительная информация, object>
  }
}

CODE

Права доступа

Некоторые функции недоступны для внешних API-запросов. Запрос к таким функциям завершится с ошибкой 3001 Unauthorized:

Сообщение об ошибке

{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}

CODE

Как обрабатывать код 503

Если VMmanager длительное время неактивен, то он может быть приостановлен. В этом случае API-запросы завершаются с кодом 503. Повторяйте запросы, пока в ответ не будет получен другой код:

Пример реализации на Python 3

def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
                break
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)

CODE

Фильтры в запросах

VMmanager поддерживает два вида GET-запросов:

информация об определённом элементе по его ID — в ответ будет получена информация только об указанном элементе. В ответе нет информации о связанных сущностях таких как IP-адрес, кластер или диск ВМ. Например:
Получить информацию о ВМ по ID
```
domain.com/vm/v3/host/host_id
```
CODE
полный список элементов определённого вида — в ответ будет получен полный список всех элементов указанного типа. Также в ответе есть информация о всех связанных сущностях. Например:
Получить информацию о всех ВМ
```
domain.com/vm/v3/host/
```
CODE

Рекомендуем запрашивать полный список элементов и применять к нему фильтры. Это позволит получать информацию о всех связанных сущностях.

Формат фильтров

Доступные фильтры:

WHERE — аналогичен выражению WHERE в SQL. Поддерживает обработку логических операторов AND, OR, NOT. Параметры сравнения:
- EQ — равно;
- NE — не равно;
- GT — больше;
- GE — больше или равно;
- LT — меньше;
- LE — меньше или равно;
- CP — поиск значений по указанной маске. Аналогичен оператору LIKE в SQL;
ORDERBY — сортировка по указанному параметру. Если не указана, то применяется сортировка по возрастанию ID. Возможный порядок:
- ASC — по возрастанию;
- DESC — по убыванию;
LIMIT — вывод указанного диапазона отфильтрованных элементов. В качестве значений укажите два числа через запятую. Нумерация начинается с 0.

Правила оформления фильтра

перед первым фильтром ставьте символ ?;
чтобы указать значения и параметры фильтра, используйте символ =;
помещайте текстовые значения в одинарные кавычки. Для числовых значений использование кавычек опционально;
параметры, значения и логические операторы фильтра разделяйте пробелом или символом %20. В параметре curl используйте для разделения символ +;
условия фильтра WHERE можно поместить в скобки;
чтобы объединить условия, используйте логические операторы AND, OR и NOT;
объединяйте несколько фильтров символом &;
при использовании оператора CP добавьте символ процента (%25) в начало и конец маски.
Пример запроса
```
where=(id%20CP%20'%25some_text%25')
```
CODE

Примеры запросов с фильтрами

Получить кластер с ID 1

GET https://domain.com/vm/v3/cluster?where=(id+EQ+1)

DIFF

Получить задачу по ID в consul и имени

GET https://domain.com/vm/v3/task?where=(consul_id+EQ+'1341774670')+AND+(name+EQ+'host_create')

DIFF

Получить список из 50 ВМ с убывающей сортировкой по имени

GET https://domain.com/vm/v3/host?orderby=cluster.name+desc&limit=0,50

DIFF

Способы авторизации

Авторизация обязательна для выполнения API-запросов в VMmanager.

Авторизация по токену

Чтобы получить токен авторизации, отправьте POST-запрос на URL вида https://domain.com/auth/v4/public/token.
Тело запроса в JSON
```
{
  "email": your_email,
  "password": your_password
}
```
CODE
Обработайте ответ формата JSON:
Ответ при успешной авторизации
```
{
  "id": int,
  "token": string
}
```
CODE
Ответ при ошибке авторизации
```
{
  "error": {
    "code": 22013,
    "msg": "Invalid password"
  }
}
```
CODE
Используйте значение token в заголовке HTTP-запроса. Например:
Использование в curl
```
curl -X POST 'https://domain.com/vm/v3/host/' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'
```
CODE

Если в течение 60 минут токен авторизации не использовался, он будет удалён. Чтобы получить токен с нужным временем жизни, отправьте POST-запрос на URL вида https://domain.com/auth/v4/token:

Тело запроса в JSON

{
"expires_at": <time>,
"description": <comment>
}

CODE

<time> — срок действия токена в формате YYYY-MM-DD HH:MM:SS

<comment> — произвольный комментарий

Ответ будет содержать новый токен с заданным сроком действия.

Использование в curl

curl -X POST 'https://domain.com/auth/v4/token' -d '{"expires_at": "2030-01-31 00:00:00", "description": "Token for integration"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

CODE

Изменение времени жизни токена и сессии

По умолчанию время жизни токена — 60 минут. Чтобы изменить этот параметр, отправьте POST-запрос на URL вида https://domain.com/auth/v4/setting/token_ttl:

Тело запроса в JSON

{
"value": "<time>"
}

CODE

<time> — время жизни токена (сессии) в минутах

Использование в curl

curl -X POST 'https://domain.com/auth/v4/setting/token_ttl' -d '{"value": "999"}' -H 'x-xsrf-token: 4-e9726dd9-61d9-2940-add3-914851d2cb8a'

CODE

Вы также можете изменить время жизни сессии через интерфейс. Подробнее см. Время жизни сессии.

Сквозная авторизация по ключу

VMmanager поддерживает сквозную авторизацию пользователя с использованием логина и пароля администратора. Например, её можно использовать для авторизованного перехода из биллинговой системы в VMmanager или предоставления временного доступа пользователя к платформе. Время действия такого ключа — один час.

Отправьте POST-запрос на URL вида https://domain.com/auth/v4/public/token.
Тело запроса в JSON
```
{
  "email": "admin@example.com",
  "password": "secret"
}
```
CODE
admin@example.com — email администратора платформы
secret — пароль администратора платформы
Использование в curl
```
curl -X POST 'https://domain.com/api/auth/v4/public/token' -d '{"email": "admin@example.com", "password": "secret"}'
```
CODE
Обработайте ответ. Он может содержать сообщение об ошибке, либо JSON вида:
Ответ в JSON
```
{
  "confirmed":true,
  "expires_at": null,
  "id":"24",
  "token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"
}
```
CODE
id — идентификатор токена
token — значение токена
Отправьте POST-запрос для создания ключа:
Создать ключ для авторизации
```
curl -X POST 'https://domain.com/api/auth/v4/user/client@example.com/key'  -H 'x-xsrf-token: 24-cee181d2-ccaa-4b64-a229-234aa7a25db6' -H 'isp-box-instance: true'  -d '{}'
```
CODE
client@example.com — email учётной записи, для которой формируется ключ. Вы можете использовать id учётной записи вместо email
В ответ будет получен JSON-объект вида:
Ответ в JSON
```
{
  "id":"4",
  "key":"4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"
}
```
CODE
id — идентификатор ключа
key — значение ключа

Обратите внимание!

По этому ключу вы можете предоставить пользователю временный доступ к платформе. Для авторизации пользователю нужно открыть ссылку вида https://domain.com/auth/key/<key>
domain.com — доменное имя или IP-адрес сервера с VMmanager
<key> — ключ доступа
Чтобы получить значение токена по временному ключу, отправьте POST-запрос:
Получить значение токена по ключу
```
curl -k -X POST 'https://domain.com/api/auth/v4/public/key' -H "isp-box-instance: true" -d '{"key": "4-74e7c0e9-a5ff-4f52-a2ac-ed03c6ed1e21"}'
```
CODE
В ответ будет получен JSON-объект вида:
Ответ в JSON
```
{
  "confirmed":true,
  "expires_at": null,
  "id":"123",
  "token":"1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f"
}
```
CODE
id — идентификатор токена
token — значение токена
Используйте значение токена в заголовке HTTP-запроса, например:
Использование в curl
```
curl -X GET 'https://domain.com/vm/v3/host' -H 'x-xsrf-token: 1996-0082f9c6-0b07-43ca-b4e7-449c6b0df71f' -H 'isp-box-instance: true'
```
CODE
В случае ошибки будет получено сообщение вида:
Ошибка при авторизации
```
{
  "error":
  {
    "code": 3001,
    "msg":"Unauthorized"
  }
}
```
CODE

Связанные статьи: