Комфортная работа в 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).
Важно!
Имейте ввиду, с использованием этого API Token вы не сможете через API:
- Менять пароль пользователя
- Управлять пользователями
- Создавать новые API Tokens
- Видеть и отзывать текущие API Tokens
А также, при использовании API Token, для следующих ресурсов будет иметься доступ только для чтения:
Не забудьте сохранить ваши переменные (кнопка Save). Итого ваше окружение будет выглядеть так:
Настройки коллекции
Для нашей созданной ранее коллекции мы будем настраивать следующие свойства:
Выбераем тип Bearer Token и в свойство Token вписываем переменную {{bearer}}.
Теперь любой созданный в коллекции запрос будет использовать наследуемый тип авторизации через токен.
Самая важная часть всей затеи - скрипт, который будет делать две важные вещи:
- Получать последнюю версию API (т.е. текущую для нашего инстанса VCD) и сохранять ее в глобальную переменную apiVersion.
- Получать токен доступа от 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).
Что бы использовать эту коллекцию с всеми удобствами созданных нами ранее переменных и скриптов проделаем следующее:
- Изменим тип авторизации с API Key на Bearer Token и вставим в поле Token {{bearer}}.
- В разделе Pre-request Script вставим аналогичный код
- В разделе Variables значение переменной baseUrl замените с /cloudapi на {{vcd-url}}/cloudapi для Initial и Current
После чего можно проверить новую коллекцию с помощью запроса Get base navigation links. В настройки запроса достаточно добавить только заголовок Accept с переменной {{accept-vcloud-json}}
