Работа с API Модулями

В данном руководстве мы рассмотрим процесс подключения «API Модуля» и настройки его работы - на примере бесплатного  Демо Модуля «Number Convert (ДЕМО)».

В общем виде НАСТРОЙКА взаимодействия по API состоит ИЗ ДВУХ СТАДИЙ:
1. Подключение соответствующего API Модуля к вашему боту.
2. Настройка Action-а на взаимодействие с API Внешнего Сервиса.

В общем виде РАБОТА настроенного соединения выглядит так:
Когда Юзер нажимает настроенную вами кнопку - Action отправляет созданный вами Запрос с указанными Параметрами и API Модуль начинает ожидать ответ от Внешнего API (обычно несколько миллисекунд). После получения ответа - данные из ответа API ассоциируются со спец. макросами Action-а, после чего они становятся доступны в цепочке Action-ов текущей кнопки. Дальше с ними можно работать - как с любыми другими данными (выводить в сообщениях, сохранять в переменных и т.д.).

❖ Подключение API Модуля

Поскольку в будущем, в системе планируется добавить довольно большое количество API Модулей, а для каждого отдельного бота будет необходимо всего несколько из них (чтобы не загромождать интерфейс), было принято решение вынести список API Модулей в отдельный раздел и дать возможность подключать их по отдельности при необходимости.

Перейти в раздел Модулей

Для подключения API Модуля перейдите в вашем боте:
☞ 🔐Админ | 🗜API Модули | ➕Доб.API Модуль

Выбрать API Модуль

Для целей данного руководства выберите Модуль «Number Convert (ДЕМО)».

Это бесплатный демонстрационный модуль, дальнейшая настройка будет происходить на его примере.

Ключ API

Введите ключ API для выбранной системы.

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

В данном случае ключ можно получить в этом же меню - см. далее.

Запросить Ключ API

Запросите автоматическую генерацию ключа для Демо и Интегрированных сервисов.

Данная функция позволит вам получить ключ API для тех сервисов которые либо являются демонстрационными для конструктора @MenuBuilderBot, либо глубоко интегрированными в его функционал. В этом случае генерация ключа происходит по месту - прямо в настройках и вводить его вручную - не надо.

Проверить и Активировать Модуль

Активируйте Модуль.

После того как Вы получили скопировали и сохранили ключ, вам необходимо указать системе на необходимость проверки указанного вами ключа - система активирует модуль автоматически, если проверка будет пройдена успешно.

Название

Укажите своё название Модуля (НЕ ОБЯЗАТЕЛЬНО).

Опция позволяет вам указать своё собственное (возможно короткое) название для подключённого вами модуля. Это название вы будете видеть в меню при дальнейших настройках работы API.

Если название не задано, в качестве идентификатора в названии кнопки Модуля, при выборе, появится Ключ API - из-за чего кнопка может выглядеть не презентабельно.

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

На этом активация API Модуля завершена. Далее мы будем настраивать его работу в сценарии Меню бота.

❖  Создаём Форму ввода числа

Создание формы ввода переменной, происходит ИСКЛЮЧИТЕЛЬНО ДЛЯ ЦЕЛЕЙ ДАННОГО РУКОВОДСТВА и необходимо для наилучшей демонстрации интеграции функционала API Модулей в функционал и сценарии вашего бота - создавайте Форму, только если вы изучаете возможности работы с API при помощи последовательности указанных тут шагов.

Рассматриваемый нами Модуль («Number Convert (ДЕМО)») принимает заданное юзером число и конвертирует цифры его шрифта в числа другого Unicode шрифта (в кружочки, если конкретнее). Таким образом нам понадобится переменная в которую мы сохраним пользовательский ввод, а затем, при помощи экшена, передадим её значение API для конвертации.

Создаём переменную

Создайте Числовую переменную - «num».

О том как добавить переменную смотри в «Руководстве по Переменным».

Создаём Форму ввода Переменной

Добавьте в меню Форму с вводом созданной вами ранее Переменной («num»).

О том как добавить Форму ввода Переменной смотри в «Руководстве по Формам».

❖ Настройка Action-а API Модулей

После того как нужный API Модуль активирован в вашем боте, необходимо настроить его непосредственное взаимодействие с API в сценарии меню. Настройка взаимодействия происходит в при помощи специального «Action-а API Модулей», который вы добавляете в ту кнопку меню, по нажатию которой хотите чтобы происходило взаимодействие с внешним API.

О том как добавлять и настраивать Action-ы смотри в «Руководстве по Action-ам».

Добавляем Action API Модулей

Добавьте Action в нужную вам кнопку меню, в нужном месте цепочки Action-ов.

Для целей данного руководства нам понадобится «Post-Action» - потому как он должен сработать после того как юзер ведёт нужно ему число в переменную «num» - то есть после созданной нами ранее Формы. Понятно что в общем случае ТИП Action-а вы выбираете в соответствии с вашей необходимостью.

Настройка Action-а происходит при помощи пошагового Мастера (Wizard).

1. Выбираем Модуль

Выбираем созданный нами ранее Модуль («Number Convert (ДЕМО)»).

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

В рамках этого руководства у нас активирован только один модуль («Number Convert (ДЕМО)»). Все параметры для настройки этого Модуля указаны В КАЧЕСТВЕ ЖИВЫХ ПРИМЕРОВ в самих сообщениях Мастера Настроек Action-а. - можете брать их оттуда.

2. Указываем Конечные Точки API

ДАННЫЕ ПО API: Все данные по каждому конкретному API нужно смотреть в его документации. Документация по Модулю «Number Convert (ДЕМО)» находится по адресу: https://api.menubuilder.cc/number_convert/docs.

Для нашего модуля Конечные Точки (Endpoints) это requests/convert.
Метод запроса - GET.

«Базовый URL», а так же «Ключ API» и «ID Бота» - будут подставлены Модулем автоматически - вам не нужно о них заботиться.
Подробнее о структуре URL запроса API - смотри в руководстве «Что такое API и как он работает».

3. Ассоциируем данные ЗАПРОСА

ЗАПРОС - это когда ваш бот отправляет данные Внешнему API на обработку.

На этом шаге мы выбираем какие данные мы будем отправлять API.
- Данные ассоциируются при помощи знака присвоения "=" (равно).
- Названия Параметров берутся из документации по API.
- Первым идёт Параметр API и ему присваивается Значение.
- Значение можно брать, как из Переменной, так и напрямую указывать в виде Текста или Числа.
- Параметры из Макроса указываются как все макросы бота - со знаками процента ("%"), текст и числа - без доп знаков.
- Каждый Параметр должен быть размещён на отдельной строке.
- Каждому указанному Параметру должно быть присвоено Значение.
Например:
api_param1=%your_macros% - параметр и макрос переменной
api_param2=your text - параметр и обычный текст
api_param3=123 - параметр и число.

В рамках нашего примера мы сохранили введённые пользователем число в переменной «num». Эти данные мы и будем передавать по API. Для этого в документации нашего API (https://api.menubuilder.cc/number_convert/docs) есть параметр «number» - который специально предназначен для того чтобы передавать число которое необходимо сконвертировать.

Ассоциируем Параметр («number») из документации API, с созданной нами переменной («num») в которой мы ранее сохранили данные Формы.
number=%num%
Обратите внимание что Параметр «number» идёт первым и указывается без знаков процента, а переменная указывается в виде её макроса - со знаками процента ("%").

4. Ассоциируем данные ОТВЕТА

ОТВЕТ - это когда Внешний API, после обработки, отвечает на ваш предыдущий Запрос.

На этом шаге мы выбираем какие данные из ответа API мы хотим передать в бот.
- Данные ассоциируются при помощи знака присвоения "=" (равно).
- Внутренние Макросы вы назначаете САМИ.
- Первым идёт название Внутреннего Макроса и ему присваивается значение Параметра API.
- Названия Параметров в ответе берутся из документации по API.
- Параметры ответа указываются - со знаками процента ("%").
- Значения Внутренних Макросов доступны только в текущей цепочке Action-ов (больше НИГДЕ).
- Одному Внутреннему Макросу можно присваивать сразу несколько значений Параметров API.
- Каждый Внутренний Макрос должен быть размещён на отдельной строке.
- Каждому указанному Внутреннему Макросу должно быть присвоено Значение.
Например:
your_macros1=%api_param1% - макрос и один параметр
your_macros2=%api_param2% %api_param3% - макрос и несколько параметров
your_macros3=%api_param4.api_param1% - макрос и доступ к СУБ-параметру Объекта (словаря)
your_macros4=%api_array[0].api_param1% - макрос и доступ к СУБ-параметру Массива.

Подробнее о синтаксисе доступа к Свойствам (Properties) JSON - смотри ниже.

В рамках нашего примера, в качестве ответа API, мы получаем сконвертированное число (число другим шрифтом). Эти данные мы и будем передавать во Внутренний Макрос. В соответствии с документацией нашего API (https://api.menubuilder.cc/number_convert/docs) ответ приходит в параметре «result» JSON файла.

Ассоциируем созданный нами Внутренний Макрос («response») с параметром («results») ответа API из документации.
response=%result%
Обратите внимание что Внутренний Макрос «response» идёт первым и указывается без знаков процента, а Параметр ответа указывается в виде макроса со знаками процента ("%").

5. Добавляем сообщение Action-а

После того как мы сохранили данные ответа API во Внутреннем Макросе «response», мы можем использовать его для вывода данных в сообщении.
Пример сообщения: "Ваш ответ: %response%".
Тут Внутренний Макрос пишется по всем правилам со знаками процента ("%") - поскольку это обычное сообщение.

Кроме непосредственного вывода данных при помощи Внутренних Макросов в сообщении самого Action-а, имеющиеся Внутренние Макросы с данными можно использовать в последующей цепочке Action-ов для сохранения их переменные. Это позволит вам дальше работать с этими данными внутри бота - на общих основаниях так же как и с любыми другими данными в переменных.

В сообщениях самой кнопки Внутренние Макросы - НЕ доступны.

❖  Синтаксис доступа к Свойствам JSON

Чаще всего в качестве ответа вы будете получать JSON файл.

О том что такое JSON файл и как он устроен - смотрите в руководстве «Что такое API и как он работает».

Ниже мы рассмотрим синтаксис использующийся в Action-ах для доступа к свойствам JSON из ответа API. Возьмём упрощённый вид файла, из мануала выше, чтобы рассмотреть все варианты.

{
"firstName": "John",
"lastName": "Connor",
"address": {
    "street": "Valerio Street",
    "city": "Winnetka"
},
"friends": [
    {
    "firstName": "Bob",
    "age": 30
    },
    {
    "firstName": "Tim",
    "age": 14
    }
]
}

your_macros1=%firstName% - прямой доступ к Свойству - вернёт "John"
your_macros2=%address.city% - доступ к Объекту «address» и его элементу (Свойству) «city» - вернёт "Winnetka" 
your_macros3=%friends[0].age% - доступ к Массиву «friends», его первому элементу (под номером [0]) являющимся Объектом и его элементу (Свойcтву) «age» - вернёт "30".

❖ Сообщения об ошибках

ОШИБКА: Макросы не разбираются (хотя API работает).

Значит API ничего не вернул. Например при запросе товара или заказа - если нет такого товара или заказа.

ОШИБКА: Массив в файле JSON ответа API не имеет Ключа (названия).

Если Массив не имеет Ключа (заголовка) - генерируется имя "data". Обращаться к такому массиву можно по этому Ключу.