api
Описание
Выполняет запрос к внешним API.
Синтаксис
api [<connection>] [<query>] [<url>] [<method>] [<verify>] [<ssl>] [<ssl_type>] [<cert>] [<auth>] [<auth_type>] [<params>] [<headers>] [<timeout>] [<body>] [<body_type>]
Опциональные аргументы
| Параметр | Синтаксис | Описание |
|---|---|---|
connection | connection=<string> | Название заранее определенного api подключения. |
query | query=<string> | Название заранее определенного api запроса. |
url | url=<string> | См. Обработка url. |
method | <string> | Метод HTTP запроса, по умолчанию GET. |
verify | verify=<boolean> | При значении true осуществляется верификация имени хоста. |
ssl | ssl=<boolean> | При значении true осуществляется валидация ssl. |
ssl_type | ssl_type=<string> | Тип ssl протокола. Может принимать значения ssl2.3, ssl3, tls, tls1.1, tls1.2, tls1.3. |
cert | cert=<string> | Путь до сертификата при использовании ssl. |
auth | auth=<string> | Токен авторизации. |
auth_type | auth_type=<string> | Тип авторизации. Может принимать значения basic, apiKey, bearer. |
params | params=<string> | Параметры запроса. |
headers | headers=<string> | Хедеры запроса. |
timeout | timeout=<int> | Таймаут запроса. |
body | body=<string> | Body запроса. |
body_type | body_type=<string> | Тип body. Может принимать значения json, xml, javascript, html, text, binary. |
Для работы команды обязательно должен быть определен url, или в подключении, или как аргумент url.
При использовании api подключения или запроса и опциональных параметров, опциональные параметры имеют высший приоритет.
Обработка URL
При формировании итогового URL происходит обработка URL из аргументов connection и query.
Если query содержит полный URL, он используется без изменений. Если URL относительный, из connection берется только значение хоста, и к нему добавляется путь из query.
Если задан аргумент url, его значение заменяет URL из query и обрабатывается по тем же правилам: полный URL используется как есть, а относительный путь объединяется с хостом из connection.
Токенизация params и headers
При использовании аргументов params и headers можно использовать токены из keystore.
Токены для headers должны храниться в keystore по пути sme.sa.api.header.<token_name>, токены для params по пути sme.sa.api.param.<token_name> соответственно. Вместо <token_name> необходимо указать название токена, например my_authorization.
Создание токена
Для создания токена с типом header и названием my_authorization необходимо выполнить запрос к keystore. В значении поля value нужно указать значение, которое будет подставляться вместо токена в запросе.
POST _core/keystore/sme.sa.api.header.my_authorization
{
"value": "Basic "
}
Использование токена
Для использования токена команды api в поисковом запросе, его название необходимо указать в двойных фигурных скобках.
| api connection=my-connection headers="Authorization={{my_authorization}}"
Примеры запросов
Пример 1
Запрашивает указанный в параметре url api и возвращает документы, содержащие информацию о пользователях.
| api url="https://jsonplaceholder.typicode.com/users"
Пример 2
В соединении json указан базовый URL https://jsonplaceholder.typicode.com/, к нему добавляется путь до ресурса из параметра url.
| api connection=json url="/todos"
Пример 3
Выполняет запрос с использованием заранее определенных api подключения и запроса.
| api connection=my-connection query=my-query
Пример 4
Выполняет запрос с использованием заранее определенных api подключения и запроса, но с отключенной валидацией ssl.
| api connection=my-connection query=my-query ssl=false