$http.query
Это основной метод встроенного HTTP-клиента JAICP. Он выполняет HTTP-запрос к внешнему ресурсу.
Метод принимает два аргумента: строку с URL запроса и объект с настройками.
$http.query("https://httpbin.org/get?param=${param}", {
method: "POST",
query: { param: "query param value" },
body: { key: "body key value" },
headers: {
"Content-Type": "application/json",
"Authorization": "Basic " + $secrets.get("HTTPBIN_BASIC_AUTH")
},
dataType: "json",
timeout: 10000
});
URL запроса
URL запроса может быть абсолютным и относительным.
- Абсолютный URL
- Относительный URL
Абсолютный URL начинается с протокола http:// или https:// и задает полный путь до ресурса, к которому будет отправлен запрос.
$http.query("https://httpbin.org/get");
Относительный URL задает путь до ресурса относительно базового URL. Базовый URL должен быть предварительно задан в сценарии через $http.config.
$http.config({
url: {
protocol: "https",
host: "httpbin.org",
port: 443
}
});
// ...
$http.query("/get");
Настройки запроса
| Поле | Тип | Описание |
|---|---|---|
method | Строка | HTTP-метод запроса. Возможные значения: GET (значение по умолчанию), POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, TRACE. |
query | Объект | Параметры для подстановки в URL запроса. |
body | Объект или строка | Тело запроса. |
form | Объект | Данные HTML-формы. |
fileUrl | Строка | URL отправляемого файла. |
fileName | Строка | Название отправляемого файла. |
headers | Объект | Заголовки запроса. |
dataType | Строка | Тип данных, которые содержатся в запросе и ожидаются в ответе. Возможные значения: json, text, xml. |
timeout | Число | Максимальное время выполнения запроса в миллисекундах. Предельное значение — 25000. |
cachingRequired | Логический | Нужно ли использовать кэширование, если получен успешный ответ на запрос. По умолчанию false. |
oauth2ResourceDetail | Объект | Настройки авторизации OAuth 2.0. |
Установка HTTP-метода
Чтобы задать HTTP-метод, укажите в настройках запроса поле method.
Кроме того, для наиболее часто используемых операций вы можете использовать альтернативные методы сервиса $http:
$http.get$http.post$http.put$http.delete
Сигнатура и поведение этих методов такие же, как у $http.query.
При этом они автоматически устанавливают поле method в нужное значение.
Подстановка URL-параметров
URL запроса может содержать выражения внутри последовательности символов ${}.
При выполнении запроса они будут заменены на значения соответствующих полей из объекта query.
- URL без подстановок
- URL с подстановками
$http.query("https://httpbin.org/get?param1=request¶m2=with%20params");
$http.query("https://httpbin.org/${method}?param1=${param1}¶m2=${param2}", {
query: {
method: "get",
param1: "request",
param2: "with params",
}
});
Отправка HTML-форм
Чтобы обратиться к ресурсу, который принимает запросы в формате HTML-форм,
передавайте параметры формы в поле form вместо body.
Такому запросу автоматически устанавливается заголовок Content-Type со значением application/x-www-form-urlencoded.
Поля формы соответствующим образом кодируются в теле запроса.
$http.query("https://httpbin.org/post?key=${value}", {
method: "POST",
form: {
username: "Иван Иванович",
email: "example@just-ai.com",
password: "qwerty"
}
});
Отправка файлов
$http.query позволяет отправлять файлы на внешний сервис.
Для этого укажите в настройках запроса поля fileUrl и опционально fileName.
Такому запросу автоматически устанавливается заголовок Content-Type со значением multipart/form-data.
Запрос отправляется как HTML-форма с полем file, где закодировано содержимое файла в бинарном виде.
$http.query("https://httpbin.org/post", {
method: "POST",
fileUrl: "https://example.com/image.png",
fileName: "image.png"
});
Если fileName не указан, но fileUrl содержит название файла с расширением, будет взято оно.
В противном случае именем файла будет случайный UUID.
Типы данных запроса и ответа
Чтобы указать тип данных, которые содержатся в запросе и ожидаются в ответе, используйте поле dataType.
Обратите внимание на то, как оно взаимодействует с передаваемым HTTP-заголовком Content-Type.
Content-Type | Content-Type | |
|---|---|---|
dataType |
|
|
dataType |
|
|
Соответствие dataType и Content-Type
dataType | Content-Type |
|---|---|
json | application/json |
xml | application/xml |
text | text/plain |
Возвращаемое значение
Метод возвращает объект со следующими полями:
| Поле | Тип | Описание |
|---|---|---|
isOk | Логический | true, если запрос завершился успешно и вернул код от 200 до 299, иначе false. |
status | Число | Код HTTP-ответа (например, 200 или 401). В случае ошибки внутри сервиса $http принимает значение -1. |
data | Объект или строка | Данные, полученные в ответе. Тип зависит от установленного типа данных:
|
error | Строка | Описание ошибки. Если запрос завершился успешно, этого поля нет. |
response | Объект | Полный дамп ответа. Его можно использовать для извлечения HTTP-заголовков. |
Пример использования
В следующем примере выполняется запрос к API сервиса OpenWeather, чтобы получить информацию о текущей погоде в запрашиваемом городе.
Пример предполагает, что вы получили собственный ключ к API OpenWeather и сохранили его в проекте как токен OPENWEATHER_API_KEY.
require: city/city.sc
module = sys.zb-common
theme: /
state: CurrentWeather
q!: * сколько [сейчас] градус* [в] $City *
script:
$temp.response = $http.get("https://api.openweathermap.org/data/2.5/weather?lat=${lat}&lon=${lon}&appid=${appid}&units=${units}", {
query: {
lat: $parseTree._City.lat,
lon: $parseTree._City.lon,
appid: $secrets.get("OPENWEATHER_API_KEY"),
units: "metric"
}
});
if: $temp.response.isOk
a: Сейчас в городе {{$parseTree._City.name}} {{Math.floor($temp.response.data.main.temp)}} °C.
else:
a: У меня не получилось узнать погоду. Попробуйте ещё раз.
-
$http.queryвыполняет HTTP-запросы синхронно. Обработка запроса пользователя приостанавливается до тех пор, пока HTTP-запрос не вернет ответ. -
Во время обработки одного запроса можно выполнить не более 15 вызовов
$http.query. При превышении этого лимита метод возвращает ответ со статусом-1и ошибкойCallback limit reached.