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), имеет смысл попробовать повторить запрос через несколько секунд.
Кроме обработки ошибок в коде, полезно изучить структуру стандартных кодов ошибок, чтобы понимать, как они группируются и что они значат. Использование стандартных кодов поможет вам быстрее определить причину проблемы и устранить ее.
Last updated
