$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&param2=with%20params");

$http.query("https://httpbin.org/${method}?param1=${param1}&param2=${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`	Запросу устанавливается заданный заголовок `Content-Type`. Ответ обрабатывается в соответствии со значением `dataType`.	Запросу устанавливается заголовок `Content-Type`, соответствующий `dataType`. Ответ обрабатывается в соответствии со значением `dataType`.
`dataType`	Запросу устанавливается заданный заголовок `Content-Type`. Ответ обрабатывается в формате, полученном в заголовке ответа `Content-Type`.	Запросу устанавливается заголовок `Content-Type` со значением `application/json`. Ответ обрабатывается в формате, полученном в заголовке ответа `Content-Type`.

Соответствие 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`	Объект или строка	Данные, полученные в ответе. Тип зависит от установленного типа данных: Если это `json` или `xml`, в `data` содержится тело ответа, преобразованное в JavaScript-объект. Если это `text` или в ответе передан другой заголовок `Content-Type`, в `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-клиента

$http.query выполняет HTTP-запросы синхронно. Обработка запроса пользователя приостанавливается до тех пор, пока HTTP-запрос не вернет ответ.
Во время обработки одного запроса можно выполнить не более 15 вызовов $http.query. При превышении этого лимита метод возвращает ответ со статусом -1 и ошибкой Callback limit reached.

$http.query

URL запроса​

Настройки запроса​

Установка HTTP-метода​

Подстановка URL-параметров​

Отправка HTML-форм​

Отправка файлов​

Типы данных запроса и ответа​

Возвращаемое значение​

Пример использования​