Ви можете створювати ботів, які взаємодіють з іншими ресурсами через API. Наприклад, боти можуть обробляти запити з можливістю перевірки, чи можна створити запис на певну дату, або знайти товар в інтернет-магазині.
Як працювати зі стороннім API на прикладі DaData
Візьмемо API підказок з https://dadata.ru/api/suggest/address як приклад
Уважно читайте документацію сторонніх API
Відкрийте свій проєкт у Mavibot і перейдіть до розширених налаштувань блоку; там потрібно змінити тип запиту на 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"}}]}
Тепер запишемо в полі “Збережені значення” наші ЗНАЧЕННЯ->ЗМІННА
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.
Збережені змінні записуються в останнє незаповнене подання; якщо подання передається через червоний блок, змінні анулюються. Отже, якщо вам потрібно зберегти дані, потрібно передавати змінні через жовтий блок.
До речі, ви можете побачити, що бот записав у змінні, у розділі Ліди:
Передача даних не як рядок
За замовчуванням значення змінної надходить у форматі #{} але потім воно надходить як рядок. Щоб змінна передавалася як число, потрібно вимкнути перевірку формату параметрів post-json.
Тоді ви можете просто згадати назву змінної, наприклад {"key": #{variable_name}}, variable_name — це змінна, тобто без використання дужок.
Після налаштування параметрів рекомендується знову ввімкнути перевірку.