Общие сведения о REST API

1. Типы

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

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

Примитивные типы - Описывают простые виды объектов, такие как string (строки) или integer (целые числа).
Перечисляемые типы - Описывают списки допустимых значений, таких как VmStatus или DiskFormat.
Структурированные типы - Описывают структурированные объекты с несколькими атрибутами и ссылками, например Vm или Disk.

2. Примитивные типы данных

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

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

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

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

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

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

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

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

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

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

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

В настоящее время Менеджер реализует этот тип с помощью знакового 32-битного целого числа, поэтому минимальное значение равно -2³¹ (-2147483648), а максимальное - 2³¹-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

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

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

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

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

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

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

QuotaStorageLimit.usage
QuotaStorageLimit.memory_limit
QuotaStorageLimit.memory_usage

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

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

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

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

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

Атрибут	Тип	Описание
id	String	Каждый объект в инфраструктуре виртуализации содержит `id`, который действует как уникальный идентификатор.
href	String	Каноническое расположение объекта как абсолютный путь.
name	String	Вводимое пользователем удобочитаемое имя объекта. Имя `name` уникально для всех объектов одного типа.
description	String	Пользовательское описание объекта в свободной форме, удобочитаемое для человека.

String

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

href

String

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

name

String

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

description

String

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

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

4. Объекты

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

5. Коллекции

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

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

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

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

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

7. Сервисы

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

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

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

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

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

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

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

Имя метода	HTTP-метод
`add`	POST
`get`	GET
`list`	GET
`update`	PUT
`remove`	DELETE

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>

7.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 - только соединения, принадлежащие указанному домену хранения.

8. Управление разрешениями

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

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

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

<permissions>
  <permission id="456" href="/ovirt-engine/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 в конкретной сети).

9. Поиск

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

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

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

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

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

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

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

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

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

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

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

Таблица 1. Примеры поисковых запросов
Коллекция	Критерии	Результат
`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

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

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

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

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

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

10. Ссылки

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_attachments>
  <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 только тогда, когда это оправдано.

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

Некоторые ошибки требуют дополнительного объяснения, помимо стандартного кода состояния 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>

Код Статус Описание

200

Указывает на успешное выполнение 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 на домен хранения, который уже является мастер-доменом).