Object Builder (full version)

Що таке Object Builder

Блок Object Builder є універсальним блоком для формування, зміни або структурування даних усередині флоу, наприклад, перед відправкою запиту в API чи перед передачею в наступний блок. Він дозволить вам представляти формати запиту в різних структурах, в залежності від того як того потребує документація API системи з якою ви плануєте розробити інтеграцію. Також за допомогою Object Builder можна підготувати вихідні дані перед передачею в Output, об’єднати кілька попередніх результатів у єдину структуру, і ще динамічно створювати списки об’єктів.

Коли використовувати Object Builder?

• Сформувати тіло JSON-запиту перед HTTP Request
• Змінити або відфільтрувати дані після API-відповіді
• Зібрати масив зі значень всередині Loop
• Об’єднати результати кількох блоків в один об’єкт
• Провести умовну трансформацію даних (додати ключ тільки якщо значення не порожнє, змінити поле при виконанні умови)
• Видалення зайвих полів

Навігація:

1. Розташування блоку Object Builder?
2. Де відбувається налаштування Object Builder?
   
3. Для чого поле "Save Result To" або як ще можна створити Глобальну змінну?
4. Методи роботи з об'єктом в межах одного блоку Object Builder?
   New Empty Object
   Copy Object From
   Edit Existing Object
5. Дії які можна виконувати для формування структури запиту та як кожна з них працює?
   Set property
   Set property if
   Set property Object
   Set property Object From Json
   Add Value from start
   Add Object from start
   Add Value at end
   Add Value at end if
   Add Object at end
   Remove Key
   Remove Key if
   Remove First
   Remove Last
6. Як в запиті виконувати програмне виконання (EXP) для застосування операторів та функцій?

Додаткові конфігурації

• Як змінити назву блоку
• Розділ Note
• Розділ Test

FAQ — часті питання

1. Як швидко створити об'єкт і передати його в HTTP Request

Розташування блоку Object Builder?

─────────────────────────────────────────────────────────────-

Блок Object Builder можна знайти в таких флоу:
Input, Main Action, Output, Account Validation, Request Error, Custom.
Найчастіше блок Object Builder необхідний в цих флоу Input та Main Action, тому як, саме там відбувається найголовніша частина роботи по його застосуванню.

Для того щоб додати новий блок, натисніть на + та оберіть Object Builder.

Розташування Object Builder в флоу Main Action

Де відбувається налаштування Object Builder?

─────────────────────────────────────────────────────────────-

Settings

В розділі Settings відбувається головна частина налаштувань по формуванню та представленню даних для запиту в різних форматах.

Тут можна обрати що треба буде зробити з об'єктом, яку дію можна застосувати для формування структури запиту та в якій змінній буде збережений результат.

Вибір метода роботи з об'єктом

Вибір дії

Збереження результату у змінну

Для збереження внесених змін треба натиснути Save.

Для чого поле "Save Result To" або як ще можна створити Глобальну змінну?

─────────────────────────────────────────────────────────────-

Поле "Save Result To" визначає, куди буде збережено результат виконання блока.
Результат записується в глобальне сховище змінних VARS, що дозволяє використовувати його в наступних блоках потоку, це один з механізмів передачі даних між блоками.

{{VARS}}['my_variable'] - правильний синтаксис

• {{VARS}} — глобальне сховище (вибирається у списку змінних).

• 'my_variable' — назва ключа, за яким буде збережено результат.

{{VARS}} не потрібно прописувати вручну, її необхідно обрати у списку Глобальної змінної , Globals - VARS

В результаті на Тесті ви побачите який це має вигляд

Методи роботи з об'єктом в межах одного блоку Object Builder

─────────────────────────────────────────────────────────────-

Вибір цього параметру визначає початкову точку створення або модифікації даних у поточному блоці.
Від цього залежить, чи почнеться побудова структури «з нуля», чи використовуватиметься вже наявний об’єкт із попередніх кроків. 

Об'єкт можна створити новий, скопіювати та редагувати існуючий - New Empty Object, Copy Object From, Edit Existing Object.


New Empty Object - буде створений новий об'єкт. Усі властивості, які ви задаєте далі (через дії Set Property, Add Value at End тощо), будуть додані до цього нового об’єкта, який надалі можна використовувати в інших блоках для виконання операцій.

Цей результат ви можете використовувати в наступних блоках, просто вказавши Result з цього блоку.


Copy Object From - створює копію вже існуючого об’єкта (зазвичай отриманого з попереднього блоку або змінної), після чого над копією можна виконувати модифікації, не змінюючи оригінал.
Це забезпечує безпечну роботу, коли потрібно перетворити дані, але зберегти початковий результат.
У полі Value необхідно обрати існуючий об'єкт для його копіювання. 

В даному прикладі ми скопіюємо Результат Виконання попереднього блоку і внесемо в скопійований об'єкт зміну. Оригінальний блок з результатом при цьому залишиться без змін.

Застосуємо дію Remove Key і збережемо в окрему змінну "copy_builder". (можна застосувати будь-яку дію, це лише приклад)

На етапі Тест можна побачити Результат Виконання цього блоку. 

Тепер збережену змінну можна використовувати в наступних блоках.

Глобальні змінні розташовані тут > Globals - VARS.


Edit Existing Object - редагує той самий об’єкт, який вже збережено у змінній чи отримано з попереднього блоку. Зміни вносяться безпосередньо в існуючу структуру, тому результат використання цього параметру змінює оригінал.  У полі Value необхідно обрати інший існуючий об'єкт/змінну, для внесення в нього змін.

В даному прикладі ми оберемо змінну яку зберегли до цього в попередньому блоці, таким чином в цьому об'єкті ми внесемо зміни в цю змінну.

Застосуємо дію Set property Object щоб додати інший об'єкт як значення властивості.

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

Тепер цю змінну можна далі використовувати в наступних блоках.

Дії які можна виконувати для формування структури запиту та як кожна з них працює?

─────────────────────────────────────────────────────────────-


Set property - Створює або змінює властивість (Key-Value) в об’єкті. Якщо ключ існує — перезаписує його значення.

Дозволяє сформувати об'єкт із властивостями і отримати такий тип даних:

object

{ "full_name": "Piter Simonson", "email": "[email protected]" }

В даному прикладі ми створюємо властивість в об'єкті з двома ключами і в полях Value вставляємо змінні з Глобального INPUT, знаходиться тут > Globals - INPUT. При призначенні змінних, можна побачити що в них міститься, при умові що вони були заповнені в Flow Test.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP формат буде такий як на скріншоті.


Set property if - Створює або змінює властивість (Key-Value) в об’єкті тільки якщо виконується певна умова (наприклад, поле не пусте або дорівнює певному значенню).

Робить те саме що і попередня дія, але при виконанні певної умови. Дозволяє сформувати об'єкт із властивостями якщо умова виконана і отримати такий тип даних:

object

{ "full_name": "Piter Simonson", "email": "[email protected]" }

В даному прикладі ми використовуємо дві умови. Перша умова перевіряє чи не пусте значення у вказаній змінній "!EMPTY()", яку ввів користувач з INPUT, друга умова перевіряє чи вказане значення є масивом "IS_ARRAY()".
Від вказаних умов залежить Результат Виконання.
В даному випадку у нас перша умова виконалась так як значення в змінній не пусте, друга умова ні, так як не є масивом.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP формат буде такий як на скріншоті.


Set property Object - Додає до поточного об’єкта інший об’єкт як значення властивості. Використовується для вкладених структур.

Дозволяє сформувати об'єкт як значення властивості іншого об'єкта і отримати такий тип даних:

object

{"customProperties":{"key":"field_string","value":"test100"}}

Створюємо об’єкт customProperties, всередині якого міститься вкладений об’єкт із полями key та value. Значення полів це змінні з Input які користувач буде вводити.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP формат буде такий як на скріншоті.


Set property Object From Json - Створює властивість, значення якої — об’єкт, розпарсений із JSON-рядка. Може бути корисно, коли API повертає JSON як текст, або з попереднього блоку прийшов JSON у вигляді тексту, який потрібно розпарсити. 

Встановлює властивість, розпарсивши JSON-рядок у JSON-об’єкт, можна отримати такий тип даних:

object

Припустимо API повернув JSON-рядок. Дана дія перетворює його у JSON-об’єкт і додає як значення властивості. 

Приклад відповіді яку отримали від API

У полі Key вказуємо ключ, в який буде записано об'єкт після парсингу JSON-рядка.
У полі Value обираємо JSON-рядок із попереднього блоку HTTP, який потрібно перетворити в об’єкт.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Add Value from start - Додає значення на початок масиву в поточному об’єкті. Якщо масиву не було - створює новий масив. Використовується для формування списків від найновішого до найстарішого, підготовка масивів для API, які очікують значення у певному порядку або форматі. 

Формує масив зі значень, отримуємо такий тип:

array

["[email protected]","[email protected]"]

Припустимо у нас є множинне поле для збору email, за допомогою цикла "Loop: Object/List" ми переберемо кожне значення і сформуємо масив.

Перебираємо значення циклом

Тепер формуємо масив, в полі Value ми обираємо значення з циклового блоку, в даному випадку ми бачимо останнє значення.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Add Object from start -  Додає об’єкт на початок масиву в поточному об’єкті.

Формує масив всередині якого знаходяться об'єкти, отримуємо такий тип даних:

array

[{"full_name":"Piter Simonson","email":"[email protected]","phone":"15749999999"}]

В даному прикладі додаємо об'єкт на початок масиву, використовуючи змінні з Input які буде вводити користувач.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Add Value at end - Додає значення в кінець масиву. Якщо масиву не було - створює новий масив. Використовується для формування списків від найстарішого до найновішого, підготовка масивів для API, які очікують значення у певному порядку або форматі.

Формує масив зі значень, отримуємо такий тип:

array

["[email protected]","[email protected]"]

Припустимо у нас є множинне поле для збору email, за допомогою цикла "Loop: Object/List" ми переберемо кожне значення і сформуємо масив.

Перебираємо значення циклом

Тепер формуємо масив, в полі Value ми обираємо значення з циклового блоку, в даному випадку ми бачимо останнє значення.  

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Add Value at end if - Додає значення в кінець масиву лише якщо умова виконується (наприклад, поле не пусте або дорівнює певному значенню).

Робить те саме що і попередня дія, але при виконанні певної умови. Дозволяє сформувати масив зі значень якщо умова виконана і отримати такий тип даних:

array

["[email protected]","[email protected]"]

Як і в попередньому прикладі, ми циклом перебираємо значення множинного поля, і при умові що значення не пусте, буде сформований масив. Якщо значення поля буде порожнє, то в результаті ви отримаєте пустий масив.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Add Object at end - Додає об’єкт у кінець масиву в поточному об’єкті.

Формує масив всередині якого знаходять об'єкти, отримуємо такий тип даних:

array

[{"full_name":"Piter Simonson","email":"[email protected]","phone":"15749999999"}]

В даному прикладі формуємо масив в якому є об'єкти, використовуючи змінні з Input які буде вводити користувач.

В розділі Test ви побачите Результат Виконання блоку.

При відправці запиту HTTP, або при передачі в подальші блоки, формат буде такий як на скріншоті.


Remove Key - Видаляє властивість з об’єкта за його ключем.

Було

Застосовуємо дію редагуючи існуючий об'єкт з попереднього блоку. 

Результат


Remove Key if - Видаляє властивість з об'єкта за його ключем, якщо виконується певна умова (наприклад, поле не пусте або дорівнює певному значенню). 

Було

Застосували дію редагуючи існуючий об'єкт. В даному випадку використали 2 умови , якщо значення першого ключа порожнє EMPTY(), то лише в цьому випадку видаляємо його із об'єкта, друга умова, якщо значення другого ключа не порожнє !EMPTY(), то лише в цьому випадку видалимо його з об'єкта. При цьому в даний момент значення всіх ключів заповнене.

Результат


Remove First - Видаляє перший елемент масиву.

Було, масив мав такий вигляд.

Застосували дію, редагуючи цей самий об'єкт

Результат. Перший елемент відсутній


Remove Last - Видаляє останній елемент масиву.

Було, масив мав такий вигляд.

Застосували дію, редагуючи цей самий об'єкт

Результат. Останній елемент відсутній

Як в запиті виконувати програмне виконання (EXP) для застосування операторів та функцій?

─────────────────────────────────────────────────────────────-

Майже в кожному блоці, в полях, можна обрати один із двох режимів виконання:

TXT (Text Mode) — текстовий режим
EXP (Expression Mode) — режим виразів (expression)

Ці режими визначають, як саме система обробить значення поля: як звичайний текст чи як програмний вираз з логікою, функціями і обчисленнями.

У режимі EXP з’являється панель операторів і функцій. Це дозволяє писати складні вирази прямо в полі.

Будь що, що ви передасте в режимі TXT буде оформлено як текст. Якщо ви передасте в режимі TXT якийсь вираз/умову/функцію , то система не буде це рахувати, вона просто передасть те що ви вписали у вигляді тексту.

Якщо ви захочете передати номер телефону як числове значення, застосувавши функцію TO_NUMBER() але залишаєте режим TXT, то результат буде просто текст, як в прикладі.

Для отримання бажаного результату і передачі номеру телефону в числовому форматі, переведіть режим поля в режим EXP

Режим EXP дозволяє: 

• виконувати логічні операції (>, <, ==, !=, &&, ||)

• виконувати арифметику (+, -, *, /)

• працювати з текстом (кодування, зміна регістру, пошук і заміна , тощо)

• працювати з числовими значеннями

• працювати з датами

• працювати з масивами

• перевіряти умови

• використовувати загальні функції (EMPTY, ISSET, TO_BOOL, TO_NUMBER і інші)

У режимі EXP поле працює як програмний код, а не як текст.

Одне єдине правило і відмінність цих двох режимів:

TXT — передає будь яке значення як текст. EXP — виконує значення як програмний вираз із логікою, функціями, обчисленнями та умовами.

Додаткові конфігурації

─────────────────────────────────────────────────────────────-

Як змінити назву блоку

Натисніть на олівець біля назви для редагування назви - впишіть нову і натисніть Save.

Розділ Note

В розділі Note можна додати текст з описом що буде робити цей блок, або якимось чином позначити важливу інформацію яка відноситься до того що саме відбудеться в ньому.

Після того як ви збережете зміни, частина цієї інформації буде відображатись всередині блоку.

Розділ Test

В розділі Test розташована інформація про Результат Виконання всього блоку, тобто те що ви налаштовували в розділі Settings.

Тут можна побачити Результат Виконання в межах цього блоку, тобто як саме була сформована структура даних.

У випадку, якщо ви використовували редагування або копіювання об'єкта, або зберігали Результат Виконання у якусь змінну, то нижче можна побачити як це виглядає на Глобальному рівні і де саме розташована ця змінна.

FAQ

─────────────────────────────────────────────────────────────-

1. Як швидко створити об'єкт і передати його в HTTP Request

Натисніть на + і додайте блок Object Builder - додайте 2 дії Set Ptoperty для кожного поля для формування властивостей об'єкта, вкажіть ключі і оберіть змінні з Input - у полі "Save Result To" збережіть у Глобальну змінну

Додайте блок HTTP Request - вкажіть ваш URL, метод і Parse Body(JSON) 

На вкладці Body оберіть тип "Raw json data" -  в Raw Body оберіть цю змінну Globals - VARS['request']

Додатково треба буде обрати функцію у вбудованому декораторі, натисніть біля змінної на f:0 - Functions - Text Functions - Encode object as JSON, після цього натисніть Save як на картинці

Коли побачите f:1 біля змінної, значить функція була застосована.

Тепер можете відправити запит і побачити структуру.

На цьому все, ви відправили запит з очікуваним форматом JSON в АПІ.