API Requests
This article has not been translated yet. We will translate it shortly. For now, you can use Google Translator or automatic translator in your browser.
Основная информация о запросах
Запрос — обращение от одного сервиса к другому сервису для получения или отправки информации.
Запросы можно делать к любому стороннему сервису, который их поддерживает. Если вы не можете найти документацию к API в публичном доступе, свяжитесь с поддержкой или разработчиками системы.
Ботмама умеет отправлять запросы и принимать ответы только в формате JSON. Если нужная вам система не поддерживает JSON, нужно искать сервис, который изменяет формат запроса, или писать кодом скрипт обработки на сервере. Ещё можно использовать сервисы, которые заменяют интеграцию запросами — например, Zapier.
Существует множество типов запросов, мы используем только самые распространённые: GET, POST, PUT, DELETE.
- GET чаще всего используется как запрос получения информации. В отдельных случаях он может использоваться равнозначно с другими типами. Например, в Telegram можно использовать и GET, и POST для одинаковых запросов.
- POST используется для отправки информации и создания объектов. Этим методом чаще всего создаются заявки, формируются заказы и т.д.
- PUT обновляет информацию об объекте.
- DELETE удаляет созданный объект.
Тело в GET запросе можно передавать в строке URL, для остальных запросов — только в специальном поле компонента.
Основная информация об ответах
Ответом на запрос может быть информация об ошибке или об удачном запросе с дополнительными данными или без них.
Об ответах на запросы можно подробно узнать в Википедии.
Чаще всего приходят ответы успеха и ошибок.
Если запрос прошёл успешно, код будет иметь значение, начинающееся на 2:
- 200 OK — успешный запрос.
- 201 Created — в результате успешного выполнения запроса был создан новый ресурс.
- 202 Accepted — запрос был принят на обработку, но она не завершена.
Если запрос не прошёл из-за ошибки параметров запроса, Ботмама считает его успешным, но в объекте {{last_request}} будет лежать ошибка, начинающаяся на 4:
- 400 Bad Request — сервер обнаружил в запросе клиента синтаксическую ошибку. Этот код используется для любых ошибок такого типа, если разработчик сервиса не вложил другие значения.
- 401 Unauthorized — для доступа к запрашиваемому ресурсу требуется авторизация.
- 403 Forbidden — сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному ресурсу.
- 404 Not Found — запрашиваемый ресурс не был найдет или не существует.
Если запрос не прошёл из-за ошибки сервера (запрос упал по таймауту, сервер недоступен или тело не удалось распарсить), бот исполняет экран ошибки. В остальных случаях сработает экран успеха. Если ответ пришел валидным со статусом не 200, нужно установить компонент «Развилка» после запроса и смотреть на статус в теле. Исходя из этого направлять на нужный экран. Ошибки сервера начинаются на 5:
- 500 Internal Server Error — любая внутренняя ошибка сервера. Этот код используется, если разработчик не добавил код для описания данной ошибки.
- 501 Not Implemented — сервер не может обработать запрос. Например, вы используете несуществующий метод.
- 502 Bad Gateway — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, получает некорректный ответ от другого сервера.
- 503 Service Unavailable — сервер временно не может обрабатывать запросы. Такие ошибки возникают, когда сервер выключен, не имеет доступа к Сети или ограничен в доступе.
- 504 Gateway Timeout — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, не получает ответ от другого сервера.
Отправка методом GET и POST
Каждому боту при создании присваивается уникальный токен вида 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
Авторизация запросов к Telegram проходит по токену бота. Это значит, что срабатывать запрос будет в боте, токен которого вы указали. К примеру, отправляя запрос с текстом, вы можете указать токен другого бота, и тогда сообщение будет приходить в него.
Все запросы в Telegram создаются по шаблону:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА
Метод API — действие, которое должна совершить система в заданном боте.
Один из самых простых методов — sendMessage. Он отправляет текст.
Параметры запроса — обязательные и дополнительные данные, которые конкретизируют, какое действие произойдёт. Например, параметры получателя или текст, который ему придёт.
Обязательными параметрами являются chat_id и text:
- chat_id — уникальный идентификатор пользователя в Telegram. Его мы получаем из переменной {{this_user.platform_id}}. Чтобы отправить сообщение определённому пользователю, нужно вставить значение его переменной.
- text — текст сообщения, которое мы отправляем.
Для передачи пробелов в URL запроса нужно заменять их знаком + . Если отправить текст без замены, он оборвётся на первом пробеле.
Для запроса методом GET метод API и параметры передаются в URL запроса. Параметры от метода API отделяются знаком вопроса. Значение параметра отправляется после знака равенства. Между собой параметры отделяются знаком &
Формируем шаблон GET-запроса:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА_API?параметр1=значение1&параметр2=значение2Подставляем метод и параметры для отправки текста:
https://api.telegram.org/bot<token>/sendMessage?chat_id=значение1&text=значение2
Вставляем значения токена и параметров, чтобы получить работающий путь (URL) GET-запроса:
https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id=123456&text=Привет+из+бота!Теперь попробуем сделать тот же запрос, но методом POST.
Параметры запроса и их значения составляют тело запроса. Поэтому в строке URL мы оставляем только:
https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА
Для метода POST в URL передаётся только метод API, параметры отправляются в теле запроса в формате JSON.
JSON — один из форматов данных. Он состоит из пар данных: ключ-значение. Ключ — название параметра, значение — значение параметра (может быть определенным или переменной).
Чтобы сделать тело с нашими параметрами, указываем их в формате JSON:
{
"chat_id": "123456",
"text": "Привет из бота!"
} Важно следить за синтаксисом. Если вы забудете поставить хотя бы один символ, запрос не сработает. Это самая распространённая ошибка при отправке запросов.
Вставляем GET-запрос на экран в конструкторе:
* отмечены обязательные поля
Вставляем Post-запрос на экран в конструкторе:
* отмечены обязательные поля
Для тестирования можете попробовать удалить предыдущее сообщение методом deleteMessage.
Обязательные параметры:
- chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
- message_id — уникальный идентификатор сообщения, находится в переменной {{last_telegram_message_id}}.
Обработка ответа — объект
Для примера мы будем использовать ресурс https://www.cbr-xml-daily.ru.
В нём мы выбираем запрос в формате JSON:
https://www.cbr-xml-daily.ru/daily_json.js
Открываем его как обычную ссылку в браузере и получаем ответ в JSON-формате.
Чтобы ответ был удобным для чтения, поставьте расширение на браузер. Для Google Chrome это JSON Formatter.
Например, мы хотим получить стоимость 1 белорусского рубля. Находим часть, где выводится значение BYN и составляем переменную.
Ответ на запрос находится в объекте {{last_request}}.
Чтобы вывести переменную внутри текста, вводим её внутри фигурных скобок:
