Використання Variables та Collections у Postman для тестування Salecforce endpoints

В цій статті ми поговоримо про використання 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

image
Після цього ми можемо зберегти його як нову змінну, присвоюючи Name та обираючи область доступу у Postman; обираємо Collection.
image
Після збереження наш текст зміниться на ключ змінної у подвійних фігурних дужках {{URL}}, та при наведенні курсора миші на цю змінну ми будемо бачити її поточне значення та область доступу.
image
Цим самим ми створили змінну з урлою до нашого інстансу, і за потребою ми її можемо змінювати на іншу у відповідному розділі налаштувань колекції (розповім про колекції детальніше трохи згодом).
image
Цей приклад допоможе при повторному використанні створених запит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 в відповідній секції.

image

Створюємо нову змінну opportunityID без зазначеного Initial value та зберігаємо зміни

image

Додаємо створену змінну до URL запиту

image

Натискаємо Send та отримуємо останню закриту Opportunity

image

В мене повернуло Opportunity з ID 0067Q000004qkiyQAA

Тепер ми можемо присвоїти нашій змінній opportunityID значення безпосередньо із response. Для цього достатньо виділити ID запису, натиснути праву кнопку миші та у контекстному меню у розділі Set:Global обрати opportunityID

image

Тепер коли ми перевіримо значення змінної opportunityID – то побачимо там наш ID.

image

Усі наступні виклики будуть з використанням встановленої ID запису.

Етап 2

POST запит у Endpoint вміє оновлювати існуючу Opportunity. Для оновлення запису, звісно, необхідна ID Opportunity. Як вже згадувалось раніше, Postman дозволяє використовувати змінні будь-де у конструкторі запиту, тому додаємо змінну opportunityID у Body.

image

Тиснемо Send та дивимось відповідь

image

Наш запис оновлено.

Повертаємось до GET запиту та повторно надсилаємо його, щоб перевірити оновлення дати закриття Opportunity

image

Ми бачимо, що отримана Opportunity у GET запиті оновилась. При цьому ми зробили лише просту дію присвоєння значення.

Колекції

Кажучи простими словами, колекція - це збережена група запитів (реквестів). Кожен надісланий запит в Postman можна побачити в розділі History на боковій панелі:

image

Це буде зручно, якщо ви оперуєте декількома запитами. А ось коли ви матимете сотні різних запитів, тоді пошук може ускладнюватись.

То ж, буде зручно об’єднати запити у групи для швидкого доступу.

Створення колекції

Створити колекцію можна двома шляхами:

  1. Маючи запит, зберегти його й одразу створити нову колекцію або використати існуючу для збереження

  2. Створити колекцію і, за необхідності, додавати туди запити.

Давайте детальніше розглянемо 2й варіант.
Оберіть New > Collection

image

Вкажіть назву колекції. Також, можна зробити деякі доналаштування, які будуть застосовуватись до запитів, що зберігатимуться в цій колекції. Наприклад, можна задати варіант авторизації:

image

Або вже згадані змінні для конкретно цієї колекції.

Коли колекція створена, можемо додати в неї потрібні запити.
Натисніть Save і вкажіть бажану колекцію.

image

Хочу ще додати, що в Postman є доволі багато колекцій для роботи з Salesforce. Наприклад, за цим посиланням можна знайти деякі з них.

Висновок

Найчастіше Variables використовуються для швидкого перемикання між організаціями Salesforce. Наприклад між Дев та Продакшин, як це показано у першому прикладі. Але Postman дає набагато більше функціоналу з Variables як у другому прикладі. Це дозволяє створювати більш гнучкий запит, який буде майже автоматично змінюватись перед його викликом. Якщо опанувати можливості змінних, то це суттєво може допомогти в тестуванні Endpoints у Salesforce і не тільки, а також збереже вас від сивини :slight_smile:

Колекції ж допомагають нам структуровано зберігати наші виклики для різних продуктів.

2 Likes