Інтеграція зі сторонніми API
У цій статті наведено приклад створення бота, що працює з внутрішнім API Wilfire (він надсилає та отримує інформацію)
Ви можете створювати ботів, які взаємодіють з іншими ресурсами через API. Наприклад, боти можуть обробляти запити з можливістю перевірити, чи можна створити запис на певну дату, або знайти товар в інтернет-магазині.
Як обробляти стороннє API на прикладі DaData
Давайте візьмемо поради щодо API з https://dadata.ru/api/suggest/address як приклад
Уважно прочитайте документацію сторонніх API
Відкрийте свій проєкт у Salebot і відкрийте розширені налаштування в налаштуваннях блоку; там потрібно змінити тип запиту на POST-json.
У полі “URL запиту” введіть таку URL-адресу: https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/address
У полі “Заголовок запиту” введіть заголовок у JSON-форматі:
{ "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Token " + token }
У полі «JSON-параметри” вставте сам запит - { "query": "#{CurrencyType}" }
Щоб отримати результати, вам також потрібно заповнити вкладку “Збережені значення”.
Нижче наведено приклад запиту:
Як зберігати значення з змінних
Не всі розуміють це одразу, доки не спробують зробити це самі.
Спочатку введіть #{custom_answer} у полі відповіді. (Змінна #{custom_answer} містить відповідь, отриману від сервера, про який згадувалося в полі “URL для відповіді від сервера”)
Запустіть блок із запитом, щоб надіслати запит і отримати на нього відповідь. Вам потрібно проаналізувати відповідь і налаштувати доступ до змінних у ній. Для цього потрібно працювати з вкладкою “Збережені значення”.
Давайте розглянемо приклад, щоб краще зрозуміти процес.
У результаті нашого запиту #{custom_answer} надійшла відповідь у такому форматі:
{"suggestions": [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]}
Тепер запишемо в полі “Збережені значення” наш VALUE->VARIABLE
suggestions|0|value->CurrencyType;
suggestions|0|data|code->CurrencyDigCode;
suggestions|0|data|strcode->CurrencyStrCode;
suggestions|0|data|country->CurrencyCountry
suggestions - ключ масиву [{"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}]
suggestions|0 - ключ першого елемента в масиві {"value": "British pound", "unrestricted_value": "British pound", "data": {"code": "826", "strcode": "GBP", "name": "British pound", "country": "The UK"}}
suggestions|0|value - ключ до значення “British pound”
Найдовший ключ у цьому JSON:
suggestions|0|data|strcode - ключ до значення “GBP”
Ключі розділяються вертикальною рискою (|). Якщо в JSON є масив, то доступ до його елемента нумерується, починаючи з 0, і також записується через вертикальну риску.
Потрібно повторити всю вкладеність. Для зручності можна візуалізувати JSON у застосунку JSON-viewer.
Рівні вкладеності розділяються вертикальними рисками. Тож вам потрібно перелічити всі ключі, розділені рискою, щоб дістатися до значення.
Якщо в JSON є масив, то замість ключа потрібно вказати номер елемента, починаючи з 0.
Окремі фрази отримання змінних відокремлюються символом крапки з комою (;). Фрази складаються з посилання на дані у відповіді та назви змінної, у яку їх зберегти, які розділяються символами -> (тире + кутова дужка).
Пошуковий запит — це, певною мірою, шлях у JSON до потрібного значення.
Розробка API для ботів
Щоб розробити API, вам знадобиться хостинг, на якому він буде базуватися. Якщо у вас його немає або ви не сильні в програмуванні, то можете звернутися до нас, і ми розробимо API для вашого бота та розмістимо його на нашому хостингу. Сам хостинг безкоштовний, ви платитимете лише за розробку.
Але поки що трохи теорії.
Бот підтримує GET та POST запити, це основні типи, які використовуються в більшості публічних API.
GET — це запит, який відбувається під час натискання на посилання або при відкритті посилання в браузері. Параметри в такому запиті передаються в URL-запитах.
Синтаксис переданих параметрів: після URL іде знак питання (?) , потім кожен параметр відокремлюється амперсандом (&). Параметр складається з назви та його значення після знака дорівнює (=). Приклад URL з параметром:
Тут ви бачите, що передається один параметр з назвою “search_query”, а його значення — “queen live aid”. Знак ‘+’ тут означає пробіл між словами; під час роботи в редакторі ви можете просто залишати пробіли — бот сам їх замінить.
POST — це тип запиту, який найчастіше надсилається під час заповнення форми на сайті. Запит передає параметри в тілі; звісно, їх можна передавати так само, як і в GET, але так роблять рідко. Параметр у тілі може бути у JSON-форматі або як ключ-значення. У форматі ключ-значення параметри передаються у формах, а JSON-формат найчастіше використовується для API.
Заголовок запиту. Кожен запит може мати доданий заголовок/титул. Найчастіше в ньому записуються формат переданих даних і ключі доступу. Зазвичай ми залишаємо цю вкладку порожньою, але іноді потрібно вказати API Token або тип запиту “Content-type”: “application/json”.
JSON — (JavaScript Object Notation) — це відкритий стандартний формат файлів і формат обміну даними, який використовує зрозумілий людині текст для зберігання й передачі об’єктів даних, що складаються з пар атрибут–значення та масивів. Щоб працювати з API в ботах, вам потрібно знати цей формат, усе на ньому базується.
Перш ніж продовжити, прочитайте такі статті:
https://www.json.org/json-en.html https://developer.mozilla.org/en-US/docs/learn/javascript/objects/json
А також спробуйте створити власний JSON-файл на цьому сайті:
Практика
Блоки та умови можуть обробляти запити. Запити умов створюються для того, щоб зрозуміти на сайті, чи може діалог піти певним шляхом, чи ні. Запит у цьому випадку відбувається щоразу, коли перевіряється умова шляху. На відміну від цього, запити блоків запускаються лише тоді, коли відбувається перехід у блок.
Перш ніж створювати запит, потрібно вибрати його тип:
POST-data і POST-json відрізняються способом передачі параметрів, як зазначено вище (JSON-формат або як ключ-значення). Якщо ви обираєте JSON, то параметри можуть передаватися лише в запиті. Для post відкривається додаткове поле: JSON POST-параметри. Важливо! Параметри мають бути записані лише у JSON-форматі, бот працює тільки так.
Відповідь від сервера можна розібрати та зберегти у змінні.
Розібрати відповідь можна лише якщо вона у JSON-форматі.
Збережені змінні записуються в останнє незаповнене надсилання; якщо надсилання передається через червоний блок, змінні скидаються. Тож якщо вам потрібно зберегти дані, потрібно передавати змінні через жовтий блок.
До речі, ви можете подивитися, що бот записав у змінні, у розділі Leads:
Передача даних не у вигляді рядка
За замовчуванням значення змінної надходить у форматі #{} , але потім воно приходить як рядок. Щоб змінна передавалася як число, потрібно вимкнути перевірку формату параметрів post-json.
Тоді ви можете просто вказати назву змінної, наприклад {"key": #{variable_name}}, variable_name — це змінна, тобто без використання дужок.
Після налаштування параметрів рекомендується знову увімкнути перевірку.
Останнє оновлення