REST Клиент#
Блок REST Клиент предназначен для выполнения HTTP-запросов.
Он поддерживает основные методы HTTP-запросов, что позволяет Пользователю взаимодействовать с API (в том числе и с RESTful API), используя:
- GET: Извлечение данных.
- POST: Отправка данных для создания нового ресурса.
- PUT: Обновление существующего ресурса.
- DELETE: Удаление ресурса.
- OPTIONS: Получение информации о поддерживаемых методах для указанного ресурса.
 | Следует учитывать, что блок Выполнить HTTP-запрос в Sherpa Designer является устаревшим (вместо него рекомендуют использовать блок REST Клиент, так как он более функциональный). Но с учетом того, что многие Пользователи все еще используют блок Выполнить HTTP-запрос, разработчики оставили его доступным для обеспечения обратной совместимости. |
Пользователи могут гибко настраивать заголовки запросов, добавлять куки, а также передавать параметры в URL. Эти возможности могут быть полезны для:
- Указания формата данных, такими как `Content-Type` или `Accept`.
- Настройки авторизации, используя заголовки типа `Authorization`, что позволяет работать с OAuth, API-ключами или базовой аутентификацией.
- Передачи дополнительных параметров в запросах, что может быть полезно для фильтрации или сортировки данных.
При использовании методов POST и PUT, REST Клиент позволяет Пользователю передавать данные в теле запроса. Он может:
- Отправлять данные в формате JSON, XML или других типах.
- Загружать файлы, позволяя интеграцию с сервисами, которые требуют передачи контента (например, изображений или документов).
Это особенно полезно для работы с API, которые принимают сложные структуры данных.
Также блок REST Клиент предоставляет возможности для:
- Настройки времени ожидания (таймаута): Пользователь может определить, как долго его запрос будет ждать ответ от сервера, прежде чем быть отмененным.
- Обработки ошибок: по умолчанию блок возвращает ошибку, если сервер отвечает статусом, отличным от успешных (2xx), но Пользователь может настроить его так, чтобы он продолжал выполнять действия в зависимости от кодов ошибок.
Для обеспечения безопасности или обхода сетевых ограничений, блок REST Клиент поддерживает использование прокси-серверов. Пользователь может настроить:
- Адрес прокси,
- Порт,
- Необходимую авторизацию для доступа к прокси.
Это полезно в случаях, когда необходимо взаимодействовать с API, который доступен только через указанные промежуточные соединения.
Пример использования: Yandex Speech API#
Предположим, что Пользователь хочет преобразовать аудиофайл формата .wav в текст, используя Yandex Speech API. С помощью блока REST Клиент это можно сделать следующим образом:
1. Настройка запроса:
URL: `https://speechiy.yandex.net/apis/speech/v1/stt:recognize\`
Метод: `POST`
Заголовки:
Authorization: Api-Key <ваш_ключ>
Content-Type: application/octet-stream
2. Передача данных: В теле запроса Пользователь загрузит аудиофайл .wav.
3. Обработка ответа: Пользователь получит текстовый результат, который можно использовать в приложении.
Пример использования REST Клиента с массивом полей типа `multipart/form-data`#
При работе с API, требующими отправки данных в формате `multipart/form-data`, важно правильно настроить клиент. Данный формат часто используется для загрузки файлов, а также для передачи данных форм.
Предположим, у Пользователя есть API, который позволяет ему загружать файлы и отправлять дополнительные текстовые данные. Для этого необходимо использовать формат `multipart/form-data`.
Для примера, допустим, что Пользователь хочет отправить изображение и описание к нему на сервер.
Пример заполнения полей блока REST Клиент:
| Поле | Пример заполнения | Комментарий |
|---|---|---|
| URL | http://www.example.com/api/upload | Ссылка на API, которое принимает загруженные файлы. |
| Тип запроса | POST | Мы отправляем данные на сервер, поэтому используем метод POST. |
| Кодировка | UTF-8 | Стандартная кодировка для Web-страниц. |
| Accept Заголовок | application/json | Укажите, какой тип ответа вы ожидаете от сервера. |
| Параметры | {"description"="Описание загружаемого файла"} | Укажите дополнительные данные, которые вы хотите отправить вместе с файлом. |
| Заголовки | {"Authorization"="Bearer YourAccessToken"} | Укажите заголовок авторизации. |
| Куки | Список куков, если это необходимо для запроса. Если сервер требует авторизацию через куки, добавьте их здесь, получив их из блока "Получить Куки". | |
| Файлы | @{"file"="C:\path\to\your\file.jpg"} | Укажите файл, который хотите загрузить. Используйте полный путь к файлу. |
| Содержание запроса | Не заполняйте это поле при использовании `multipart/form-data`, так как данные формируются автоматически. | |
| Content-Type Заголовок | multipart/form-data | Укажите тип содержимого, который соответствует отправляемым данным. |
| Время ожидания | 30 | Установите время ожидания в секундах для ответа сервера. |
| Результат | Поле будет заполнено автоматически при выполнении запроса. | |
| Код ответа | Поле будет заполнено автоматически при выполнении запроса. | |
| Заголовки ответа | Поле будет заполнено автоматически при выполнении запроса. | |
| Куки | Поле будет заполнено автоматически при выполнении запроса. | |
| Уровень обработки | Default | Выберите уровень обработки ошибок. По умолчанию ошибки будут обрабатываться. |
| Уровень сообщений | Default | Выберите уровень сообщений, который будет выводиться при выполнении блока. |
| Текст ошибки | Поле будет заполнено автоматически в случае возникновения ошибок. |
Категории ошибок#
Ошибки, которые могут возникать при работе с API, можно разделить на несколько категорий:
- Сетевая ошибка: Проблемы с сетью, такие как отсутствие соединения, таймауты, и другие сбои на уровне транспортного протокола.
- Ошибки клиента (4xx): Это ошибки, связанные с запросами, отправленными на сервер. Они указывают на то, что что-то не так с запросом или параметрами. Примеры:
`400 Bad Request`: Неверный запрос, ошибка в синтаксисе.
`401 Unauthorized`: Доступ запрещен, требуется авторизация.
`404 Not Found`: Запрашиваемый ресурс не найден.
- Ошибки сервера (5xx): Эти ошибки указывают на проблемы на стороне сервера. Примеры:
`500 Internal Server Error`: Внутренняя ошибка сервера, общая ошибка без уточнения.
`503 Service Unavailable`: Сервис временно недоступен, может быть перегружен или в обслуживании.
Обработка ошибок в REST Клиенте#
Для эффективной работы с ошибками в REST Клиенте предусмотрены несколько методов:
- Стратегия обработки: Настройка логики обработки ошибок в зависимости от статуса ответа сервера. Например:
Для кодов 4xx вы можете вывести уведомление пользователю о неверном запросе.
Для кодов 5xx можно реализовать логику повторного запроса с некоторыми задержками.
- Кастомизация сообщений об ошибках: Вы можете настраивать и выводить более понятные сообщения для пользователей, предоставляя детали об ошибке. Это важно для повышения удобства использования.
Логирование ошибок — это важная часть отладки и диагностики. Вы можете настроить резервирование ошибок, чтобы:
- Записывать ошибочные ответы в файл или базу данных для последующего анализа.
- Включить дополнительные сведения о контексте ошибки (например, URL запроса, заголовки, тело запроса) для упрощения диагностики.
В случаях, когда запрос не может быть выполнен из-за временных ошибок сети или сервера:
- Установите таймауты для запросов, чтобы они не зависали на неопределенное время.
- Реализуйте механизм повторных попыток с экспоненциальной задержкой для временных ошибок. Например, если сервер временно недоступен (код 503), имеет смысл попробовать повторить запрос через несколько секунд.
Кроме обработки ошибок в коде, полезно изучить структуру стандартных кодов ошибок, чтобы понимать, как они группируются и что они значат. Использование стандартных кодов поможет вам быстрее определить причину проблемы и устранить ее.