Ir al contenido

Устранение неполадок API и данных

Протоколы реагирования на сбои массовой экстракции, латентность сети OData и архитектурные ограничения в Business Central.

0просмотры

В нашей работе DevSecOps, обеспечивающей целостность каналов данных (Data Pipelines), интеграция между Business Central и платформами бизнес-аналитики может представлять собой узкие места и сетевые препятствия.

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

Инцидент 1: «Удаленный хост принудительно разорвал соединение» (Timeout OData)

Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»

При попытке обновить набор исторических данных (например, более 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)»
  1. Отказаться от веб-сервисов на основе страниц: Удалить из архитектуры любой массовый потребление данных через веб-сервисы типа страницы.
  2. Разработать родные API (запросы): Перенести запрос в объект query AL. При этом выполнение пропускает слой интерфейса и превращается в чистый SQL-оператор, уменьшая время ответа с 15 минут до менее 30 секунд.
  3. Страница (внешние скрипты): Если мы используем язык, такой как 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 enrutamiento
APIGroup = '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 для логических иерархий.
  • ✓ Синхронизация: Предварительная очистка локальных кэшей клиента для принудительного повторного обнаружения схем после пере конфигурации.