Руководство по REST API

Версия zVirt: 3.3

1. Введение

Менеджер управления включает Representational State Transfer (REST) API. API предоставляет разработчикам программного обеспечения и системным администраторам контроль над своей средой zVirt за пределами стандартного веб-интерфейса. API полезен для интеграции функций среды zVirt с пользовательскими сценариями или внешними приложениями, которые обращаются к API через стандартный протокол передачи гипертекста (HTTP).

Преимущества API
  • Широкая клиентская поддержка. Любой язык программирования, платформа или система с поддержкой протокола HTTP могут использовать API.

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

  • Модель на основе ресурсов. Модель REST на основе ресурсов обеспечивает естественный способ управления платформой виртуализации.

Это дает разработчикам и администраторам возможность
  • Интеграции с корпоративными ИТ-системами.

  • Интеграции со сторонним программным обеспечением для виртуализации.

  • Выполнения автоматизированного обслуживания или проверки ошибок.

  • Автоматизации повторяющихся задач в среде zVirt с помощью сценариев.

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

1.1. REST

Representational State Transfer (REST) ​​— это архитектура проектирования, ориентированная на ресурсы для конкретной службы и их представления. Представление ресурсов — это ключевая абстракция информации, которая соответствует одному конкретному управляемому элементу на сервере. Клиент отправляет запрос элементу сервера, расположенному по универсальному идентификатору ресурса (URI), и выполняет операции, используя стандартные методы HTTP, такие как GET, POST, PUT и DELETE. Это обеспечивает связь между клиентом и сервером без сохранения состояния, при которой каждый запрос действует независимо от любого другого запроса и содержит всю информацию, необходимую для выполнения запроса.

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

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

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

  • Клиент или программная библиотека, которая инициирует и получает 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.

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

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

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

2.1.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 на клиентском компьютере. Затем вы должны импортировать этот файл в хранилище сертификатов клиента.

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

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

2.2. Аутентификация

Любой пользователь с учетной записью Менеджера управления имеет доступ к API. Все запросы должны быть аутентифицированы с использованием OAuth или обычной аутентификации, как описано ниже.

2.2.1. OAuth-аутентификация

Предпочтительным механизмом аутентификации является 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

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

2.2.2. Базовая аутентификация

Базовая аутентификация поддерживается только для обратной совместимости; она устарела и будет удалена в будущем.

Каждый запрос использует базовую аутентификацию HTTP для кодирования учетных данных. Если запрос не включает соответствующий заголовок Authorization, сервер отправляет ответ 401 Authorization Required:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com

HTTP/1.1 401 Authorization Required

Запрос выдается с заголовком Authorization для указанной области. Закодируйте соответствующий домен и имя пользователя в предоставленных учетных данных с помощью соглашения username@domain:password.

В следующей таблице показан процесс кодирования учетных данных в Base64.

Таблица 2. Кодирование учетных данных для доступа к API
Элемент Значение

Имя пользователя

admin

Домен

internal

Пароль

mypassword

Незакодированные учетные данные

admin@internal:mypassword

Учетные данные в кодировке Base64

YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

Укажите учетные данные в кодировке Base64, как показано ниже:

HEAD /ovirt-engine/api HTTP/1.1
Host: myengine.example.com
Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==

HTTP/1.1 200 OK
Базовая аутентификация включает потенциально конфиденциальную информацию, такую ​​как пароли, отправляемые в виде обычного текста. Для API требуется безопасный протокол передачи гипертекста (HTTPS) для шифрования на транспортном уровне простых текстовых запросов.
Некоторые библиотеки Base64 разбивают результат на несколько строк и заканчивают каждую строку символом новой строки. Это ломает заголовок и вызывает ошибочный запрос. Для заголовка Authorization требуются закодированные учетные данные в одной строке заголовка.

2.2.3. Сеансы аутентификации

API также обеспечивает поддержку сеанса аутентификации. Отправьте первоначальный запрос с данными аутентификации, а затем отправьте все последующие запросы, используя файл cookie сеанса для аутентификации.

Запрос аутентифицированного сеанса
  1. Отправьте запрос с заголовками Authorization и Prefer: persistent-auth:

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
    Prefer: persistent-auth
    
    HTTP/1.1 200 OK
    ...

    Он возвращает ответ со следующим заголовком:

    Set-Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK; Path=/ovirt-engine/api; Secure

    Обратите внимание на значение JSESSIONID=. В этом примере значение равно 5dQja5ubr4yvI2MM2z+LZxrK.

  2. Отправляйте все последующие запросы с заголовками Prefer: persistent-auth и Cookie с соответствующим значением JSESSIONID=. Заголовок Authorization больше не нужен при использовании аутентифицированного сеанса.

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Prefer: persistent-auth
    Cookie: JSESSIONID=5dQja5ubr4yvI2MM2z+LZxrK
    
    HTTP/1.1 200 OK
    ...
  3. Когда сеанс больше не требуется, выполните запрос к серверу без заголовка Prefer: persistent-auth.

    HEAD /ovirt-engine/api HTTP/1.1
    Host: myengine.example.com
    Authorization: Basic YWRtaW5AaW50ZXJuYWw6bXlwYXNzd29yZA==
    
    HTTP/1.1 200 OK
    ...

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

3.1. Типы

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

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

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

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

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

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

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

Атрибут Тип Описание

id

String

Каждый объект в инфраструктуре виртуализации содержит id, который действует как уникальный идентификатор.

href

String

Каноническое расположение объекта как абсолютный путь.

name

String

Вводимое пользователем удобочитаемое имя объекта. Имя name уникально для всех объектов одного типа.

description

String

Пользовательское описание объекта в свободной форме, удобочитаемое для человека.

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

3.3. Объекты

Объекты — это отдельные экземпляры типов, поддерживаемых API. Например, виртуальная машина с идентификатором 123 является объектом типа Vm.

3.4. Коллекции

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

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

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

3.5.1. XML-представление

XML-представление объекта состоит из элемента XML, соответствующего типу объекта, атрибутов XML для атрибутов id и href и вложенных элементов XML для остальных атрибутов. Например, представление XML для виртуальной машины выглядит следующим образом:

<vm id="123" href="/ovirt-engine/api/vms/123">
  <name>myvm</name>
  <description>My VM</description>
  <memory>1073741824</memory>
  ...
</vm>

XML-представление набора объектов состоит из элемента XML, названного по типу объектов во множественном числе. Он содержит представления объектов коллекции. Например, представление XML для набора виртуальных машин выглядит следующим образом:

<vms>
  <vm id="123" href="/ovirt-engine/api/vms/123">
    <name>yourvm</name>
    <description>Your VM</description>
    <memory>1073741824</memory>
    ...
  </vm>
  <vm id="456" href="/ovirt-engine/api/vms/456">
    <name>myname</name>
    <description>My description</description>
    <memory>2147483648</memory>
    ...
  </vm>
  ...
</vms>

В теле ответа XML-представление используется по умолчанию, но для явного указания можно добавить в заголовок запроса параметр Accept: application/xml.

Для передачи тела запроса в формате XML, добавьте в заголовок запроса параметр Content-type: application/xml.

В XML-представлении объектов атрибуты id и href являются единственными, которые представлены как атрибуты XML, остальные представлены как вложенные элементы XML.

3.5.2. JSON-представление

JSON-представление объекта состоит из документа JSON, содержащего пару имя:значение для каждого атрибута (включая id и href). Например, JSON-представление виртуальной машины выглядит следующим образом:

{
  "id": "123",
  "href": "/ovirt-engine/api/vms/123",
  "name": "myvm",
  "description": "My VM",
  "memory": 1073741824,
  ...
}

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

{
  "vm": [
    {
      "id": "123",
      "href": "/ovirt-engine/api/vms/123",
      "name": "myvm",
      "description": "My VM",
      "memory": 1073741824,
      ...
    },
    {
      "id": "456",
      "href": "/ovirt-engine/api/vms/456",
      "name": "yourvm",
      "description": "Your VM",
      "memory": 2147483648,
      ...
    },
  ]
}

Для получения тела ответа в формате JSON добавьте в заголовок запроса параметр Accept: application/json

Для передачи тела запроса в формате JSON, добавьте в заголовок запроса параметр Content-type: application/json.

3.6. Сервисы

Сервисы — это части сервера, отвечающие за извлечение, добавление обновлений, удаление и выполнение действий над объектами, поддерживаемыми API.

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

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

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

Каждый сервис доступен по определенному пути внутри сервера. Например, сервис, управляющий набором виртуальных машин, доступных в системе, доступен по пути /vms, а сервис, управляющий виртуальной машиной 123, доступен по пути /vms/123.

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

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

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

add

POST

get

GET

list

GET

update

PUT

remove

DELETE

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

Например, запрос для получения списка виртуальных машин с помощью метода list должен быть таким (используется HTTP-метод GET и путь /vms):

GET /ovirt-engine/api/vms

Для методов action HTTP-метод всегда POST, а имя метода добавляется в качестве суффикса к пути. Например, запрос на запуск виртуальной машины 123 должен выглядеть так (используется HTTP-метод POST и путь /vms/123/start):

POST /ovirt-engine/api/vms/123/start

Каждый метод имеет набор параметров.

Параметры делятся на две категории:

  • Основной параметр - основной параметр соответствует объекту или коллекции, которые извлекаются, добавляются или обновляются. Это относится только к методам add, get, list и update и для каждого метода будет ровно один такой главный параметр.

  • Вторичные параметры - остальные параметры.

Например, операция добавления виртуальной машины имеет три параметра: vm, clone и clone_permissions. Основным параметром является vm, так как он описывает добавляемый объект. Параметры clone и clone_permissions являются вторичными параметрами.

Основной параметр, используемый для ввода, должен быть включен в тело HTTP-запроса. Например, при добавлении виртуальной машины в тело запроса должен быть включен параметр vm типа Vm. Таким образом, полный запрос на добавление виртуальной машины, включая все детали HTTP, должен выглядеть следующим образом:

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

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

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

HTTP/1.1 201 Created
Content-Type: application/xml

<vm href="/ovirt-engine/api/vms/123" id="123">
  <name>myvm</name>
  <description>My VM</description>
  ...
</vm>

Вторичные параметры разрешены только для ввода (за исключением методов действий, которые описаны ниже), и они должны быть включены в качестве параметров запроса. Например, при добавлении виртуальной машины с параметром clone , установленным на true, полный запрос должен выглядеть так:

POST /ovirt-engine/api/vms?clone=true HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
</vm>

Методы action имеют только вторичные параметры. Их можно использовать для ввода и вывода, и они должны быть включены в тело запроса, обернутые элементом action. Например, метод action, используемый для запуска виртуальной машины, имеет параметр vm, описывающий, как следует запускать виртуальную машину, и параметр use_cloud_init, указывающий, следует ли использовать cloud-init для настройки гостевой операционной системы. Таким образом, полный запрос на запуск виртуальной машины 123 с помощью cloud-init при использовании XML будет выглядеть следующим образом:

POST /ovirt-engine/api/vms/123/start HTTP/1.1
Host: myengine.example.com
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=
Content-Type: application/xml
Accept: application/xml

<action>
  <use_cloud_init>true</use_cloud_init>
  <vm>
    <initialization>
      <nic_configurations>
        <nic_configuration>
          <name>eth0</name>
          <on_boot>true</on_boot>
          <boot_protocol>static</boot_protocol>
          <ip>
            <address>192.168.0.100</address>
            <netmask>255.255.255.0</netmask>
            <gateway>192.168.0.1</netmask>
          </ip>
        </nic_configuration>
      </nic_configurations>
      <dns_servers>192.168.0.1</dns_servers>
    </initialization>
  </vm>
</action>

3.7. Поиск

Метод list некоторых сервисов имеет параметр search, который можно использовать для указания критериев поиска. При использовании сервер будет возвращать только те объекты коллекции, которые удовлетворяют этим критериям. Например, следующий запрос вернет только виртуальную машину с именем myvm:

GET /ovirt-engine/api/vms?search=name%3Dmyvm

3.7.1. Параметр 'max'

Используйте параметр max, чтобы ограничить количество возвращаемых объектов. Например, следующий запрос вернет только одну виртуальную машину, независимо от того, сколько их доступно в системе:

GET /ovirt-engine/api/vms?max=1

Поисковый запрос без параметра max вернет все объекты. Указание параметра max рекомендуется для снижения влияния запросов на общую производительность системы.

3.7.2. Чувствительность к регистру

По умолчанию запросы не чувствительны к регистру. Например, следующий запрос вернет виртуальные машины с именами myvm, MyVM и MYVM:

GET /ovirt-engine/api/vms?search=name%3Dmyvm

Необязательный логический параметр case_sensitive можно использовать для изменения этого поведения. Например, чтобы получить именно виртуальную машину с именем myhost, а не MyHost или MYHOST, отправьте такой запрос:

GET /ovirt-engine/api/vms?search=name%3D=myvm&case_sensitive=true

3.7.3. Синтаксис поиска

Параметры search используют тот же синтаксис, что и язык запросов zVirt:

(criteria) [sortby (element) asc|desc]

Предложение sortby является необязательным и требуется только для упорядочивания результатов.

Таблица 3. Примеры поисковых запросов
Коллекция Критерии Результат

hosts

vms.status=up

Возвращает список всех хостов, на которых запущены виртуальные машины.

vms

domain=example.com

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

vms

users.name=mary

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

events

severity > normal sortby time

Возвращает список всех событий с серьезностью выше, чем normal и отсортированных по значению атрибута time.

events

severity > normal sortby time desc

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

Значение параметра search должно быть представлено в URL кодировке для перевода зарезервированных символов, таких как операторы и пробелы. Например, знак равенства (=) должен быть закодирован как %3D:

GET /ovirt-engine/api/vms?search=name%3Dmyvm

3.7.4. Подстановочные знаки

Звездочка (*) может использоваться как часть значения, чтобы указать, что любая строка соответствует, включая пустую строку. Например, следующий запрос вернет все виртуальные машины с именами, начинающимися с myvm, например myvm, myvm2, myvma или myvm-webserver:

GET /ovirt-engine/api/vms?search=name%3Dmyvm*

3.7.5. Пагинация

Некоторые среды zVirt содержат большие коллекции объектов. Получение всех их одним запросом нецелесообразно и снижает производительность. Чтобы разрешить извлечение их страница за страницей, параметр search поддерживает необязательную опцию page. Это, в сочетании с параметром max, является основой для разделения на страницы. Например, чтобы получить первую страницу виртуальных машин с размером страницы 10 виртуальных машин, отправьте запрос следующим образом:

GET /ovirt-engine/api/vms?search=page%201&max=10
Параметр поиска представлен в URL кодировке, фактическое значение параметра search до кодирования равно page 1, что указывает на запрос первой страницы.

Увеличьте значение page, чтобы получить следующую страницу:

GET /ovirt-engine/api/vms?search=page%202&max=10

Опцию page можно использовать вместе с другими опциями внутри параметра search. Например, следующий запрос вернет вторую страницу виртуальных машин, но с сортировкой по имени:

GET /ovirt-engine/api/vms?search=sortby%20name%20page%202&max=10

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

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

3.8. Cсылки

API возвращает указания на связанные объекты в виде ссылок. Например, данные о виртуальной машине содержат ссылки на присоединённые к ней диски и сетевые карты:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <link rel="diskattachments" href="/ovirt-engine/api/vms/123/diskattachments"/>
  <link rel="nics" href="/ovirt-engine/api/vms/123/nics"/>
  ...
</vm>

Полное описание этих связанных объектов можно получить, отправив отдельные запросы:

GET /ovirt-engine/api/vms/123/diskattachments
GET /ovirt-engine/api/vms/123/nics

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

Значение параметра follow представляет собой список строк, разделенных запятыми. Каждая из этих строк является путем связанного объекта. Например, чтобы получить присоединённые диски и сетевые карты в приведенном выше примере, запрос должен быть таким:

GET /ovirt-engine/api/vms/123?follow=disk_attachments,nics

Это вернет ответ, подобный следующему:

<vm id="123" href="/ovirt-engine/api/vms/123">
  ...
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789"/>
    </disk_attachment>
    ...
  </disk_attacments>
  <nics>
    <nic id="234" href="/ovirt-engine/api/vms/123/nics/234">
      <name>eth0</name>
      <interface>virtio</interface>
      <linked>true</linked>
      <mac>
        <address>00:1a:4a:16:01:00</address>
      </mac>
      <plugged>true</plugged>
    </nic>
    ...
  </nics>
  ...
</vm>

Путь к связанному объекту может быть одним словом, как в предыдущем примере, или последовательностью слов, разделенных точками, для запроса вложенных данных. Например, в предыдущем примере использовался параметр disk_attachments для получения полного описания присоединённых дисков, но каждый блок disk_attachments содержит нераскрытую ссылку на диск (в примере выше: <disk id="789" href="/ovirt-engine/api/disks/789"/>). Для того, чтобы также перейти по ссылкам на диски, можно использовать следующий запрос:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk

Это приведет к следующему ответу:

<vm id="123" href="/ovirt-engine/api/vms/123">
  <disk_attachments>
    <disk_attachment id="456" href="/ovirt-engine/api/vms/123/diskattachments/456">
      <active>true</active>
      <bootable>true</bootable>
      <interface>virtio_scsi</interface>
      <pass_discard>false</pass_discard>
      <read_only>false</read_only>
      <uses_scsi_reservation>false</uses_scsi_reservation>
      <disk id="789" href="/ovirt-engine/api/disks/789">
        <name>mydisk</name>
        <description>My disk</description>
        <actual_size>0</actual_size>
        <format>raw</format>
        <sparse>true</sparse>
        <status>ok</status>
        <storage_type>image</storage_type>
        <total_size>0</total_size>
        ...
      </disk>
    </disk_attachment>
    ...
  </disk_attachments>
  ...
</vm>

Путь можно сделать настолько глубоким, насколько это необходимо. Например, чтобы также получить статистику дисков:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics

Можно комбинировать несколько элементов пути и несколько путей. Например, чтобы получить присоединённые диски и сетевые карты со статистикой:

GET /ovirt-engine/api/vms/123?follow=disk_attachments.disk.statistics,nics.statistics

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

Использование параметра follow перемещает нагрузку со стороны клиента на сторону сервера. Когда вы запрашиваете дополнительные данные, сервер должен получить и объединить их с основными данными. Это потребляет ЦП и память на стороне сервера и в большинстве случаев требует дополнительных запросов к базе данных. Это может отрицательно сказаться на производительности сервера, особенно в крупномасштабных средах. Обязательно протестируйте приложение в реалистичной среде и используйте параметр follow только тогда, когда это оправдано.

3.9. Разрешения

Управление разрешениями возможно с помощью сервиса permissions. Каждое разрешение содержит ссылки на пользователя или группу, роль и объект. Например, разрешения, назначенные конкретной виртуальной машине, можно получить, отправив такой запрос:

GET /ovirt-engine/api/vms/123/permissions

Тело ответа будет выглядеть так:

<permissions>
  <permission id="456" href="/ovirt-engien/api/vms/123/permissions/456">
    <user id="789" href="/ovirt-engine/api/users/789"/>
    <role id="abc" href="/ovirt-engine/api/roles/abc"/>
    <vm id="123" href="/ovirt-engine/api/vms/123"/>
  </permission>
  ...
</permissions>

Разрешение добавляется к объекту отправкой POST-запроса с представлением разрешения в этот сервис. Для каждого нового разрешения требуется роль и пользователь.

Сервис permissions может использоваться следующим образом:

  • Самостоятельно (/ovirt-engine/api/permissions): при таком использовании предполагается управление правами на уровне всей системы.

  • Как вложенный сервис: при таком использовании предполагается управление правами для конкретного объекта.

Поскольку вложенное использование сервиса permissions идентично самостоятельному, в разделе Описание сервисов отсутствует описание его применения на уровне отдельных объектов. Описание самостоятельного применения смотрите в группе Разрешения и роли.

Вложенное использование сервиса permissions допустимо по следующим путям:

  • /clusters/{cluster:id} (т.е. /clusters/{cluster:id}/permissions, далее будут описаны только пути к родительским объектам) - управление правами на уровне кластера.

  • /cpuprofiles/{profile:id} - управление правами на уровне профиля ЦП.

  • /datacenters/{datacenter:id} - управление правами на уровне центра данных.

  • /datacenters/{datacenter:id}/quotas/{quota:id} - управление правами на уровне квоты центра данных.

  • /diskprofiles/{diskprofile:id} - управление правами на уровне профиля диска.

  • /disks/{disk:id} - управление правами на уровне диска (включая возможность использования с сервисом disks в конкретном домене хранения).

  • /groups/{group:id} - управление правами группы.

  • /hosts/{host:id} - управление правами на уровне хоста.

  • /macpools/{macpool:id} - управление правами на уровне пула MAC-адресов.

  • /networks/{network:id} - управление правами на уровне логической сети (включая возможность использования с сервисом networks в конкретном центре данных).

  • /storagedomains/{storagedomain:id} - управление правами на уровне домена хранения.

  • /templates/{template:id} - управление правами на уровне шаблона ВМ.

  • /users/{user:id} - управление правами пользователя.

  • /vmpools/{pool:id} - управление правами на уровне пула ВМ.

  • /vms/{vm:id} - управление правами на уровне ВМ.

  • /vnicprofiles/{profile:id} - управление правами на уровне профиля vNIC (включая возможность использования с сервисом vnicprofiles в конкретной сети).

3.10. Обработка ошибок

Некоторые ошибки требуют дополнительного объяснения, помимо стандартного кода состояния HTTP. Например, API сообщает о неудачном обновлении состояния объекта или действии с помощью элемента fault в тексте ответа. Элемент fault содержит атрибуты reason и detail. Например, когда сервер получает запрос на создание виртуальной машины без обязательного атрибута name, он вернёт следующую строку ответа HTTP:

HTTP/1.1 400 Bad Request

И следующее тело ответа:

<fault>
  <reason>Incomplete parameters</reason>
  <detail>Vm [name] required for add</detail>
</fault>
Таблица 4. Интерпретация основных кодов
Код Статус Описание

200

OK

Указывает на успешное выполнение GET, PUT и DELETE запросов.

PUT и DELETE запросы возвращают код 200 только в случае синхронного выполнения (параметр async либо не указан, либо имеет значение false).

201

Created

Указывает на успешное выполнение POST-запроса

202

Accepted

Указывает на успешное создание задачи путем отправки асинхронного PUT или DELETE запроса (параметр async имеет значение true).

Возврат данного кода не означает, что операция выполнена успешно. Его получение указывает только на тот факт, что запрос успешно принят.

400

Bad Request

Указывает на некорректный запрос. Как правило, является результатом ошибок в теле PUT и POST запросов. Например, код 400 возвращается при передаче в теле запроса неверного параметра (naem вместо name) или его значения (internal вместо internal-authz при указании домена аутентификации), а также при отсутствии в теле требуемого параметра.

401

Unauthorized

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

  • Указан некорректный метод авторизации (например, NoAuth).

  • Истек срок действия токена авторизации.

  • Пользователь, использованный для авторизации, не имеет необходимых прав на выполнение запроса.

404

Not Found

Указывает на то, что объект, к которому производится запрос, не найден. Как правило возникает при некорректно указанном ID объекта.

405

Method Not Allowed

Указывает на то, что запрошенный метод недоступен для объекта. Например, DELETE запрос к /groups (обращение к сервису, указывающему на все группы, а не к конкретной группе /groups/{group:id})

409

Conflict

Указывает на невозможность выполнения операции. Может возникать при невыполнении требований для совершения операции, например:

  • Передача в теле POST запроса ссылки на несуществующий объект (например, код 409 будет возвращен при создании iSCSI-бонда с указанием несуществующей в центре данных логической сети).

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

  • Операция не имеет смысла (например, попытка передать роль master на домен хранения, который уже является мастер-доменом).

4. Особенности использования сервисов

4.1. Вложенные сервисы

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

Далее приводится список перечень дочерних и родительских сервисов.

  • /datacenters/{dc:id}

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

      Применение сервисов /clusters в сервисе /datacenters/{dc:id} позволяет выполнять операции только с кластерами, относящимися к соответствующему центру данных.

      Например, GET-запрос /ovirt-engine/api/clusters возвращает все кластеры, присутствующие в системе, а GET-запрос /ovirt-engine/api/datacenters/{dc:id}/clusters - только кластеры в центре данных с указанным ID.

    • /storagedomains и все относящиеся к нему запросы, описанные в группе Домены хранения (сервис /storagedomains), за исключением некоторых методов, описанных в группе Центры данных.

      Применение сервисов /storagedomains в сервисе /datacenters/{dc:id} позволяет выполнять операции только с доменами хранения, относящимися к соответствующему центру данных.

      Например, GET-запрос /ovirt-engine/api/storagedomains возвращает все существующие домены хранения, присутствующие в системе, а GET-запрос /datacenters/{datacenter:id}/storagedomains - только домены хранения в соответствующем центре данных.

  • /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}

    • /networks и все относящиеся к нему запросы, описанные в группе логические сети, за исключением POST-запроса /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks.

      Применение сервисов /networks в сервисе /datacenters/{dc:id}/iscsibonds/{iscsibond:id} позволяет выполнять операции только с сетями, относящимися к соответствующему iSCSI-бонду.

      Например, GET-запрос /ovirt-engine/api/networks возвращает все логические сети, присутствующие в системе, а GET-запрос /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/networks - только сети в iSCSI-бонде с указанным ID.

    • /storageserverconnections и все относящиеся к нему запросы, описанные в группе Домены хранения (сервис /storageconnections), за исключением POST-запроса /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections.

      Применение сервисов /storageserverconnections в сервисе /datacenters/{dc:id}/iscsibonds/{iscsibond:id} позволяет выполнять операции только с соединениями доменов хранения, относящимися к соответствующему iSCSI-бонду.

      Например, GET-запрос /ovirt-engine/api/storageconnections возвращает все существующие соединения доменов хранения, присутствующие в системе, а GET-запрос /datacenters/{datacenter:id}/iscsibonds/{iscsibond:id}/storageserverconnections - только соединения в iSCSI-бонде с указанным ID.

  • /groups

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

      Применение сервисов /roles в сервисе /groups/{group:id} позволяет выполнять операции только с ролями, назначенными указанной группе.

      Например, GET-запрос /ovirt-engine/api/roles возвращает все существующие роли, присутствующие в системе, а GET-запрос /groups/{group:id}/roles - только роли, назначенные указанной группе.

  • /users

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

      Применение сервисов /roles в сервисе /users/{user:id} позволяет выполнять операции только с ролями, назначенными указанному пользователю.

      Например, GET-запрос /ovirt-engine/api/roles возвращает все существующие роли, присутствующие в системе, а GET-запрос /users/{user:id}/roles - только роли, назначенные указанному пользователю.

  • /networks

    • /vnicprofiles и все относящиеся к нему запросы, описанные в группе Профили vNIC.

      Применение сервисов /vnicprofiles в сервисе /networks/{network:id} позволяет выполнять операции только с профилями vNIC, принадлежащими указанной логической сети.

      Например, GET-запрос /ovirt-engine/api/vnicprofiles возвращает все существующие профили vNIC, присутствующие в системе, а GET-запрос /networks/{network:id}/vnicprofiles - только профили vNIC, принадлежащие указанной логической сети.

  • /storagedomains

    • /diskprofiles и все относящиеся к нему запросы, описанные в группе Диски и профили дисков.

      Применение сервисов /diskprofiles в сервисе /storagedomains/{storagedomain:id} позволяет выполнять операции только с профилями дисков, принадлежащими указанному домену хранения.

      Например, GET-запрос /ovirt-engine/api/diskprofiles возвращает все существующие профили дисков, присутствующие в системе, а GET-запрос /storagedomains/{storagedomain:id}/diskprofiles - только профили, принадлежащие указанному домену хранения.

    • /disks и все относящиеся к нему запросы, описанные в группе Диски и профили дисков.

      Применение сервисов /disks в сервисе /storagedomains/{storagedomain:id} позволяет выполнять операции только с образами дисков, принадлежащими указанному домену хранения.

      Например, GET-запрос /ovirt-engine/api/disks возвращает все существующие образы дисков, присутствующие в системе, а GET-запрос /storagedomains/{storagedomain:id}/disks - только образы, принадлежащие указанному домену хранения.

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

      Применение сервисов /storageconnections в сервисе /storagedomains/{storagedomain:id} позволяет выполнять операции только с соединениями хранилищ, принадлежащими указанному домену хранения.

      Например, GET-запрос /ovirt-engine/api/storageconnections возвращает все существующие соединения хранилищ, присутствующие в системе, а GET-запрос /storagedomains/{storagedomain:id}/storageconnections - только соединения, принадлежащие указанному домену хранения.

5. Быстрый старт

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

  • Установленная и настроенная среда zVirt, имеющая доступ к сети.

  • Файл ISO, содержащий операционную систему виртуальной машины, которую вы хотите установить. В этой главе в качестве примера установки ISO используется CentOS 7.

В примерах используется curl для демонстрации запросов API с помощью клиентского приложения. Вы можете использовать любое приложение, которое отправляет HTTP-запросы.

Заголовки HTTP-запросов в этом примере опускают заголовки Host и Authorization. Однако эти поля являются обязательными и требуют данных, специфичных для вашей установки zVirt.

В curl примерах используется имя пользователя admin@internal, пароль mypassword, расположение сертификата /etc/pki/ovirt-engine/ca.pem и имя хоста myengine.example.com. Вы должны заменить их правильными значениями для вашей среды.

zVirt генерирует уникальный идентификатор атрибута id для каждого ресурса. Идентификационные коды в этом примере будут отличаться от идентификационных кодов в вашей среде zVirt.

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

5.1. Доступ к точке входа API

Следующий запрос извлекает представление основной точки входа для API версии 4:

GET /ovirt-engine/api HTTP/1.1
Version: 4
Accept: application/xml

Тот же запрос, но с использованием префикса URL /v4 вместо заголовка Version:

GET /ovirt-engine/api/v4 HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api

Результатом является объект типа Api:

<api>
    <link href="/ovirt-engine/api/clusters" rel="clusters"/>
    <link href="/ovirt-engine/api/clusters?search={query}" rel="clusters/search"/>
    ...
    <product_info>
        <instance_id>6fdd60c6-fdfd-11ed-94ee-00163e232a46</instance_id>
        <name>zVirt Engine</name>
        <version>
            <build>9</build>
            <full_version>4.4.9.5-1.1587.zvirt.el7</full_version>
            <major>4</major>
            <minor>4</minor>
            <revision>0</revision>
        </version>
    </product_info>
    <special_objects>
        <blank_template href="..." id="..."/>
        <root_tag href="..." id="..."/>
    </special_objects>
    <summary>
        <hosts>
            <active>3</active>
            <total>3</total>
        </hosts>
        <storage_domains>
            <active>2</active>
            <total>3</total>
        </storage_domains>
        <users>
            <active>2</active>
            <total>2</total>
        </users>
        <vms>
            <active>1</active>
            <total>1</total>
        </vms>
    </summary>
    <time>2023-06-02T18:09:00.587+03:00</time>
    ...
</api>

Если не используются ни заголовок, ни префикс URL, сервер автоматически выберет версию. Версия по умолчанию - 4. Вы можете изменить версию по умолчанию с помощью параметра конфигурации ENGINE_API_DEFAULT_VERSION:

# echo "ENGINE_API_DEFAULT_VERSION=3" > \
/etc/ovirt-engine/engine.conf.d/99-set-default-version.conf

# systemctl restart ovirt-engine

Изменение этого параметра влияет на всех пользователей API, не указывающих версию явно.

Точка входа предоставляет пользователю ссылки (link) на коллекции в среде виртуализации. Атрибут rel каждой ссылки на коллекцию предоставляет контрольную точку для каждой ссылки. На следующем шаге в этом примере исследуется коллекция центра данных, доступная по ссылке datacenters.

Точка входа также содержит другие данные, такие как product_info, special_objects и summary.

5.2. Список центров данных

zVirt при установке создает центр данных Default. В этом примере центр данных Default используется в качестве основы для виртуальной среды.

Следующий запрос извлекает представление центров данных:

GET /ovirt-engine/api/datacenters HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/datacenters

Результатом будет список объектов типа DataCenter:

<data_centers>
    <data_center href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46" id="6e1b9a78-fdfd-11ed-afe5-00163e232a46">
        <actions>
            <link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/setmaster" rel="setmaster"/>
            <link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/cleanfinishedtasks" rel="cleanfinishedtasks"/>
        </actions>
        <name>Default</name>
        <description>The default Data Center</description>
        <link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/storagedomains" rel="storagedomains"/>
        <link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/permissions" rel="permissions"/>
        <link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/clusters" rel="clusters"/>
        ...
        <local>false</local>
        <quota_mode>disabled</quota_mode>
        <status>up</status>
        <storage_format>v5</storage_format>
        <supported_versions>
            <version>
                <major>4</major>
                <minor>6</minor>
            </version>
        </supported_versions>
        <version>
            <major>4</major>
            <minor>6</minor>
        </version>
    </data_center>
</data_centers>

Обратите внимание на id вашего центра данных Default. Он идентифицирует этот центр данных по отношению к другим ресурсам вашей виртуальной среды.

Центр данных также содержит ссылку на сервис AttachedStorageDomains, который управляет доменами хранения, подключенными к центру данных:

<link href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46/storagedomains" rel="storagedomains"/>

Этот сервис используется для присоединения доменов хранения из основной коллекции storagedomains, что будет рассмотрено в этом примере позже.

5.3. Получение списка кластеров

zVirt при установке создает кластер Default. В этом примере кластер Default используется для группировки ресурсов в среде zVirt.

Следующий запрос извлекает представление коллекции кластеров:

GET /ovirt-engine/api/clusters HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/clusters

Результатом будет список объектов типа Cluster:

<clusters>
    <cluster href="/ovirt-engine/api/clusters/6e1d0a3e-fdfd-11ed-ad51-00163e232a46" id="6e1d0a3e-fdfd-11ed-ad51-00163e232a46">
        <name>Default</name>
        <description>The default server cluster</description>
        <comment></comment>
        <link href="/ovirt-engine/api/clusters/6e1d0a3e-fdfd-11ed-ad51-00163e232a46/permissions" rel="permissions"/>
        <link href="/ovirt-engine/api/clusters/6e1d0a3e-fdfd-11ed-ad51-00163e232a46/networks" rel="networks"/>
        ...
        <cpu>
            <architecture>x86_64</architecture>
            <type>Intel Icelake Server Family</type>
        </cpu>
        <version>
            <major>4</major>
            <minor>6</minor>
        </version>
        <virt_service>true</virt_service>
        <data_center href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46" id="6e1b9a78-fdfd-11ed-afe5-00163e232a46"/>
    </cluster>
</clusters>

Обратите внимание на id своего кластера Default. Он идентифицирует этот кластер по отношению к другим ресурсам вашей виртуальной среды.

Кластер Default ассоциируется с центроми данных Default посредством связи с использованием атрибутов id и href ссылки data_center:

<data_center href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46" id="6e1b9a78-fdfd-11ed-afe5-00163e232a46"/>

Ссылка networks — это ссылка на сервис DataCenterNetworks, которая управляет сетями, связанными с этим кластером. В следующем разделе коллекция сетей рассматривается более подробно.

5.4. Список логических сетей

zVirt при установке по умолчанию создает сеть ovirtmgmt. Эта сеть действует как сеть управления Менеджера управления для доступа к хостам.

Эта сеть связана с кластером Default и входит в состав центра данных Default. В этом примере сеть ovirtmgmt используется для подключения виртуальных машин.

Следующий запрос извлекает список логических сетей:

GET /ovirt-engine/api/networks HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/networks

Результатом будет список объектов типа Network:

<networks>
    <network href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009" id="00000000-0000-0000-0000-000000000009">
        <name>ovirtmgmt</name>
        <description>Management Network</description>
        <comment></comment>
        <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/permissions" rel="permissions"/>
        <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/vnicprofiles" rel="vnicprofiles"/>
        <link href="/ovirt-engine/api/networks/00000000-0000-0000-0000-000000000009/networklabels" rel="networklabels"/>
        <mtu>0</mtu>
        <port_isolation>false</port_isolation>
        <stp>false</stp>
        <usages>
            <usage>vm</usage>
        </usages>
        <vdsm_name>ovirtmgmt</vdsm_name>
        <data_center href="/ovirt-engine/api/datacenters/6e1b9a78-fdfd-11ed-afe5-00163e232a46" id="6e1b9a78-fdfd-11ed-afe5-00163e232a46"/>
    </network>
</networks>

Сеть ovirtmgmt подключена к центру данных Default через связь, использующую id центра данных.

Сеть ovirtmgmt также подключена к кластеру Default посредством связи в поднаборе сетей кластера.

5.5. Список хостов

В этом примере извлекается список хостов и отображается хост с именем host1-kf, зарегистрированным в среде виртуализации:

GET /ovirt-engine/api/hosts HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
--user 'admin@internal:mypassword' \
https://myengine.example.com/ovirt-engine/api/hosts

Результатом будет список объектов типа Host:

<hosts>
    <host href="/ovirt-engine/api/hosts/5650f5c0-6c01-4967-bce0-76465be8fbf1" id="5650f5c0-6c01-4967-bce0-76465be8fbf1">
        <name>host1-kf</name>
        <comment></comment>
        <link href="/ovirt-engine/api/hosts/5650f5c0-6c01-4967-bce0-76465be8fbf1/nics" rel="nics"/>
        ...
        <address>host1-kf</address>
        <cpu>
            <name>Intel Xeon Processor (Icelake)</name>
            <speed>3000</speed>
            <topology>
                <cores>1</cores>
                <sockets>6</sockets>
                <threads>1</threads>
            </topology>
            <type>Intel Icelake Server Family</type>
        </cpu>
        <memory>16777216000</memory>
        <os>
            <type>RHEL</type>
            <version>
                <build>2</build>
                <full_version>7.3.2 - 40.el7</full_version>
                <major>7</major>
                <minor>3</minor>
            </version>
        </os>
        <port>54321</port>
        <status>up</status>
        <cluster href="/ovirt-engine/api/clusters/6e1d0a3e-fdfd-11ed-ad51-00163e232a46" id="6e1d0a3e-fdfd-11ed-ad51-00163e232a46"/>
    </host>
</hosts>

Обратите внимание на id вашего хоста. Он идентифицирует этот хост по отношению к другим ресурсам вашей виртуальной среды.

Этот хост является членом кластера Default, а доступная подколлекция nics показывает, что этот хост подключен к сети ovirtmgmt.

5.6. Создание домена хранения данных на базе NFS

Домен хранения данных на базе NFS — это экспортированный общий ресурс NFS, подключенный к центру данных и предоставляющий хранилище для виртуализированных гостевых образов. Для создания нового домена хранения требуется запрос POST, содержащий представление домена хранения, отправленный по URL-адресу коллекции доменов хранения.

Вы можете включить опцию очистки после удаления по умолчанию в домене хранения. Чтобы настроить это, укажите wipe_after_delete в запросе POST. Этот параметр можно изменить после создания домена, но это не изменит свойства очистки после удаления уже существующих дисков.

Запрос должен быть таким:

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

А тело запроса должно выглядеть следующим образом:

<storage_domain>
  <name>mydata</name>
  <type>data</type>
  <description>My data</description>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>mydata</name>
  <description>My data</description>
  <type>data</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

Сервер использует хост myhost для создания домена хранения данных типа NFS mydata с именем пути экспорта mynfs.example.com:/exports/mydata. API также возвращает следующее представление только что созданного ресурса домена хранения типа StorageDomain:

<storage_domain href="/ovirt-engine/api/storagedomains/005" id="005">
  <name>mydata</name>
  <description>My data</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/mydata</path>
    <type>nfs</type>
  </storage>
  <storage_format>v5</storage_format>
  <type>data</type>
  <used>9663676416</used>
</storage_domain>

5.7. Создание домена ISO на базе NFS

Домен ISO на базе NFS — это смонтированная общая папка NFS, подключенная к центру данных и обеспечивающая хранилище для DVD/CD-ROM ISO и файлов образов виртуальных гибких дисков (VFD). Для создания нового домена хранения требуется запрос POST с включенным представлением домена хранения, отправленный по URL-адресу коллекции доменов хранения:

Запрос должен быть таким:

POST /ovirt-engine/api/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

А тело запроса должно выглядеть следующим образом:

<storage_domain>
  <name>myisos</name>
  <description>My ISOs</description>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>myisos</name>
  <description>My ISOs</description>
  <type>iso</type>
  <storage>
    <type>nfs</type>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
  </storage>
  <host>
    <name>myhost</name>
  </host>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/storagedomains

Сервер использует хост myhost для создания домена ISO на базе NFS, который называется myisos c путем экспорта mynfs.example.com:/exports/myisos. API также возвращает следующее представление только что созданного ресурса домена хранения типа StorageDomain:

<storage_domain href="/ovirt-engine/api/storagedomains/006" id="006">
  <name>myiso</name>
  <description>My ISOs</description>
  <available>42949672960</available>
  <committed>0</committed>
  <master>false</master>
  <status>unattached</status>
  <storage>
    <address>mynfs.example.com</address>
    <path>/exports/myisos</path>
    <type>nfs</type>
  </storage>
  <storage_format>v5</storage_format>
  <type>iso</type>
  <used>9663676416</used>
</storage_domain>

5.8. Прикрепление доменов хранения к центру данных

В следующем примере домены хранения mydata и myisos подключаются к центру данных Default.

Чтобы подключить домен хранения данных mydata, отправьте запрос следующего вида:

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

С таким телом запроса:

<storage_domain>
  <name>mydata</name>
</storage_domain>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>mydata</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains

Чтобы подключить домен ISO myisos, отправьте запрос следующего вида:

POST /ovirt-engine/api/datacenters/001/storagedomains HTTP/1.1
Accept: application/xml
Content-type: application/xml

С таким телом запроса:

<storage_domain>
  <name>myisos</name>
</storage_domain>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<storage_domain>
  <name>myisos</name>
</storage_domain>
' \
https://myengine.example.com/ovirt-engine/api/datacenters/001/storagedomains

5.9. Создание виртуальной машины

В следующем примере в кластере Default на основе шаблона Blank создается виртуальная машина с именем myvm. Запрос также определяет память виртуальной машины в размере 512 МБ и устанавливает в качестве загрузочного устройства виртуальный жесткий диск.

Запрос должен содержать объект типа Vm, описывающий создаваемую виртуальную машину:

POST /ovirt-engine/api/vms HTTP/1.1
Accept: application/xml
Content-type: application/xml

Тело запроса должно выглядеть следующим образом:

<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
</vm>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<vm>
  <name>myvm</name>
  <description>My VM</description>
  <cluster>
    <name>Default</name>
  </cluster>
  <template>
    <name>Blank</name>
  </template>
  <memory>536870912</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
  </os>
</vm>
' \
https://myengine.example.com/ovirt-engine/api/vms

Тело ответа будет объектом типа Vm:

<vm href="/ovirt-engine/api/vms/007" id="007">
  <name>myvm</name>
  <link href="/ovirt-engine/api/vms/007/diskattachments" rel="diskattachments"/>
  <link href="/ovirt-engine/api/vms/007/nics" rel="nics"/>
  ...
  <cpu>
    <architecture>x86_64</architecture>
    <topology>
      <cores>1</cores>
      <sockets>1</sockets>
      <threads>1</threads>
    </topology>
  </cpu>
  <memory>1073741824</memory>
  <os>
    <boot>
      <devices>
        <device>hd</device>
      </devices>
    </boot>
    <type>other</type>
  </os>
  <type>desktop</type>
  <cluster href="/ovirt-engine/api/clusters/002" id="002"/>
  <status>down</status>
  <original_template href="/ovirt-engine/api/templates/000" id="00"/>
  <template href="/ovirt-engine/api/templates/000" id="000"/>
</vm>

5.10. Создание сетевой карты виртуальной машины

В следующем примере создается виртуальный сетевой интерфейс для подключения примера виртуальной машины к сети ovirtmgmt.

Запрос должен быть таким:

POST /ovirt-engine/api/vms/007/nics HTTP/1.1
Content-Type: application/xml
Accept: application/xml

Тело запроса должно содержать объект типа Nic, описывающий создаваемую сетевую карту:

<nic>
  <name>mynic</name>
  <description>My network interface card</description>
</nic>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<nic>
  <name>mynic</name>
  <description>My network interface card</description>
</nic>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/nics

5.11. Создание диска виртуальной машины

В следующем примере создается диск с возможностью копирования при записи объемом 8 ГБ для примера виртуальной машины.

Запрос должен быть таким:

POST /ovirt-engine/api/vms/007/diskattachments HTTP/1.1
Content-Type: application/xml
Accept: application/xml

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

<disk_attachment>
  <bootable>false</bootable>
  <interface>virtio</interface>
  <active>true</active>
  <disk>
    <description>My disk</description>
    <format>cow</format>
    <name>mydisk</name>
    <provisioned_size>8589934592</provisioned_size>
    <storage_domains>
      <storage_domain>
        <name>mydata</name>
      </storage_domain>
    </storage_domains>
  </disk>
</disk_attachment>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<disk_attachment>
  <bootable>false</bootable>
  <interface>virtio</interface>
  <active>true</active>
  <disk>
    <description>My disk</description>
    <format>cow</format>
    <name>mydisk</name>
    <provisioned_size>8589934592</provisioned_size>
    <storage_domains>
      <storage_domain>
        <name>mydata</name>
      </storage_domain>
    </storage_domains>
  </disk>
</disk_attachment>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/diskattachments

Атрибут storage_domains указывает API хранить диск в домене хранения данных mydata.

5.12. Прикрепление ISO-образа к виртуальной машине

Загрузочный носитель для следующего примера виртуальной машины требует ISO-образ компакт-диска или DVD для установки операционной системы. В этом примере используется образ CentOS 7.

Для использования виртуальными машинами образы ISO должны быть доступны в домене ISO myisos. Вы можете использовать сервисы ImageTransfers для создания передачи образа и ImageTransfer для загрузки ISO-образа.

После загрузки ISO-образа можно использовать API для запроса списка файлов из домена хранения ISO:

GET /ovirt-engine/api/storagedomains/006/files HTTP/1.1
Accept: application/xml

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request GET \
--header 'Version: 4' \
--header 'Accept: application/xml' \
https://myengine.example.com/ovirt-engine/api/storagedomains/006/files

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

<files>
  <file href="..." id="CentOS-7-x86_64-Minimal.iso">
    <name>CentOS-7-x86_64-Minimal.iso</name>
  </file>
  ...
</files>

Пользователю API необходимо прикрепить CentOS-7-x86_64-Minimal.iso к примеру виртуальной машины. Прикрепление ISO-образа эквивалентно использованию кнопки Сменить CD на администрирования или пользовательском портале.

Запрос должен быть таким:

PUT /ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000 HTTP/1.1
Accept: application/xml
Content-type: application/xml

Тело запроса должно быть объектом типа Cdrom, содержащим внутренний атрибут file для указания идентификатора образа ISO:

<cdrom>
  <file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request PUT \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<cdrom>
  <file id="CentOS-7-x86_64-Minimal.iso"/>
</cdrom>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/cdroms/00000000-0000-0000-0000-000000000000

Дополнительные сведения см. в документации сервиса VmCdrom, управляющего компакт-дисками виртуальных машин.

5.13. Запуск виртуальной машины

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

Запрос должен быть таким:

POST /ovirt-engine/api/vms/007/start HTTP/1.1
Accept: application/xml
Content-type: application/xml

Тело запроса должно выглядеть следующим образом:

<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>

Тот же запрос с помощью команды curl:

== curl \
--cacert '/etc/pki/ovirt-engine/ca.pem' \
--user 'admin@internal:mypassword' \
--request POST \
--header 'Version: 4' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--data '
<action>
  <vm>
    <os>
      <boot>
        <devices>
          <device>cdrom</device>
        </devices>
      </boot>
    </os>
  </vm>
</action>
' \
https://myengine.example.com/ovirt-engine/api/vms/007/start

В теле запроса в качестве загрузочного устройства виртуальной машины задается CD-ROM только для этой загрузки. Это позволяет виртуальной машине установить операционную систему из прикрепленного ISO-образа. Загрузочное устройство возвращается к диску для всех будущих загрузок.

6. Сервисы

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

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

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

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

{
    "data_center": [
        {
            "local": "false",
            "quota_mode": "disabled",
            "status": "up",
            "storage_format": "v5",
            "version": {
                "major": "4",
                "minor": "7"
            },
            "name": "Default",
            "description": "The default Data Center",
        }
    ]
}

Из примера выше для создания ЦД нужны следующие данные:

  • local - указание типа хранилища (обязательно)

  • name - имя ЦД (обязательно)

  • quota_mode - режим квотирования

  • description - описание ЦД

Следовательно в теле POST-запроса /datacenters указать следующее (структура аналогична примеру, но не требуется элемент верхнего уровня data_center):

{
  "local": "false",
  "quota_mode": "audit",
  "name": "SDNDC",
  "description": "Datacenter for SDN"
}

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

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

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.

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

Приложение A: Примитивные типы данных

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

A.1. Тип данных string

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

A.2. Тип данных boolean

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

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

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

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

A.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 будет реализован с использованием целых чисел с неограниченной точностью, поэтому указанные выше ограничения и исключения со временем исчезнут.

A.4. Тип данных decimal

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

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

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

  • QuotaStorageLimit.usage

  • QuotaStorageLimit.memory_limit

  • QuotaStorageLimit.memory_usage

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

A.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.