API-запросы через сниппет
В данном руководстве демонстрируется процесс выполнения API-запроса к внешнему серверу для обогащения данных в реальном времени. В качестве примера используется задача определения информации по номеру телефона, однако представленный подход является универсальным и может быть адаптирован для обработки любых других данных, извлекаемых из пользовательского ввода.
Сферы применения
Автоматическая обработка и обогащение данных через внешние API является ключевым требованием для многих бизнес-процессов в таких отраслях, как телекоммуникации, финансы и электронная коммерция. Это позволяет решать следующие задачи:
Динамическая маршрутизация: Направление обращений в профильные отделы на основе данных о клиенте.
Персонализация: Предоставление кастомизированных предложений.
Антифрод-анализ: Выявление подозрительной активности на основе обогащенных данных.
Например, по номеру телефона можно определить оператора связи, регион и другие параметры, которые затем могут быть использованы для ветвления логики сценария.
Алгоритм реализации
Ниже представлен алгоритм, описывающий логику работы сниппета для обогащения данных по номеру телефона:
Извлечение входных данных: Получение номера телефона из параметров вызова сниппета или из контекста диалога (например, из ранее распознанной сущности).
Нормализация данных: Валидация и очистка номера телефона от нерелевантных символов (пробелы, дефисы) и приведение к стандартному формату (например, удаление кода страны).
Формирование и отправка API-запроса: Инициализация HTTP-запроса к внешнему сервису с передачей нормализованного номера.
Обработка ответа: Анализ статуса ответа от API. В случае успеха — переход к следующему шагу. В случае ошибки — выполнение логики обработки исключений.
Сохранение данных в контекст: Запись полученных данных (оператор, регион и т.д.) в контекст диалога для их дальнейшего использования в сценарии.
Логирование (опционально): Вывод отладочной информации о результатах выполнения запроса.
Обработка исключений: Корректная обработка ошибок, возникших на любом из этапов, с информированием пользователя или системы.
Рекомендация: Отладочные вызовы, такие как
core.sendText, следует использовать только на этапе разработки. Перед развертыванием в production-среде их необходимо удалить или закомментировать.
async function snippet (core = new Core(), context = new Context()) {
// Измените на ваш URL API
const apiUrl = 'https://api.example.com/v2/operator?number=';
// Переменные для хранения номера телефона
let phone = null;
let inputPhone = null;
// Проверяем, был ли передан номер телефона
if (inputPhone) {
phone = inputPhone; // Если номер передан в параметре, используем его
} else if (context && context.current && context.current.meta &&
context.current.meta.entities && context.current.meta.entities.phone) {
// Если номер телефона есть в контексте, извлекаем его
phone = context.current.meta.entities.phone.raw;
}
// Проверяем, что номер телефона действительно найден (для отладки)
if (!phone) {
core.sendText('Номер телефона не указан в контексте');
return null;
}
// Логируем номер телефона для тестирования (для отладки)
core.sendText('Номер телефона в контексте: ' + phone);
// Преобразуем номер в строку и удаляем все нецифровые символы
// (например, пробелы, скобки, дефисы)
phone = String(phone);
phone = phone.replace(/\D/g, '');
// Убираем код страны (например, 7 или 8 для России)
if (phone.startsWith('7') || phone.startsWith('8')) {
phone = phone.slice(1);
}
// Логируем номер для отправки запроса (для отладки)
core.sendText(`Отправляем запрос с номером: ${phone}`);
try {
// Отправляем GET запрос к API с номером телефона
// Запрос будет отличаться в зависимости от вашего API
const response = await axios.get(apiUrl, {
params: { number: phone }, // Передаем номер в параметре
headers: {
"Accept": "*/*",
"Accept-Language": "en,ru;q=0.9,en-GB;q=0.8,en-US;q=0.7",
"Cache-Control": "no-cache",
"Connection": "keep-alive",
"Origin": "https://api.example.com/v2/operator?number=",
"Pragma": "no-cache",
"Referer": "https://api.example.com/v2/operator?number=",
"Sec-Fetch-Dest": "empty",
"Sec-Fetch-Mode": "cors",
"Sec-Fetch-Site": "same-site",
"User-Agent": ""
}
});
// Получаем ответ от API
const operatorInfo = response.data;
// Проверяем код статуса ответа
// statusCode возвращает 1001 - успех, 3003 - ошибка
if (operatorInfo.statusCode && operatorInfo.statusCode !== 1001) {
throw new Error(`Ошибка API: ${operatorInfo.statusCode}`);
}
// Сохраняем данные в контексте
// Response
context.set("operatorInfo", operatorInfo);
// Имя оператора
context.set("operatorName", operatorInfo.operator);
// Регион
context.set("region", operatorInfo.region);
// Полное название оператора
context.set("operatorTitle", operatorInfo.title);
// Код оператора
context.set("operatorCode", operatorInfo.code);
// Логируем данные для отладки
core.sendText("Ответ API получен и сохранен в контексте");
// Название оператора
// JSON.stringify превращает объект в строку формата JSON,
// чтобы представить данные в текстовом виде.
core.sendText(JSON.stringify(context.operatorInfo));
return operatorInfo.code;
} catch (error) {
// Обработка ошибки
core.sendText(`Ошибка при запросе: ${error.message}`);
if (error.response && error.response.data) {
core.sendText(JSON.stringify(error.response.data));
return error.response.data;
}
core.sendText('Не удалось получить информацию о номере телефона');
}
}
Последнее обновление