Запросы к API

Основная информация о запросах

Запрос — обращение от одного сервиса к другому сервису для получения или отправки информации.

Запросы можно делать к любому стороннему сервису, который их поддерживает. Если вы не можете найти документацию к API в публичном доступе, свяжитесь с поддержкой или разработчиками системы.

Ботмама умеет отправлять запросы и принимать ответы только в формате JSON. Если нужная вам система не поддерживает JSON, нужно искать сервис, который изменяет формат запроса, или писать кодом скрипт обработки на сервере. Ещё можно использовать сервисы, которые заменяют интеграцию запросами — например, Zapier.

Существует множество типов запросов, мы используем только самые распространённые: GET, POST, PUT, PATCH, DELETE.

  • GET чаще всего используется как запрос получения информации. В отдельных случаях он может использоваться равнозначно с другими типами. Например, в Telegram можно использовать и GET, и POST для одинаковых запросов.
  • POST используется для отправки информации и создания объектов. Этим методом чаще всего создаются заявки, формируются заказы и т.д.
  • PUT обновляет информацию об объекте.
  • PATCH частично обновляет информацию об объекте.
  • DELETE удаляет созданный объект.

Тело в GET запросе можно передавать в строке URL, для остальных запросов — только в специальном поле компонента.

Основная информация об ответах

Ответом на запрос может быть информация об ошибке или об удачном запросе с дополнительными данными или без них.

Об ответах на запросы можно подробно узнать в Википедии.

Чаще всего приходят ответы успеха и ошибок.

Если запрос прошёл успешно, код будет иметь значение, начинающееся на 2:

  • 200 OK — успешный запрос.
  • 201 Created — в результате успешного выполнения запроса был создан новый ресурс.
  • 202 Accepted — запрос был принят на обработку, но она не завершена.

Если запрос не прошёл из-за ошибки параметров запроса, Ботмама считает его успешным. Такие ошибки начинаются на 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

Создание URL для GET-запроса

Для примера мы будем использовать запросы к Telegram bot API.

1. Добавим токен бота в URL-запрос.

Все запросы в Telegram создаются по шаблону:

https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА

Каждому боту при создании присваивается уникальный токен вида 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Авторизация запросов к Telegram проходит по токену бота. Это значит, что срабатывать запрос будет в боте, токен которого вы указали. К примеру, отправляя запрос с текстом, вы можете указать токен другого бота, и тогда сообщение будет приходить в него.

Пока что URL будет таким:

 https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/НАЗВАНИЕ_МЕТОДА

Где вместо 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

2. Добавим метод API.

Метод API — действие, которое должна совершить система в заданном боте.

Один из самых простых методов — sendMessage. Он отправляет текст.

После вставки метода API наш шаблон выглядит так:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage

3. Добавим параметры запроса.

Параметры запроса — обязательные и дополнительные данные, которые конкретизируют, какое действие произойдёт. Например, параметры получателя или текст, который ему придет.

Обязательными параметрами являются chat_id и text:

  • chat_id — уникальный идентификатор пользователя в Telegram. Его мы получаем из переменной {{this_user.platform_id}}. Чтобы отправить сообщение определённому пользователю, нужно вставить значение его переменной. В нашем примере мы выводим значение из переменных пользователя.
  • text — текст сообщения, которое мы отправляем.

Для передачи пробелов в URL запроса нужно заменять их знаком +. Если отправить текст без замены, он оборвётся на первом пробеле.

Для запроса методом GET метод API и параметры передаются в URL запроса. Параметры от метода API отделяются знаком вопроса. Значение параметра отправляется после знака равенства. Между собой параметры отделяются знаком &.

4. Формируем шаблон GET-запроса.

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?параметр1=значение1&параметр2=значение2

Вместо параметра1 добавим chat_id, значение1 выведем из переменных {{this_user.platform_id}}.

При необходимости, в значении1 можно указать конкретное значение.

Вместо параметра2 добавим text, в значение2 напишем текст, который должен прийти в бота.

URL GET-запроса готов:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id={{this_user.platform_id}}&text=Привет+из+бота!

Настройка компонента

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запросаGET.

3. Укажите URL запроса.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

7. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

8. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

9. Тело запроса для запросов методом GET нужно оставить пустым.

10. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать авторизацию.

11. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Отправка методом POST

Создание URL для POST-запроса

Так как в POST запросе, параметры запроса и их значения составляют тело запроса, то в строке URL остаются только:

https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА

Где <token> — токен бота, где будет срабатывать запрос.</token>

Пример токена: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Название метода оставим, как в прошлом примере — sendMessage.

Получаем URL такого вида:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage

Параметры в URL, как в GET запросе, добавлять не нужно.

Для метода POST, в URL передаётся только метод API, параметры отправляются в теле запроса в формате JSON.

JSON — один из форматов данных. Он состоит из пар данных: ключ-значение. Ключ — название параметра, значение — значение параметра (может быть определенным или переменной).

Чтобы сделать тело с нашими параметрами, указываем их в формате JSON:

{
"chat_id": "{{this_user.platform_id}}",
"text": "Привет из бота!"
}
Важно следить за синтаксисом. Если вы забудете поставить хотя бы один символ, запрос не сработает. Это самая распространённая ошибка при отправке запросов.
Переносить строки можно с помощью \n, но такие символы ломают JSON. Чтобы JSON не ломался, нужно экранировать таким образом: /\n. Но так сделать не получится, если мы отправляем в переменной var текст от пользователя. В таком случае, нужно использовать хелпер escapeJsonEntities таким образом: {{escapeJsonEntities var}}.

Настройка компонента

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запросаPOST.

3. Укажите URL запроса.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

7. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

8. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

9. Тело запроса для метода POST указывается, если того требует API. Поддерживается только в формате JSON.

10. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать авторизацию.

11. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Удаление сообщения с помощью POST-запроса

Для тестирования метода POST можно попробовать удалить предыдущее сообщение методом deleteMessage.

Обязательные параметры:

  • chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
  • message_id — уникальный идентификатор сообщения, находится в переменной {{last_telegram_message_id}}.

Создадим POST-запрос deleteMessage в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запросаPOST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/deleteMessage

Где где 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

7. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

8. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

9. Добавьте Тело запроса. Поддерживается тело только в формате JSON.

{
"chat_id": "{{this_user.platform_id}}",
"message_id": "{{last_telegram_message_id}}"
}

10. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать авторизацию.

11. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

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

Отправка стикера с помощью POST-запроса

Отправим в чат стикер методом sendSticker.

Обязательные параметры:

  • chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
  • sticker — уникальный идентификатор стикера. ID стикера можно узнать, прислав стикер боту Sticker ID.

Создадим POST-запрос sendSticker в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запросаPOST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendSticker

Где 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

7. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

8. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

9. Добавьте Тело запроса. Поддерживается тело только в формате JSON.

{
"chat_id": "{{this_user.platform_id}}",
"sticker": "12345"
}

Где 12345 — ID отправляемого стикера.

10. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать авторизацию.

11. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Если все сделано верно, то при исполнении Запроса, в бот придет стикер.

Обработка ответа — объект

Для примера мы будем использовать ресурс 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}}.

Чтобы вывести переменную внутри текста, вводим её внутри фигурных скобок. Для этого делаем запрос и выводим полученный ответ в тексте.

В начало ↑

Была ли статья полезна?

Да Нет