Публичный Web API

Импорт данных с помощью Web API состоит из нескольких шагов:

Рассмотрим каждый шаг подробнее.

Подготовка файла для импорта

Шаблон для импорта в каждом приложении индивидуален. Его можно скачать один раз, а затем неоднократно наполнять данными для последующей загрузки в приложение.

В зависимости от объема данных и возможностей системы-источника, файл заполняется вручную или автоматически. Пример генерации файла на TypeScript можно найти в статье «Создание текстовых UTF-8 файлов» в ELMA365 Community.

Когда файл с данными подготовлен, можно переходить к следующему шагу.

Загрузка файла с данными в систему

И метод загрузки файла в директорию, и метод загрузки временного файла подходят для импорта данных. Однако при использовании последнего необходимо учитывать, что время жизни файла составляет 60 минут, и импорт должен завершиться за это время. Поэтому при импорте больших объемов данных (более 50000 записей за раз) рекомендуется использовать метод загрузки файла в директорию.

Важно: одним из обязательных параметров обоих методов является hash. В дальнейшем он используется для вызова метода импорта данных. Сгенерированный hash необходимо сохранить, так как в ответе он не возвращается.

Пример запроса для загрузки файла в директорию можно найти в статье о подключении к API загрузки файлов через TypeScript.

После успешной загрузки файла в систему переходим к импорту данных.

Запуск импорта данных

Для запуска импорта данных необходимо использовать hash ранее загруженного файла. Также в теле запроса передаем формат файла — .xlsx или .csv — и игнорируем обработчики событий — withEventHandlers: false. Обработчики событий настоятельно рекомендуется игнорировать при импорте больших объемов данных, так как они могут создавать высокую нагрузку на систему и влиять на ее работоспособность.

Если бизнес-логика все же требует использовать обработчики событий при импорте, рекомендуется загружать данные небольшими частями (до 1000 записей) и делать паузу между запросами, чтобы система завершила обработку очереди сообщений.

В случае успешного запуска импорта в ответе на запрос приходит информация о количестве импортированных на данный момент элементов, статус текущего импорта и его ID, который используется для получения статуса.

Важно: если импорт данных в приложение уже запущен, запустить еще одну процедуру импорта будет невозможно. Запрос вернет статус blocked.

Проверка результата импорта

Метод получения результата импорта возвращает такой же ответ, как и метод запуска импорта. Отправляя этот запрос с заданной периодичностью, можно получать актуальную информацию о количестве импортированных элементов, а также определить, когда импорт завершится. Рекомендуется запрашивать статус импорта не чаще чем раз в секунду.