Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Руководство по REST API для папок ВМ

1. Введение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

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

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

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

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

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

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

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

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

HTTP/1.1 401 Unauthorized

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

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

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

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

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

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

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

4.1. Типы

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

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

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

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

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

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

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

4.3. Объекты

Объекты — это отдельные экземпляры типов, поддерживаемых API. Например, папка виртуальной машины с идентификатором fc942e0d-1b94-4c93-bf0b-99ae9ed04c5f является объектом типа VM_FOLDER.

4.4. Коллекции

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

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

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

5. Сервисы

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

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

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

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

Реализован ряд сервисов для работы с API папок виртуальных машин:

  1. VmFoldersService — сервис, обеспечивающий выполнение операций с папками виртуальных машин, поддерживает следующий функционал:

    • получение папки ВМ по её уникальному идентификатору;

    • вывод полного списка папок ВМ;

    • изменение свойств существующей папки VM;

    • создание новой папки ВМ;

    • удаление папки ВМ по указанному идентификатору;

    • проверка наличия вложенных объектов в указанной папке ВМ.

  2. VmFoldersTreeService - сервис, предназначенный для выполнения операций с древовидной структурой папок виртуальных машин.

    Реализует следующий функционал:

    • получение структурированного представления дерева папок с включением или исключением виртуальных машин;

    • перемещение отдельных объектов в пределах дерева папок;

    • перемещение групп объектов в рамках дерева;

    • извлечение конкретного узла дерева папок;

    • получение идентификаторов всех потомков или исключительно непосредственных дочерних узлов заданного типа;

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

    • определение родительской папки для указанного объекта;

    • формирование поддерева для указанных объектов;

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

  3. VmFolderActionCheckerService - сервис, осуществляющий проверку возможности выполнения операций с элементами дерева папок виртуальных машин.

    Поддерживаемые функции сервиса:

    • Проверка выполнения операции с корневым элементом дерева и выброс исключения в подобном случае;

    • Проверка наличия необходимых прав доступа для совершения запрашиваемого действия и выдача ошибки при их отсутствии;

    • Анализ ограничений на перемещение объекта в дерево папок и уведомление об ошибке в случае нарушения любого из них;

    • Проверка типа родительского объекта: валидация того, что целевой родительский элемент не является виртуальной машиной (ВМ), с генерацией ошибки при попытке назначения родителя типа ВМ;

    • Проверка типа удаляемого объекта: подтверждение того, что удаляемый элемент не является виртуальной машиной (ВМ) перед выполнением операции удаления;

    • Проверка условий для удаления объекта в дереве с генерацией ошибки в случае нарушения любого из них;

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

Каждый сервис доступен по определенному пути внутри сервера. Например, сервис, управляющий структурой папок ВМ, существующих в системе, доступен по пути /folders/vm/v1, а сервис, управляющий папкой ВМ с идентификатором 123, доступен по пути /folders/vm/v1/123.

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

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

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

add

POST

get

GET

list

GET

update

PUT

remove

DELETE

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

5.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. Описание методов папок ВМ