Внешние API

Нашим собеседником может быть как человек так и программа. Но что если нас тоже заменить программой?

Для того чтобы программа понимала другую программу придумали API (application programming interface). Простыми словами, API позволяют программам общаться друг с другом. В Пайп также реализована возможность взаимодействовать с другими программами и устройствами в сети через API.

API отвечают на языке JSON. Строго говоря, это даже не язык, а ответы в виде {переменная: "значение"}, где фигурные скобки определяют структуру ответа.

🐫 Чтобы видеть структуру ответа, необходимо поставить плагин JSONView plugin для Chrome или использовать онлайн-редактор JSON.

Посмотрим как это выглядит на примере курса биткоина:

Без плагина

{"high": "17234.99", "last": "16789.02", "timestamp": "1515294364", "bid": "16789.02", "vwap": "16658.97", "volume": "8288.43967678", "low": "16220.00", "ask": "16800.10", "open": "17142.43"}

С JSON View

{
high: "17234.99",
last: "16800.06",
timestamp: "1515294226",
bid: "16786.43",
vwap: "16658.85",
volume: "8315.43956887",
low: "16220.00",
ask: "16807.18",
open: "17142.43"
}

Простой запрос

Для работы с простыми ответами, не требующими авторизации и задания параметров, существует упрощенная версия запроса к API.

Давай узнаем текущий курс биткоина. Для этого нужно написать в узле следующее:

%BTCPrice=/get ask https://www.bitstamp.net/api/v2/ticker/btcusd/,

где /get — тип запроса;

ask — имя переменной из ответа, значение которой нужно получить;

URL — адрес API без параметров;

%BTCPrice — переменная, в которую нужно записать значение.

Полный запрос

Если необходимо пройти авторизацию и отправить параметры в другую программу, используется полный запрос к API. Для примера рассмотрим как работает распознавание естественного языка:

Click icon to copy this map or open it in

В узлах они обозначаются как $SYS.GET, $SYS.POST, $SYS.DELETE и $SYS.PUT.

В узле QUESTION указываются параметры запроса. В приведенном примере QUESTION содержит в переменной такие параметры: v — версия протокола; query —сообщение пользователя, которое нужно понять; sessionid — идентификатор диалога(в нем содержится (uid) для распознавания собеседника); lang — язык общения.

В узел ANSWER из JSON выбираются нужные переменные:

%answ=result.fulfilment.speech

Полный ответ можно получить, если указать переменную %raw (как показано в примере).

В JSON можно найти интересующий объект, указав по какому полю искать значение. Например получить курс нужной валюты из запроса https://bank.gov.ua/NBUStatService/v1/statdirectory/exchange?json

%answ=[cc=VND].rate

При необходимости на верхнем уровне можно добавить заголовок запроса. В примере это ключ авторизации.

⚠ Вы можете использовать синтаксис JSON path для получения нужных данных из ответа API(к примеру в ANSWER можно написать %var=$.path.to.the.object)

Если вам не нужно получать данные из ответа, вы можете использовать запросы ASYNC. Этот запрос будет выполнен как асинхронный, который не ждет ответа. Это ускорит выполнение сценария.

Click icon to copy this map or open it in