В цій статті ми поговоримо про використання Variables та Collections у Postman та як вони можуть полегшити життя Salesforce розробнику при створенні, модифікуванні та наступному тестуванні REST API Endpoint у Salesforce. Для цього ми будемо використовувати Postman та організацію Salesforce. Як їх налаштувати можна ознайомитись у статті
Variables - змінні
Трошки теорії
Variables у Postman дають нам змогу зберігати значення та використовувати їх у різних запитах API. Ми можемо використовувати ці змінні передаючи їх колекціям, середовищам або будь-яким запитам. Postman дозволяє отримати доступ до значень не вводячи їх вручну, де б воно не було потрібно, та стільки, скільки потрібно. У прикладах ми розглянемо зберігання URL на Salesforce environment, та зберігання значення з отриманої відповіді та подальше використання у запитах.
Variables визначаються як пари key-value. Key визначає ім’я змінної, за яким ми отримуємо доступ до значення (value). У Postman змінна вказується у подвійних фігурних лапках {{name}}.
Variables мають області застосування (Variable Scopes). Є декілька областей, які дозволяють нам використовувати змінні з різними значеннями. Давайте розглянемо існуючі діапазони від найширшої до найвужчої області:
Global variables: Найширший діапазон, доступні у всій робочій області. Можна використовувати будь-де серед кількох запитів або колекцій.
Collection variables: Доступні для всіх запитів лише всередині колекції. Не змінюються в залежності від вибраного середовища.
Environment variables: Дозволяють мати різні набори значень для різних середовищ, з якими ми працюємо. Можна використовувати для налаштування групи змінних. Ці змінні матимуть різні значення залежно від середовища. Наприклад для DEV, UAT та PROD.
Data variables: Це зовнішні змінні. Визначають набір даних під час запуску колекції. Ми можемо отримувати їх лише з файлу JSON або CSV. Вони мають поточні значення, які не зберігаються після запиту.
Local variables: тимчасові змінні, доступні лише через сценарій запиту. Вони діють лише до поточного запиту. Після завершення виконання вони більше не доступні.
Global and Environment variables також поділяються на типи:
Default type: тип за замовчуванням. Змінні відображаються як простий текст без додаткових властивостей.
Secret type: змінні приховують свої значення, подібно до пароля.
Ми можемо визначати змінні кількох типів та з областями, які наведені вище. Їх можна визначити в будь-якій області конструктора запитів.
Використання змінних
Пропоную розглянути два приклади використання variables для тестування Salesforce за допомогою Postman.
Приклад 1. Використання Variables для зміни URL адреси згідно з потрібним інстансом.
Для використання Variables у Postman нам потрібно їх визначити. Для цього ми маємо виділити текст, який ми хочемо перетворити у змінну, та натиснути Set as variable
Після цього ми можемо зберегти його як нову змінну, присвоюючи Name та обираючи область доступу у Postman; обираємо Collection.
Після збереження наш текст зміниться на ключ змінної у подвійних фігурних дужках {{URL}}, та при наведенні курсора миші на цю змінну ми будемо бачити її поточне значення та область доступу.
Цим самим ми створили змінну з урлою до нашого інстансу, і за потребою ми її можемо змінювати на іншу у відповідному розділі налаштувань колекції (розповім про колекції детальніше трохи згодом).
Цей приклад допоможе при повторному використанні створених запитiв в різних організаціях без ручного модифікування URL-ів.
Приклад 2. Значення змінної можна присвоювати з response та далі використовувати в колекції. Це допоможе виконувати кілька запитів послідовно та створювати певний потік із запитів.
Для цього прикладу використовую раніше створений Endpoint:
@RestResource(urlMapping='/opportunity/*')
global with sharing class OpportunityEndpoint {
@HttpGet
global static Opportunity getOpportunityById() {
RestRequest request = RestContext.request;
String opportunityId = request.requestURI.substring(request.requestURI.lastIndexOf('/')+1);
Opportunity opportunity;
if (opportunityId.length() == 18) {
opportunity = [
SELECT Id, Name, StageName, CloseDate, Account.Name, Type, LeadSource
FROM Opportunity
WHERE Id = :opportunityId
];
} else {
opportunity = [
SELECT Id, Name, StageName, CloseDate, Account.Name, Type, LeadSource
FROM Opportunity
ORDER BY CloseDate DESC
LIMIT 1
];
}
return opportunity;
}
@HttpPost
global static String upsertOpportunity(Opportunity opportunity){
String response;
if (opportunity.Id != null && String.valueof(opportunity.Id) != '') {
update opportunity;
response = 'Updated Opportunity with ID: ' + opportunity.Id;
} else {
response = 'Wrong Opportunity ID' + opportunity.Id;
}
return response;
}
}
Етап 1
На цьому Endpoint є GET та POST запит. Розглянемо ситуацію, коли потрібно отримати дані із GET та передати їх у POST запит.
Get запит на Endpoint вміє віддавати Opportunity за ID або останню закриту Opportunity. Це залежить від того, чи передамо ми ID запису в URL.
Для цього створюємо нову Global змінну. Відкриваємо Environment quick look та тиснемо Add в відповідній секції.
Створюємо нову змінну opportunityID без зазначеного Initial value та зберігаємо зміни
Додаємо створену змінну до URL запиту
Натискаємо Send та отримуємо останню закриту Opportunity
В мене повернуло Opportunity з ID 0067Q000004qkiyQAA
Тепер ми можемо присвоїти нашій змінній opportunityID значення безпосередньо із response. Для цього достатньо виділити ID запису, натиснути праву кнопку миші та у контекстному меню у розділі Set:Global обрати opportunityID
Тепер коли ми перевіримо значення змінної opportunityID – то побачимо там наш ID.
Усі наступні виклики будуть з використанням встановленої ID запису.
Етап 2
POST запит у Endpoint вміє оновлювати існуючу Opportunity. Для оновлення запису, звісно, необхідна ID Opportunity. Як вже згадувалось раніше, Postman дозволяє використовувати змінні будь-де у конструкторі запиту, тому додаємо змінну opportunityID у Body.
Тиснемо Send та дивимось відповідь
Наш запис оновлено.
Повертаємось до GET запиту та повторно надсилаємо його, щоб перевірити оновлення дати закриття Opportunity
Ми бачимо, що отримана Opportunity у GET запиті оновилась. При цьому ми зробили лише просту дію присвоєння значення.
Колекції
Кажучи простими словами, колекція - це збережена група запитів (реквестів). Кожен надісланий запит в Postman можна побачити в розділі History на боковій панелі:
Це буде зручно, якщо ви оперуєте декількома запитами. А ось коли ви матимете сотні різних запитів, тоді пошук може ускладнюватись.
То ж, буде зручно об’єднати запити у групи для швидкого доступу.
Створення колекції
Створити колекцію можна двома шляхами:
-
Маючи запит, зберегти його й одразу створити нову колекцію або використати існуючу для збереження
-
Створити колекцію і, за необхідності, додавати туди запити.
Давайте детальніше розглянемо 2й варіант.
Оберіть New > Collection
Вкажіть назву колекції. Також, можна зробити деякі доналаштування, які будуть застосовуватись до запитів, що зберігатимуться в цій колекції. Наприклад, можна задати варіант авторизації:
Або вже згадані змінні для конкретно цієї колекції.
Коли колекція створена, можемо додати в неї потрібні запити.
Натисніть Save і вкажіть бажану колекцію.
Хочу ще додати, що в Postman є доволі багато колекцій для роботи з Salesforce. Наприклад, за цим посиланням можна знайти деякі з них.
Висновок
Найчастіше Variables використовуються для швидкого перемикання між організаціями Salesforce. Наприклад між Дев та Продакшин, як це показано у першому прикладі. Але Postman дає набагато більше функціоналу з Variables як у другому прикладі. Це дозволяє створювати більш гнучкий запит, який буде майже автоматично змінюватись перед його викликом. Якщо опанувати можливості змінних, то це суттєво може допомогти в тестуванні Endpoints у Salesforce і не тільки, а також збереже вас від сивини 
Колекції ж допомагають нам структуровано зберігати наші виклики для різних продуктів.