Устранение неполадок API и данных
Протоколы реагирования на сбои массовой экстракции, латентность сети OData и архитектурные ограничения в Business Central.
В нашей работе DevSecOps, обеспечивающей целостность каналов данных (Data Pipelines), интеграция между Business Central и платформами бизнес-аналитики может представлять собой узкие места и сетевые препятствия.
Этот документ описывает коренные причины наиболее серьезных сбоев и их окончательные решения, основанные на реализованной архитектуре.
Инцидент 1: «Удаленный хост принудительно разорвал соединение» (Timeout OData)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»Симптом
Sección titulada «Síntoma»При попытке обновить набор исторических данных (например, более 200 000 строк) из Power Query, Power BI Desktop или через скрипт Python, соединение загружается в течение нескольких минут, а затем внезапно прерывается и возвращает ошибку: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (Таймаут OData).
Диагностика коренной причины
Sección titulada «Diagnóstico Raíz»Это сбой из-за истощения ресурсов NST (уровень сервера Navision). Происходит, когда целевая конечная точка не является оптимизированным API (Query), а стандартной страницей, опубликованной как веб-служба (например, страница 38). При запросе тысяч строк на веб-страницу сервер Business Central пытается отобразить визуальные компоненты, выполнить триггеры и вычислить сложные подзапросы (FlowFields) в оперативной памяти для каждой строки. Когда обработка превышает временные ограничения (обычно 10 или 15 минут), балансировщик нагрузки Azure обрывает HTTP-соединение по соображениям безопасности, чтобы предотвратить сбой ERP.
Решение DevSecOps (реализовано)
Sección titulada «Solución DevSecOps (Implementada)»- Отказаться от веб-сервисов на основе страниц: Удалить из архитектуры любой массовый потребление данных через веб-сервисы типа страницы.
- Разработать родные API (запросы): Перенести запрос в объект
queryAL. При этом выполнение пропускает слой интерфейса и превращается в чистый SQL-оператор, уменьшая время ответа с 15 минут до менее 30 секунд. - Страница (внешние скрипты): Если мы используем язык, такой как Python, для ETL, мы должны убедиться, что соблюдаем и запрограммировали отслеживание токена
@odata.nextLink, возвращаемого сервером, поскольку Business Central устанавливает максимальный предел строк на страницу JSON, возвращаемую.
Инцидент 2: Невозможность создания подпапок в маршрутах API
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»Симптом (номенклатура и маршрутизация)
Sección titulada «Síntoma (Nomenclatura y Enrutamiento)»Во время разработки новой API в AL, при попытке создать логическую иерархию отделов, введя косую черту (/) в свойствах API, компилятор Visual Studio Code выдает фатальную ошибку и блокирует генерацию файла .app.
Пример ошибочного кода:
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Диагностика коренной причины
Sección titulada «Diagnóstico Raíz»Двигатель OData V4 Microsoft Business Central имеет жестко закодированные фабричные структурные маршруты.
Сервер всегда ожидает только неизменную модель из 3 уровней:
{APIPublisher} / {APIGroup} / {APIVersion}
Нет технических возможностей или разрешений на уровне контейнера для изменения HTTP-оркестратора и добавления дополнительных сегментов или «подпапок» в URL-адреса пользовательских API.
Решение / временное решение Архитектурное
Sección titulada «Solución / Workaround Arquitectónico»Принятие строгих соглашений об именовании (Нaming Conventions).
Поскольку невозможно создавать физические пути, разделенные /, мы имитируем иерархию с помощью подчеркивания (Snake_case) внутри APIGroup или APIPublisher.
-
Правильная реализация (Логическая группа):
APIPublisher = 'portelcore';APIGroup = 'api_portelcore_finanzas_1';APIVersion = 'v1.0';Результат OData:
.../api/portelcore/api_portelcore_finanzas_1/v1.0/ -
Альтернативная реализация (Логический издатель):
APIPublisher = 'portelcore_finanzas';APIGroup = 'analitica';APIVersion = 'v1.0';Результат OData:
.../api/portelcore_finanzas/analitica/v1.0/
3. Контрольный список диагностики API и данных
Sección titulada «3. Checklist de Diagnóstico de API y Datos»- ✓ Производительность: Полная замена услуг типа страница на объекты
Query APIдля предотвращения таймаутов из-за переполнения RAM в NST. - ✓ Формат маршрутизации: Строгое соблюдение трехуровневой схемы, требуемой компилятором AL, с использованием Snake_Case для логических иерархий.
- ✓ Синхронизация: Предварительная очистка локальных кэшей клиента для принудительного повторного обнаружения схем после пере конфигурации.

