VMware Cloud Director API

VMware Cloud Director API позволяет взаимодействовать с VMware Cloud Director через REST-клиент. В этой инструкции описаны основные принципы для работы с VMware Cloud Director API. Полное описание эндпоинтов, методов и параметров запросов к VMware Cloud Director API представлено в официальной документации.

Для выполнения тестовых запросов в инструкции будут использоваться Postman и cURL.

Доступные методы VMware Cloud Director API:

  • GET — получить представление объекта;
  • POST — создать объект;
  • PUT — изменить объект;
  • DELETE — удалить объект.

Чтобы авторизоваться и начать использовать API, узнайте версию API и получите токен.

Запрос версии API

Отправьте GET-запрос на https://vcd.selectel.ru/api/versions, чтобы получить список версий API и узнать URL для авторизации.

Запрос версий API с помощью cURL

curl -X GET 'https://vcd.selectel.ru/api/versions'

Запрос версий API с помощью Postman

GET https://vcd.selectel.ru/api/versions

У актуальных версий атрибут deprecated принимает значение false, у неактуальных true. Актуальных и неактуальных версий может быть несколько.

Выберите из списка любую актуальную версию API. В данной инструкции мы используем версию 36.3 и URL https://vcd.selectel.ru/cloudapi/1.0.0/sessions/.

Получение токена

Для получения токена необходимо знать:

  • номер версии API (например, 35.0);

  • зону API:

    • МСК — https://vcd-msk.selectel.ru/api/versions;
    • СПБ — https://vcd.selectel.ru/api/versions;

  • URL для авторизации — зависит от версии API, можно посмотреть в списке версий нужной зоны для используемой версии API в поле LoginUrl;

  • tenant_name — название тенанта, можно посмотреть в URL-адресе для входа в VMware Cloud Director https://vcd.selectel.ru/tenant/<tenant_name>;

  • user — логин для входа в VMware Cloud Director;

  • password — пароль для входа в VMware Cloud Director.

Отправьте POST-запрос на полученный URL для авторизации.

Запрос токена с помощью cURL

curl -X POST 'https://vcd.selectel.ru/cloudapi/1.0.0/sessions/' -i -H 'Accept: application/*;version=36.3' -H 'Authorization: Basic credentials'

В запросе Basic — это тип авторизации, а credentials — учетные данные от VMware Cloud Director в формате user@tenant_name:password в кодировке MIME Base64. Можно использовать любой инструмент для перевода из текстового формата в MIME Base64, например, Base64-онлайн декодировщик.

Запрос токена с помощью Postman

POST https://vcd.selectel.ru/cloudapi/1.0.0/sessions/

На вкладке Authorization:

  1. В поле Type выберите Basic Auth.
  2. В поле Username укажите логин и название тенанта в формате user@tenant_name.
  3. В поле Password укажите пароль.

Для формирования заголовка Authorization через Postman не нужно отдельно переводить данные в формат MIME Base64. На вкладке Headers добавьте в поле Key значение Accept, а в поле Value введите application/*+xml;version=36.3. После получения ответа от сервера перейдите на вкладку Headers, в которой отображается список из нескольких заголовков и ключей авторизации.

Для дальнейшей работы на вкладке Authorization в поле Type выберите Bearer Token и в поле Token введите токен текущей сессии x-vmware-vcloud-access-token.

Ключ x-vcloud-authorization — это кратковременный ключ, который выдается на ограниченное время. Если сессия с этим ключом истекает, шаги по получению токена авторизации необходимо выполнить заново.

На вкладке ответа Body есть API URL ссылки для доступа к различным компонентам VDC. Рекомендуется сохранить эти данные в отдельный файл, чтоб упростить дальнейшее взаимодействие с API.

Запрос объектов организации

Отправьте GET-запрос на URL организации, чтобы получить XML-представление организации.

В нем отображаются все доступные объекты организации (виртуальные дата-центры, каталоги, задачи, квоты, группы, метадата и сети организации), а также ссылка для администрирования организации.

Запрос с помощью cURL

curl -X GET 'https://vcd.selectel.ru/api/org/ID_org' -H 'Accept: application/*;version=36.3' -H 'Authorization: Bearer token'

Где ID_org и token получены на предыдущем шаге.

Запрос с помощью Postman

GET https://vcd.selectel.ru/api/org/ID_org

ID_org получен на предыдущем шаге в ответе на вкладке Body.

На вкладке Headers добавьте в поле Key значение Accept, а в поле Value введите application/*+xml;version=36.3.

На вкладке Authorization в поле Type выбран Bearer Token и в поле Token введен токен текущей сессии.

Запрос объектов виртуального дата-центра

Отправьте GET-запрос на URL виртуального дата-центра (vDC). Вы получите ответ со списком объектов виртуального дата-центра.

Запрос с помощью cURL

curl -X GET 'https://vcd.selectel.ru/api/query?type=orgVdc' -H 'Accept: application/*;version=36.3' -H 'Authorization: Bearer token'

Где ссылка https://vcd.selectel.ru/api/query?type=orgVdс получена на предыдущем шаге и используется и token для сессии.

Запрос с помощью Postman

GET https://vcd.selectel.ru/api/query?type=orgVdc

Ссылка на vDC получена на предыдущем шаге.

На вкладке Headers добавьте в поле Key значение Accept, а в поле Value введите application/*+xml;version=36.3.

На вкладке Authorization в поле Type выбран Bearer Token и в поле Token введен токен текущей сессии.

Запрос списка VM

Отправьте GET-запрос URL https://vcd.selectel.ru/api/query?type=orgVdc из предыдущего шага, добавив параметры:

  • type=vm — показывать список всех объектов типа VM;
  • fields=name,containerName — для каждой VM показывать только атрибуты name и containerName (и по умолчанию атрибуты href);
  • filter=isVAppTemplate==false — показывать только развернутые VM, а шаблоны vApp отфильтровывать.

Запрос списка VM с помощью cURL

curl -X GET 'https://vcd.selectel.ru/api/query?type=vm&fields=name,containerName&filter=isVAppTemplate==false' -H 'Accept: application/*;version=36.3' -H 'Authorization: Bearer token'

Запрос списка VM с помощью Postman

GET https://vcd.selectel.ru/api/query?type=vm&fields=name,containerName&filter=isVAppTemplate==false

Включение/выключение VM

Список URL VM получен на предыдущем шаге. Чтобы запустить включение/выключение VM, отправьте POST-запрос на нужную ссылку:

  • https://vcd.selectel.ru/api/vApp/vm-VM_id/power/action/powerOn — VM будет включена;
  • https://vcd.selectel.ru/api/vApp/vm-VM_id/power/action/powerOff — VM будет выключена.

Выключение VM с помощью cURL

curl -X POST 'https://vcd.selectel.ru/api/vApp/vm-VM_id/power/action/powerOff' -H 'Accept: application/*;version=35.0' -H 'Authorization: Bearer token'

Выключение VM с помощью Postman

POST https://vcd.selectel.ru/api/vApp/vm-VM_id/power/action/powerOff

Выход из сессии

После завершения работы удалите сессию DELETE-запросом.

Выход с помощью cURL

curl -X DELETE 'https://vcd.selectel.ru/cloudapi/1.0.0/sessions/' -i -H 'Accept: application/*;version=36.3' -H 'Authorization: Bearer token'

Выход с помощью Postman

DELETE https://vcd.selectel.ru/cloudapi/1.0.0/sessions/