Руководство по REST API для SDN

Версия zVirt: 4.2

1. Введение

Для поддержки и управления структурой программно-управляемых сетей посредством архитектуры REST предоставляется API для SDN на базе сервиса 'zvirt-engine-backend'.

Данное API дополняет оригинальное REST API zVirt и придерживается основных принципов его построения, но в отличии от оригинального реализует доступ по HTTP(S) протоколу, без реализации SDK.

Эта документация служит справочником по REST API для SDN. Она предназначена для предоставления разработчикам и администраторам инструкций и примеров, которые помогут использовать функциональные возможности программно-управляемых сетей через API.

2. Предварительные требования к API

Предварительные требования для использования REST API для SDN:

  • Сетевая установка zVirt Engine, включающая API.

  • Клиент или программная библиотека, которая инициирует и получает HTTP-запросы от сервера API. Например:

    • Инструмент командной строки cURL.

    • RESTClient — отладчик для веб-служб RESTful.

    • Postman — HTTP-клиент для тестирования API.

  • Знание протокола передачи гипертекста (HTTP), протокола, используемого для взаимодействия с REST API. Инженерная рабочая группа Интернета публикует запрос комментариев (RFC) с объяснением протокола передачи гипертекста по адресу http://www.ietf.org/rfc/rfc2616.txt.

  • Знание расширяемого языка разметки (XML) или нотации объектов JavaScript (JSON), которые API использует для создания представлений ресурсов. W3C предоставляет полную спецификацию XML на http://www.w3.org/TR/xml. ECMA International предоставляет бесплатную публикацию по JSON на http://www.ecma-international.org.

3. Аутентификация и безопасность

Предпочтительным механизмом аутентификации является OAuth 2.0, как описано в RFC 6749.

OAuth — это сложный протокол с несколькими механизмами получения токенов авторизации и доступа. Для использования с API поддерживается только предоставление учетных данных владельца ресурса, как описано в разделе 4.3 RFC 6749.

Сначала необходимо получить токен, отправив имя пользователя и пароль в службу единого входа Менеджера управления:

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Тело запроса должно содержать параметры grant_type, scope, username и password:

Таблица 1. Параметры запроса токена OAuth
Имя Значение

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

Эти параметры должны быть представлены в URL кодировке. Например, символ @ в имени пользователя должен быть закодирован как %40. Результирующее тело запроса будет примерно таким:

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
Параметр scope описан как необязательный в OAuth RFC, но при использовании его с API он является обязательным, и его значение должно быть ovirt-app-api.

Если имя пользователя и пароль верны, служба единого входа Менеджера управления ответит документом JSON, подобным этому:

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

Для целей аутентификации API единственной подходящей парой имя/значение является access_token. Ни в коем случае не манипулируйте этим; используйте его точно так, как это предусмотрено службой единого входа.

После получения токена его можно использовать для выполнения запросов к API, включив его в заголовок HTTP Authorization и используя схему Bearer. Например, чтобы получить список виртуальных машин, отправьте такой запрос:

GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

Токен можно использовать несколько раз для нескольких запросов, но в конечном итоге срок его действия истечет. По истечении этого срока сервер отклонит запрос с кодом ответа HTTP 401:

HTTP/1.1 401 Unauthorized

В этом случае требуется новый токен, так как служба единого входа Менеджера управления в настоящее время не поддерживает обновление токенов. Новый токен можно запросить тем же способом, который описан выше.

3.1. Ролевая модель

При обращении к REST API для SDN от имени пользователя необходимо учитывать, что у пользователя должны быть роли SDN Manager, SDN ACL Manager, со следующими привилегиями:

  • SDN_INFRASTRUCTURE_MANAGEMENT, используется для всех запросов на создание, редактирование и удаление логических сетей, внешних сетей, подсетей, маршрутизаторов и интерфейсов маршрутизатора;

  • SDN_ROUTER_CONFIGURATION используется для запросов, редактирующих NAT, таблицу маршрутов и внешний интерфейс маршрутизаторов;

  • SDN_ACL_MANAGEMENT используется для запросов, связанных с созданием, редактированием и удалением групп безопасности и правил безопасности;

  • SDN_ACL_CONFIGURATION используется для запросов, связанных с добавлением/удалением групп безопасности на портах, а также с управлением политикой безопасности портов.

Для добавления необходимых ролей и привилегий пользователю необходимо:

  • Создать пользователя через Портал Keycloak, для этого:

    • Подключитетесь к порталу Keycloak;

      keycloak1

    • Перейдите во вкладку Users и нажмите Add User;

      keycloak2

    • Задайте пользователю имя в поле Username и добавьте в группу ovirt-administrator в поле Groups;

      keycloak3

    • После создания пользователя, перейдите в его свойства и во вкладке Credentials задайте пароль нажав на Set password;

      keycloak4

  • Настроить роли и привилегии пользователя, для этого:

    • На Портале администрирования перейдите в Управление  Пользователи.

      Нажмите Добавить, в параметрах поиска в качестве базы пользователей укажите internalsso (internalkeycloak-authz) и введите имя пользователя в поисковой строке. После обнаружения пользователя, выделите его в списке и нажмите Добавить и закрыть.

      keycloak5

    • Для снятия ограничений по количеству сессий и времени сессии, выделите пользователя из списка нажмите Управление сессиями и в полях Количество сессий и Время сессий(минуты) установите значение 0;

      keycloak6

    • Для добавления привилегий пользователю необходимо открыть свойства пользователя, далее во вкладке Разрешения нажать Добавление системных разрешений выбрать из списка роли SDNACLManager и SDNManager.

      keycloak7

3.2. TLS/SSL-сертификация

API zVirt требует защищенного протокола передачи гипертекста (HTTPS) для безопасного взаимодействия с клиентским программным обеспечением. Это включает в себя получение сертификата ЦС, используемого сервером, и его импорт в хранилище сертификатов вашего клиента.

3.2.1. Получение CA сертификата

Вы можете получить CA сертификат от Менеджера управления zVirt и передать его на клиентскую машину одним из следующих способов:

Способ 1

Предпочтительный метод получения CA сертификата — использовать инструмент командной строки openssl s_client для выполнения реального рукопожатия TLS с сервером, а затем извлечь сертификаты, которые он представляет. Запустите команду следующим образом:

$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null

Эта команда подключится к серверу и отобразит вывод, подобный следующему:

CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
 0 s:/C=US/O=Example Inc./CN=myengine.example.com
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

Текст между маркерами -----BEGIN CERTIFICATE----- и -----END CERTIFICATE----- показывает сертификаты, представленные сервером. Первый — это сертификат самого сервера, а последний — CA сертификат. Скопируйте CA сертификат вместе с метками в файл ca.crt. Результат должен выглядеть так:

-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
Это самый надежный способ получить CA сертификат, используемый сервером. Остальные описанные здесь способы сработают в большинстве случаев, но они не дадут правильный CA сертификат, если он был вручную заменен администратором сервера.
Способ 2

Если вы не можете использовать описанный выше метод openssl s_client, вы можете вместо этого использовать инструмент командной строки для загрузки CA сертификата из Менеджера управления zVirt.

Примеры инструментов командной строки включают curl и wget, оба из которых доступны на нескольких платформах.

При использовании curl:

$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

При использовании wget:

$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
Способ 3

С помощью веб-браузера перейдите к сертификату, расположенному по адресу:

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

В зависимости от выбранного браузера сертификат загружается или импортируется в хранилище ключей браузера.

  • Если браузер загружает сертификат: сохраните файл как ca.crt.

  • Если браузер импортирует сертификат: экспортируйте его из параметров сертификации браузера и сохраните как ca.crt.

Способ 4

Войдите в Менеджер управления, экспортируйте сертификат из хранилища доверенных сертификатов и скопируйте его на свой клиентский компьютер.

  1. Войдите на машину с Менеджером управления как root.

  2. Экспортируйте сертификат из хранилища доверенных сертификатов с помощью утилиты keytool:

    # keytool \
-keystore /etc/pki/ovirt-engine/.truststore \
-storepass mypass \
-exportcert \
-alias cacert \
-rfc \
-file ca.crt

    Это создает файл сертификата с именем ca.crt.

  3. Скопируйте сертификат на клиентскую машину с помощью команды scp:

    $ scp ca.crt myuser@myclient.example.com:/home/myuser/.

Каждый из этих методов приводит к созданию файла сертификата с именем ca.crt на клиентском компьютере. Затем вы должны импортировать этот файл в хранилище сертификатов клиента.

3.2.2. Импорт сертификата в клиент

Импорт сертификата клиенту зависит от того, как клиент хранит и интерпретирует сертификаты. Дополнительную информацию об импорте сертификата см. в документации вашего клиента.

4. Общие понятия

4.1. Типы

API использует концепцию типов для описания различных видов принимаемых и возвращаемых объектов.

Существует три соответствующих вида типов:

  • Примитивные типы - Описывают простые виды объектов, такие как string (строки) или integer (целые числа).

  • Перечисляемые типы - Описывают списки допустимых значений, таких как status или DiskFormat.

  • Структурированные типы - Описывают структурированные объекты с несколькими атрибутами и ссылками, например subnet или network.

4.2. Идентифицируемые типы

Многие из типов, используемых API, представляют собой идентифицируемые объекты, объекты, которые имеют уникальный идентификатор и существуют независимо от других объектов.

4.3. Объекты

Объекты — это отдельные экземпляры типов, поддерживаемых API. Например, логическая сеть с идентификатором 3d6ff755 является объектом типа Network.

4.4. Коллекции

Коллекция — это набор объектов одного типа.

4.5. Представления

Состояние объектов должно быть представлено при их передаче между клиентом и сервером. API поддерживает XML и JSON в качестве представления состояния объектов как для ввода, так и для вывода.

5. Сервисы

Модель REST API основана на ресурсах. Ресурс в рамках данного руководства рассматривается как сервис, выполняющий операции только над одной сущностью (entity).

Существует два соответствующих вида сервисов:

  • Сервисы, управляющие коллекцией объектов - эти сервисы отвечают за перечисление существующих объектов и добавление новых объектов. Например, сервис Networks отвечает за управление набором логических сетей, доступных в системе.

  • Сервисы, управляющие конкретным объектом - эти сервисы отвечают за получение, обновление, удаление и выполнение действий в определенных объектах. Например, сервис Subnet отвечает за управление конкретной логической подсетью.

Каждый сервис доступен по определенному пути внутри сервера. Например, сервис, управляющий набором логических сетей, доступных в системе, доступен по пути /ovn/networks, а сервис, управляющий логической сетью с идентификатором 123, доступен по пути /ovn/networks/123.

Все виды сервисов имеют набор методов, представляющих операции, которые они могут выполнять. Сервисы, управляющие коллекциями объектов, обычно имеют методы list и add. Сервисы, управляющие определенными объектами, обычно имеют методы get, update и remove. Кроме того, сервисы могут также иметь методы action, представляющие менее распространенные операции.

Для более обычных методов существует прямое сопоставление между именем метода и именем метода HTTP:

Имя метода HTTP-метод

add

POST

get

GET

list

GET

update

PUT

remove

DELETE

Путь, используемый в HTTP-запросе — это путь сервиса с префиксом /zvirt-engine-backend/v3/ovn/.

Существуют групповые сервисы, выполняющие действия над типом сущностей (например, логический маршрутизатор), такие как получить список объектов, создать новый объект, так и сервисы непосредственно конкретной сущности (сервис конкретного логического маршрутизатора), позволяющий выполнять операции над конкретной сущностью (добавить/удалить интерфейс маршрутизатора).

5.1. Особенности сервисов

Некоторые сервисы могут быть определены как самостоятельные или быть вложенными в другие сервисы. Параметры запросов к вложенным сервисам, как правило, соответствуют базовому применению.

В качестве примера рассмотрим сервис /routers/{router:id}, который содержит в себе вложенные сервисы:

  • /gateway и все относящиеся к нему запросы, описанные в группе Gateway.

    Применение сервисов /gateway в сервисе /routers/{router:id} позволяет выполнять операции только с параметрами внешнего подключения данного логического маршрутизатора.

    Например, GET-запрос /zvirt-engine-backend/v3/ovn/routers/{router:id}/gateway возвращает такие параметры внешнего подключения как, описание внешней сети (network_id),параметры порта (port_id), прикрепленный IP-адрес (external_fixed_ips),информацию о шасси (gateway_chassis).

    {
    "network_id": "5289bbbf-7780-4b6e-9a9e-6f04bc1c084d",
    "port_id": "c14ac60d-18b0-451b-8bb6-3253c261a7a4",
    "external_fixed_ips": [
        {
            "ip_address": "10.252.22.55",
            "subnet_id": "7b9ef105-246b-4cde-b5b5-c594f277b78b",
            "link": [
                {
                    "rel": "subnet",
                    "href": "/v3/ovn/subnets/7b9ef105-246b-4cde-b5b5-c594f277b78b"
                }
            ]
        }
    ],
    "gateway_chassis": [
        {
            "id": "6be8b4c8-9029-4795-b5f6-3706b05d7a10",
            "name": "lrp412e6583-5683-48d1-8c9c-41e33757d79d_h1zv42.apolishchuk.local",
            "chassis_name": "h1zv42.apolishchuk.local",
            "chassis_hostname": "h1zv42.apolishchuk.local",
            "priority": 0
        }
    ],
    "mac": "02:0a:53:c7:f1:cf",
    "link": [
        {
            "rel": "network",
            "href": "/v3/ovn/external_networks/5289bbbf-7780-4b6e-9a9e-6f04bc1c084d"
        }
    ]
}

  • /interfaces и все относящиеся к нему запросы, описанные в группе interfaces.

    Применение сервисов /interfaces в сервисе /routers/{router:id} позволяет выполнять операции только над внутренними интерфейсами, относящимися к соответствующему логическому маршрутизатору.

Например, GET-запрос /zvirt-engine-backend/v3/ovn/routers/{router:id}/interfaces возвращает информацию о прикрепленной логической сети, подсети и IP-адресе внутреннего интерфейса маршрутизатора.

+

[
    {
        "id": "c50fd8c2-87ff-4fee-8b12-348ff91e837a",
        "network_id": "196dd3e8-c618-4ba9-a322-5a1066583359",
        "subnet_id": "c50fd8c2-87ff-4fee-8b12-348ff91e837a",
        "port_id": "6474207d-95d9-4169-8e81-e0feac52811d",
        "fixed_ip": "192.168.1.254",
        "link": [
            {
                "rel": "network",
                "href": "/v3/ovn/networks/196dd3e8-c618-4ba9-a322-5a1066583359"
            },
            {
                "rel": "subnet",
                "href": "/v3/ovn/subnets/c50fd8c2-87ff-4fee-8b12-348ff91e837a"
            }
        ]
    },
    {
        "id": "f1485029-085f-4bdd-91a2-daf238090ec0",
        "network_id": "a2fa6485-da0d-462a-91a6-debeb4312db2",
        "subnet_id": "f1485029-085f-4bdd-91a2-daf238090ec0",
        "port_id": "d6fea39c-1f70-414d-8b01-9a7a9e6469f4",
        "fixed_ip": "10.10.10.55",
        "link": [
            {
                "rel": "network",
                "href": "/v3/ovn/networks/a2fa6485-da0d-462a-91a6-debeb4312db2"
            },
            {
                "rel": "subnet",
                "href": "/v3/ovn/subnets/f1485029-085f-4bdd-91a2-daf238090ec0"
            }
        ]
    }
]

  • /nat и все относящиеся к нему запросы, описанные в группе nat.

    Применение сервисов /nat в сервисе /routers/{router:id} позволяет выполнять операции только над механизмами NAT, относящимися к соответствующему логическому маршрутизатору.

    Например, GET-запрос /zvirt-engine-backend/v3/ovn/routers/{router:id}/nat возвращает информацию о типе NAT, IP-адреса внешнего и внутренного интерфеса используемого для преобразования для конкретного маршрутизатора.

    [
    {
        "id": "8b33b202-e5c0-482b-8326-f484fb3c4f07",
        "external_ip": "10.252.22.23",
        "logical_ip": "192.168.1.1",
        "external_mac": "56:6f:5c:ac:00:04",
        "logical_port": "6dcf1122-4183-412f-86de-97d3d0ddb2c5",
        "type": "fip"
    }
]

5.2. Описание представления сервисов

Схема данных для сервисов находится в процессе исследования и описания.

Для получения недостающей информации на данный момент можно использовать выполнить GET-запрос к нужному существующему объекту и использовать результаты вывода для PUT и POST запросов.

Например, необходимо создать новую подсеть. Для этого предварительно сделайте GET-запрос к существующему списку подсетей. В теле ответа будет содержаться необходимая схема.

Пример ответа:

[
    {
        "id": "3c73f210-e60d-40a6-a00c-94ba896acc43",
        "name": "outsubnet2",
        "cidr": "10.252.22.0/24",
        "network_id": "377da53f-8252-4f6f-81e7-54df3e1a84d8",
        "dns_nameservers": [],
        "gateway_ip": "10.252.22.100",
        "link": [
            {
                "rel": "network",
                "href": "/v3/ovn/external_networks/377da53f-8252-4f6f-81e7-54df3e1a84d8"
            }
        ]
    }
]

Из примера выше, для создания логической подсети нужны следующие данные:

  • name - имя логической подсети (обязательно)

  • cidr - IP-адрес подсети с маской (обязательно)

  • network_id - идентификатор логической сети(обязательно)

  • gateway_ip - адрес шлюза(обязательно)

  • dns_nameservers - IP-адрес DNS сервера (не обязательно)

Следовательно в теле POST-запроса /subnets указать следующие обязательные параметры:

{
    "name": "API-subnet",
    "cidr": "10.252.23.0/24",
    "gateway_ip": "10.252.23.254",
    "network_id": "377da53f-8252-4f6f-81e7-54df3e1a88e2",
    "dns_nameservers": [
        "10.252.10.10"
    ]
}

5.3. Описание интерфейса отображения сервисов

Описанные ниже методы сервисов расположены во фрейме, который содержит интерактивные элементы, обеспечивающие удобное представление.

base interface
Общие элементы управления

  1. Инструменты управления отображением:

    • Expand all - позволяет развернуть все категории.

    • Collapse all - позволяет свернуть все категории.

  2. Список категорий. При клике на заголовок категории можно свернуть/развернуть ее содержимое.

  3. Список сервисов и их методов в категории. При клике на строку метода можно свернуть/развернуть его описание.

requests
Элементы управления в описании методов

  1. Общее и подробное описание метода.

  2. Поле параметров запроса:

    • query-string parameters - параметры передаваемые в строке запроса (например, /ovirt-engine/api/datacenters?max=3)

    • request body - содержимое тела запроса. На вкладке Example представлен пример, на вкладке Schema - схема данных.

      Тело запроса применяется только в POST- и PUT-запросах.

      На вкладке Schema представлено подробное описание параметров объекта. По умолчанию описание отображается в однострочном формате, поэтому часть описания может быть не видна. Для отображения полного формата нажмите Multiline description.

    • request headers - список специфических параметров, которые необходимо включить в заголовок запроса.

  3. Поле параметров ответа:

    • В верхней части содержит возвращаемые коды с описанием. В большинстве случаев представлен только пример успешного выполнения, но могут встретиться дополнительные коды (см. скрин ниже). Поскольку все методы используют одинаковый набор кодов ответа, их описание вынесено в таблицу в разделе обработка ошибок.

      codes

    • На вкладке Example представлен пример, на вкладке Schema - схема данных.

      На вкладке Schema представлено подробное описание параметров объекта. По умолчанию описание отображается в однострочном формате, поэтому часть описания может быть не видна. Для отображения полного формата нажмите Multiline description.

5.4. Сервисы логических сетей

Сервис логических сетей позволяет средствами API управлять программно-определяемыми логическими сетями.

api1

5.4.1. Описание методов логических сетей

5.5. Сервисы внешних сетей

Описанные ниже методы, используются для управления внешними сетями средствами API.

api2

5.5.1. Описание методов внешних сетей

5.6. Сервисы подсетей

Описанные ниже методы, используются для управления подсетями средствами API.

api3

5.6.1. Описание методов подсетей

5.7. Сервисы маршрутизаторов

Описанные ниже методы, используются для управления логическими маршрутизаторами средствами API.

api4

Логический маршрутизатор имеет достаточно сложную структуру корневого объекта и имеет отдельные методы по работе с вложенными сущностями, такими как механизмы NAT,таблица маршрутизации и шасси.

Свойства объекта можно поделить на следующие категории:

  1. Свойства самого роутера (id, name);

  2. Свойства внешнего подключения (external_gateway_info);

  3. Список NAT;

  4. Список маршрутов;

  5. Список интерфейсов.

Вся работа с маршрутизаторами происходит непосредственно через сервис роутера, в том числе и с вложенными сущностями.

5.7.1. Описание методов маршрутизаторов

5.8. Сервисы логических портов

Описанные ниже методы, используются для управления логическими портами средствами API.

api5

Модель логического порта будет разделена на несколько дочерних объектов:

  1. Список присвоенных адресов (fixed_ips);

  2. Объект безопасности порта - флаг и список доступных пар MAC/IP порта;

  3. Объект правил безопасности - флаг и список присвоенных групп безопасности порта;

Такое разбиение позволяет разгрузить объект порта от проверок, а также предоставить конкретные вызовы для различных видов модификации порта.

5.8.1. Описание методов логических портов

5.9. Сервис правил безопасности

На данный момент в системе существует два отдельных сервиса, связанных с правилами безопасности:

  1. Сервис групп безопасности;

  2. Сервис правил безопасности.

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

5.9.1. Описание методов правил безопасности

5.10. Сервис методов зеркалирования

Описанные ниже методы, используются для управления методами зеркалирования средствами API.

api6

5.10.1. Описание методов зеркалирования

6. Типы данных

В этом разделе описываются примитивные типы данных, поддерживаемые API.

6.1. Тип данных string

Конечная последовательность символов Unicode.

6.2. Тип данных boolean

Представляет собой понятия "ложь (false)" и "истина (true)", используемые в математической логике.

Допустимыми значениями являются строки false и true.

Регистр игнорируется Менеджером, поэтому, например, False и FALSE также являются допустимыми значениями. Однако сервер всегда будет возвращать значения в нижнем регистре.

Для обратной совместимости со старыми версиями Менеджера также принимаются значения 0 и 1. Значение 0 `имеет тот же смысл, что и `false, а 1 - тот же смысл, что и true. Старайтесь не использовать эти значения, поскольку в будущем их поддержка может быть прекращена.

6.3. Тип данных integer

Представляет собой математическое понятие целого числа.

Допустимыми значениями являются конечные последовательности десятичных цифр.

В настоящее время Менеджер реализует этот тип с помощью знакового 32-битного целого числа, поэтому минимальное значение равно -231 (-2147483648), а максимальное - 231-1 (2147483647).

Однако в системе есть некоторые атрибуты, для которых диапазон значений, возможных при использовании 32 бит, недостаточен. В этих исключительных случаях Менеджер использует 64-битные целые числа, в частности, для следующих атрибутов:

  • Disk.actual_size

  • Disk.provisioned_size

  • GlusterClient.bytes_read

  • GlusterClient.bytes_written

  • Host.max_scheduling_memory

  • Host.memory

  • HostNic.speed

  • LogicalUnit.size

  • MemoryPolicy.guaranteed

  • NumaNode.memory

  • QuotaStorageLimit.limit

  • StorageDomain.available

  • StorageDomain.used

  • StorageDomain.committed

  • VmBase.memory

Для этих исключений минимальное значение равно -263 (-9223372036854775808), а максимальное - 263-1 (9223372036854775807).

В будущем тип integer будет реализован с использованием целых чисел с неограниченной точностью, поэтому указанные выше ограничения и исключения со временем исчезнут.

6.4. Тип данных decimal

Представляет собой математическое понятие действительного числа.

В настоящее время Менеджер реализует этот тип, используя 32-битные числа IEEE 754 с плавающей запятой одинарной точности.

Для некоторых атрибутов такой точности недостаточно. В этих исключительных случаях Менеджер использует 64-битные числа с плавающей запятой двойной точности, в частности, для следующих атрибутов:

  • QuotaStorageLimit.usage

  • QuotaStorageLimit.memory_limit

  • QuotaStorageLimit.memory_usage

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

6.5. Тип данных date

Представляет собой дату и время.

Формат, возвращаемый Менеджером, соответствует формату, описанному в спецификации XML Schema при запросе XML. Например, для получения XML-представления виртуальной машины можно отправить такой запрос:

GET /ovirt-engine/api/vms/123
Accept: application/xml

Тело ответа будет содержать следующий XML-документ:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <creation_time>2016-09-08T09:53:35.138+03:00</creation_time>
  ...
</vm>

При запросе JSON-представления Менеджер использует другой формат: целое число, содержащее количество миллисекунд с 1 января 1970 года, называемое также временем эпохи. Например, если послать такой запрос для получения JSON-представления виртуальной машины:

GET /ovirt-engine/api/vms/123
Accept: application/json

Тело ответа будет содержать следующий JSON-документ:

{
  "id": "123",
  "href="/ovirt-engine/api/vms/123",
  ...
  "creation_time": 1472564909990,
  ...
}
В обоих случаях даты, возвращаемые Менеджером, используют часовой пояс, настроенный на сервере, где он запущен, в приведенных примерах это UTC+3.