Добрый день. Сегодня я хотел бы рассказать вам о том, как можно работать с VMware vRealize Orchestrator через REST API.
REST API, реализованный в Orchestrator, позволяет с помощью сгенерированных HTTP запросов выполнять различные операции, например:
- запускать Workflow;
- отслеживать статус работающих или уже выполненных Workflow;
- создавать задания, которые запускают Workflow по расписанию;
- проверять входные параметры для workflow на корректность.
- получать информацию о различных объектах, присутствующих в иерархии Orchestrator.
Через REST API можно выполнить интеграции vRealize Orchestrator с любыми сторонними системами, будь то системы автоматизации, порталы самообслуживания, CMDB системы или другие средства оркестрации.
Подготовка к работе
Для демонстрации возможностей работы с REST API я буду использовать web-браузер Google Chrome и web-приложение
Postman, которое можно загрузить из Интернет-магазина Chrome.
Для доступа к REST API требуется выполнить HTTP GET запрос, введя адрес сервера Orchestrator, порт для подключения и каталог REST API (в моем случае: "
https://ora01.company.local:8281/vco/api").
Поскольку я использую сервер Orchestrator с самоподписанными сертификатами, то REST клиент не будет подключаться к недоверенному HTTPS серверу.
Чтобы обойти это ограничение можно добавить сертификат в список исключений на компьютере, с которого производится подключение, но лучшим решением будет выдать серверу Orchestrator сертификат от доверенного удостоверяющего сервера. В тестовых целях я временно добавлю сертификат в список исключений, используя web-браузер Chrome.
Повторно выполним HTTP GET запрос. Сервер вернет ответ в формате JSON.
Мне не очень нравится JSON, при наличии возможности, я предпочитаю XML разметку. Поэтому мы можем попросить Orchestator, чтобы он предоставлял данные в формате XML.
Для этого нужно добавить заголовок в наш запрос:
Accept: application/xhtml+xmlВ производственной среде формат представления данных будет зависеть от того, какая система выполняет запросы, и какой парсер реализован у нее внутри.
Для данного REST клиента я включил сохранение заголовков, чтобы не прописывать их каждый раз заново.
Общие сведения при работе с Orchestrator REST API
REST API предоставляет доступ к иерархии Orchestrator с каталогом верхнего уровня "
/vco/api/".
Выполняя запросы к дочерним каталогам мы можем получить от Orchestrator интересующую нас информацию.
Например, добавив в адресную строку about и выполнив GET запрос, мы получим информацию о версии сервера Orchestrator и поддерживаемой версии API.
Для получения информации о всех доступных workflow требуется выполнить GET запрос:
GET https://ora01.company.local:8281/vco/api/workflows/Orchestator отказал нам в доступе, поскольку данная информация предоставляется только авторизованным пользователям.
Orchestrator поддерживает аутентификацию OAuth (при интеграции с VMware SSO), а также Basic аутентификацию.
Basic аутентификация выполняется путем добавления специального заголовка в каждый запрос:
Authorization: Basic <учетные_данные>Учетные данные пользователя (домен\логин:пароль) должны быть закодированы в формате Base64.
Для преобразования логина и пароля в формат base64 можно использовать разные инструменты, я воспользуюсь обычным онлайн
сервисом.
Выполним запрос еще раз.
После успешной аутентификации, Orchestrator выдаст список всех доступных Workflow, а их могут быть десятки и даже сотни. Чтобы сузить список выдаваемых workflow можно использовать специальный фильтр.
Для этого изменим запрос, добавив в строку адреса условие поиска, например, по имени:
?conditions=name~Get virtual machineВот с этим уже можно работать.
Для каждого Workflow отображается несколько параметров: имя (
name), краткое описание (
description), номер версии Worklow (
version). Также можно увидеть уникальный идентификатор (
id), который присваивается каждому workflow при создании, и ссылку для запроса (
down), пройдя по которой, можно получить более детальную информацию о Workflow.
Идентификатор workflow можно посмотреть через клиент Orchestrator.
Выберем тестовый workflow и выполним к нему запрос:
GET https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/Внутри каталога с workflow отображаются уже ранее виденные свойства, но что самое важно, входные параметры, которые задаются при запуске workflow (
<input-parameters>...</input-parameters>), и выходные параметры (
<output-parameters>...</output-parameters>), которые Workflow выдает в результате своей работы.
Данный workflow я взял в качестве примера, поскольку он очень простой. Его задача - принимать в качестве входного параметра (
criteria) строку с именем виртуальной машины, а качестве выходного параметра возвращать массив объектов-виртуальных машин (
Array/VC:VirtualMachine), которые подошли под указанный критерий поиска.
Помимо параметров в каталоге Workflow содержатся ссылки на дочерние каталоги, реализующие различные различные запросы.
О каталогах
executions и
presentation мы поговорим чуть позже.
В каталоге
tasks содержится информация о всех заданиях, которые запускают данный workflow по расписанию. Оттуда же можно настроить запуск новых заданий по расписанию.
icon отображает специальную иконку workflow. У всех workflow по умолчанию используется стандартная иконка, но если вы хотите визуально выделить workflow, то в настройках можете указать одну из специальных иконок, которые есть в Orchestrator.
Выполнив запрос в
schema можно увидеть рисунок схемы в формате png.
GET https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/schema/В каталоге
permissions можно видеть разрешения, которые были назначены непосредственно на данный workflow.
GET https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/permissions/Например, к workflow предоставлен доступ на просмотр и выполнение для доменной группы Domain Users.
Аналогичные разрешения (плюс унаследованные) можно увидеть из вкладки Permissions в клиенте Orchestator.
Наконец, запрос
interactions выдаст данные о workflow, которые выполняются в данный момент, и для которых требуется интерактивный ввод данных от пользователя.
Запуск Workflow
Вернемся к
executions.
GET https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/executions/Данный каталог позволяет выполнить две задачи. Во-первых, с помощью HTTP POST запроса можно запустить данный workflow. Во-вторых, здесь можно получить информацию о предыдущих попытках запуска workflow.
Идентификатор задачи (
id), дата начала (
startDate) и окончания (
endDate), имя пользователя, который запускал workflow, текущий статус задачи, ссылку на детальное описание.
Давайте посмотрим на последнюю задачу, добавив ее id в адресную строку.
GET https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/executions/402881e74db4b27c014dce08f84408a2/Здесь также можно увидеть детальные результаты работы workflow - входные значения параметров, которые ввел пользователь, и полученные результаты.
Давайте вернемся к запросу
executions.
Как уже было сказано ранее, для запуска workflow через REST API нам потребуется правильно сформировать и выполнить HTTP POST запрос.
В теле POST запроса требуется указать входные данные - те параметры и их значения, которые мы ходим передать workflow. Для данного workflow в качестве входных значений используется один параметр типа строка, в котором можно указать имя виртуальной машины или некий шаблон для поиска.
POST https://ora01.company.local:8281/vco/api/workflows/BB808080808080808080808080808080A180808001322751030482b80adf61e7c/executions/Я добавлю ранее сформированные данные в формате XML в тело запроса. В данном примере мы попробуем найти ВМ, имена которых содержат строку "
testvm01".
<execution-context xmlns="http://www.vmware.com/vco"><parameters><parameter name="criteria" type="string"><string>testvm01</string></parameter></parameters></execution-context>Откуда берутся теги для оформления XML? Самый простой вариант - посмотреть в официальной
документации.
Помимо самих данных, нам также нужно объяснить Orchestator в каком формате они предоставляются.
Для этого создадим соответствующий заголовок в запросе:
Content-Type: application/xmlОтправим запрос на исполнение.
Если все было сделано правильно, то в качестве ответа мы получим один из заголовков, который содержит ссылку (Location) на созданную нами задачу по выполнению Workflow.
Выполним запрос по указанной ссылке. Не забываем использовать для этого метод GET.
Видим, что задача завершилась успешно (
<state>completed</state>).
В качестве выходного параметра (
<output-parameters>...</output-parameters>) мы получи массив, который содержит один объект - виртуальную машину.
Проверить задачу можно через клиент Orchestrator.
Давайте рассмотрим другой workflow (
Reload virtual machine).
Для этого воспользуемся известным нам фильтром, чтобы узнать id данного workflow:
GET https://ora01.company.local:8281/vco/api/workflows?conditions=name~Reload virtual machineА затем выполним запрос, чтобы получить детальную информацию о workflow.
GET https://ora01.company.local:8281/vco/api/workflows/BD8080808080808080808080808080806BC280800122528313869552e41805bb1/Данный workflow в качестве входного параметра принимает объект типа виртуальная виртуальная машина (
vm).
Возникает вопрос - как правильно в запросе указать тип и входное значение параметра?
Для этого можно воспользоваться одной небольшой уловкой.
Из клиента Orchestrator можно запустить данный workflow на выполнение и указать какие-нибудь тестовые значений.
После чего через rest api посмотреть на выполненную задачу.
GET
https://ora01.company.local:8281/vco/api/workflows/BD8080808080808080808080808080806BC280800122528313869552e41805bb1/executions/402881e74cf6cbaf014d3f5b68bd0691/Вот искомый формат ввода данных, достаточно скопировать его, подставив свое значение в качестве идентификатора ВМ. Атрибут
href - ссылка на объект в иерархии Orchestrator, указывать не требуется, она генерируется самим Orchestrator автоматически.
Выполним POST запрос. Тело нашего запроса будет выглядить следующим образом.
<execution-context xmlns="http://www.vmware.com/vco"><parameters><parameter type="VC:VirtualMachine" name="vm" scope="local"><sdk-object type="VC:VirtualMachine" id="vc01.company.local/vm-49"/></parameter></parameters></execution-context>Адрес для запроса:
POST https://ora01.company.local:8281/vco/api/workflows/BD8080808080808080808080808080806BC280800122528313869552e41805bb1/executions/Как видите, задача успешно запущена.
Возникает вопрос - где можно взять значение ID виртуальной машины или другого объекта виртуальной инфраструктуры?
Во-первых, можно воспользоваться workflow, который мы запускали ранее (Get virtual machines by name), и который возвращает объекты виртуальных машин в качестве результата работы.
Во-вторых, Если посмотреть на вкладку Inventory в Orchestrator, то видно, что в ней отображаются объекты vCenter, в частности, виртуальные машины. При выборе одной из виртуальных машин можно увидеть ее идентификатор.
Аналогичным образом можно искать объекты в инвентаре Orchestrator через REST API. Для этого нужно выполнить цепочку GET запросов в каталоге Inventory.
GET https://ora01.company.local:8281/vco/api/inventory/Вернет перечень объектов интвентаря Orchestrator. Нас интересует объект vCenter (
VC).
GET https://ora01.company.local:8281/vco/api/inventory/VC/Вернет перечень подключенных серверов vCenter. Выполняем запрос к интересующему серверу.
GET https://ora01.company.local:8281/vco/api/inventory/VC/SdkConnection/vc01.company.local/Вернет перечень объектов, среди которых будет каталог, содержащий виртуальные ЦОД. Выполняем запрос к каталогу.
GET https://ora01.company.local:8281/vco/api/inventory/VC/SdkConnection/vc01.company.local/DatacenterFolder/vc01.company.local%252Fgroup-d1/Вернет перечень виртуальных ЦОД. Выполняем запрос к интересующему ЦОД:
GET https://ora01.company.local:8281/vco/api/inventory/VC/SdkConnection/vc01.company.local/DatacenterFolder/vc01.company.local%252Fgroup-d1/Datacenter/vc01.company.local%252Fdatacenter-28/Вернет перечень объектов виртуального ЦОД. Выполняем запрос к каталогу, содержащему ВМ.
GET https://ora01.company.local:8281/vco/api/inventory/VC/SdkConnection/vc01.company.local/DatacenterFolder/vc01.company.local%252Fgroup-d1/Datacenter/vc01.company.local%252Fdatacenter-28/VmFolder/vc01.company.local%252Fgroup-v29/Вернет перечень ВМ, которые хранятся в каталоге, а также перечень дочерних каталогов. Искомая ВМ и ее id.
Проверка входных параметров
Помимо запуска workflow, REST API предоставляет возможность проверки входных параметров на корректность с помощью Presentation. Presentation используется в следующих случаях:
- Настройка отображения входных параметров, их порядка, группировка по вкладкам и так далее.
- Контроль за значением входных параметров. Мы можем выбирать - какие параметры являются обязательными, указывать значения по-умолчанию, задавать минимальные и максимальные значения и огранивать выбор пользователя определенными значениями из списка.
Через REST API мы можем получить информацию о всех ограничениях, которые Presentation накладывает на входные параметры.
Давайте рассмотрим еще один workflows (
Rename virtual machine), который изменяет имя виртуальной машины. Чтобы получить информацию об ограничениях, которые накладывает presentation на входные параметры, выполним GET запрос.
GET https://ora01.company.local:8281/vco/api/workflows/BD808080808080808080808080808080F0C280800122528313869552e41805bb1/presentation/Для данного workflow можно увидеть, что параметры - виртуальная машина и ее новое имя является обязательным (
mandatory).
С помощью Presentation, мы можем проверить входные данные, не запуская сам workflow на выполнение.
Делается это через HTTP POST запрос в подкаталог instances:
POST https://ora01.company.local:8281/vco/api/workflows/BD808080808080808080808080808080F0C280800122528313869552e41805bb1/presentation/instances/В теле запроса укажем входные параметры, которые нуждаются в проверке.
<execution-context xmlns="http://www.vmware.com/vco"><parameters><parameter type="VC:VirtualMachine" name="vm" scope="local"><sdk-object type="VC:VirtualMachine" id="vc01.company.local/vm-49" /></parameter><parameter type="string" name="newName" scope="local"><string>testvm03</string></parameter></parameters></execution-context>Если запрос был сформирован правильно, то в ответе мы получим valid = true.
Если же при формировании запроса мы где-нибудь ошибемся, например, неправильно укажем тип параметра или передадим несуществующий объект, то в ответе будет написано, что запрос не прошел проверку (
valid = false), а также причину.
Это, пожалуй, все, что я хотел рассказать о работе с Orchestrator через REST API. Если вас заинтересовала данная тема, то настоятельно рекомендую ознакомиться с официальной документацией, доступной на
сайте VMware.
