Интеграция со сторонними 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 — это открытый стандартный формат файлов и формат обмена данными, использующий человекочитаемый текст для хранения и передачи объектов данных, состоящих из пар атрибут–значение и массивов. Чтобы работать с 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 — это переменная, то есть без использования скобок.
После настройки параметров рекомендуется снова включить проверку.
Последнее обновление