Комфортная работа в Postman с VMware Cloud Director

В последний раз что-то полезное на эту тему писал Tomas Fojta в, далеком уже, 2018 году. С тех пор в VCD появились новые интересные методы API и в частности в 10.3.1 появились Cloud Director API Token.

По этому я решил слегка модернизировать подход к работе с VCD API в Postman с использованием токенов.

Если вам интересно — добро пожаловать под cut.

Подход к работе с токенами/авторизацией и вообще разными инстансами VCD в Postman будет основан на использовании всей доступной в Postman функциональности Workspaces, Collections, Variables и Scripts.

Первым делом создадим для работы с VCD отдельный Workspace и дадим ему имя (например, внезапно, VMware Cloud Director).

Создадим коллекцию запросов назвав ее, ну например, VCD API.

Переменные окружения и глобальные переменные

Откроем блок глобальных переменных и создадим там следующие переменные:

apiVersion
accept-vcloud-xml: application/*+xml;version={{apiVersion}}
accept-vcloud-json: application/*+json;version={{apiVersion}}

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

Не забудьте сохранить глобальные переменные (кнопка Save).

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

В окружении «ihumster lab» (дайте своему окружению имя, позволяющее конкретно идентифицировать инстанс с котороым будет вестись работа) будет 3 переменных:

vcd-url — базовый url вашего инстанса VCD (я намеренно не указываю url вида https://vcd-fqdn/api т.к. у VCD с некоторых пор 2 API — классический XML-RPC и новый OpenAPI)

bearer — переменная типа secret, ее initial значение пустое, т.к. получать значение переменная будет в процессе работы

user_token — переменная типа secret, содержащая токен вашего пользователя, позволяющий получить bearer токен без аутентификации с логином и паролем (как получить этот токен описано в статье VMware).

Не забудьте сохранить ваши переменные (кнопка Save). Итого ваше окружение будет выглядеть так:

Настройки коллекции

Для нашей созданной ранее коллекции мы будем настраивать следующие свойства:

Authorization

Выбераем тип Bearer Token и в свойство Token вписываем переменную {{bearer}}.

Теперь любой созданный в коллекции запрос будет использовать наследуемый тип авторизации через токен.

Pre-request Script

Самая важная часть всей затеи — скрипт, который будет делать две важные вещи:

1. Получать последнюю версию API (т.е. текущую для нашего инстанса VCD) и сохранять ее в глобальную переменную apiVersion.
2. Получать токен доступа от VCD с использованием нашего user_token и сохранение его в переменную окружения bearer.

// Get last version of VCD and save it to 'apiVersion' global variable
let urlVer = pm.environment.get("vcd-url") + "/api/versions"
const urpRequest = {
    url: urlVer,
    method: 'GET',
    header: {
        'Accept': 'application/*+json',
        'Content-Type': 'application/json'
    }
}
pm.sendRequest(urpRequest, (error,repsponse) =>{
    if (error){
        console.log(error)
    } else {
        pm.globals.set('apiVersion', repsponse.json().versionInfo.last().version)
    }
})

// Get access token using env var 'user_token' and transform it to Bearer token data 
// with save to 'bearer' env var
let urlTok = pm.environment.get("vcd-url") + "/oauth/provider/token"
let body = 'grant_type=refresh_token&refresh_token=' + pm.environment.get('user_token')
const postRequest = {
  url: urlTok,
  method: 'POST',
  header: {
    'Accept': 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: {
    mode: 'raw',
    raw: body
  }
};

pm.sendRequest(postRequest, (error, response) =>{
    if (error){
        console.log(error)
    } else {
        pm.environment.set('bearer', response.json().access_token)
    }
})

Остается только проверить работу этого скрипта. Давайте попробуем получить ответ на запрос GET /api/admin/ (надо понимать что ваш user_token взят у пользователя из организации system и имеет права для запросов из раздела /api/admin/).

Создадим запрос типа GET, в url впишем конечный адрес с использованием переменной {{vcd-url}}, в разделе Headers добавим заголовок Accept с value {{accept-vcloud-json}}, и нажмем Send.

В результате ваш запрос выполнит сначала Pre-request Script (т.е. получит поддерживаемую версию API и получит access token для использования в запросе).

Использование данного подхода к OpenAPI

Залогиньтесь в провайдерскую консоль вашего VCD и откройте его API Exporer (Help-> API Exporer) и сохраните на локальный диск его Swagger файл (cloudapi.json)

Перейдите в Postman в раздел APIs и нажмте + после чего в разделе Import выберите ранее скаченный файл.

Postman покажет вам тип API (Swagger 2.0) и предложит сгенерировать новую коллекцию запросов из этого API.

Имейте ввиду, после процесса импорта окно не закрывается, а остается активным с вновь доступной кнопкой Import. Нажимать ее повторно не нужно — просто закройте окно крестиком.

В коллекциях у вас появится новая коллекция VMware Cloud Director OpenAPI с набором всех доступных методов и их описанием (документацией) — это очень удобно (требуется лишь изредка обновлять коллекцию при выходе новых версий API).

Что бы использовать эту коллекцию с всеми удобствами созданных нами ранее переменных и скриптов проделаем следующее:

1. Изменим тип авторизации с API Key на Bearer Token и вставим в поле Token {{bearer}}.
2. В разделе Pre-request Script вставим аналогичный код
3. В разделе Variables значение переменной baseUrl замените с /cloudapi на {{vcd-url}}/cloudapi для Initial и Current

После чего можно проверить новую коллекцию с помощью запроса Get base navigation links. В настройки запроса достаточно добавить только заголовок Accept с переменной {{accept-vcloud-json}}

Спасибо что дочитали до конца!