SMART External File Storage - FTP Connector

Додаток SMART External File Storage - FTP Connector — це розширення для Microsoft Dynamics 365 Business Central, яке забезпечує підключення до FTP/SFTP серверів та інших файлових протоколів через уніфікований API модуля зовнішнього зберігання файлів (External File Storage Module). Додаток дозволяє виконувати повний спектр операцій з файлами та каталогами на віддалених серверах безпосередньо з Business Central.

Основні можливості

• Підтримка множини протоколів: SFTP, SCP, FTP, WebDAV, S3
• Безпечне зберігання облікових даних у ізольованому сховищі
• Гнучка настройка параметрів безпеки для SFTP/SSH підключень
• Підтримка автентифікації за допомогою SSH приватних ключів
• Можливість використання власної Azure Function для додаткового рівня безпеки
• Повний набір операцій з файлами: створення, читання, завантаження, видалення
• Управління каталогами: створення, перегляд вмісту
• Інтеграція з модулем External File Storage для уніфікованого доступу

Налаштування облікового запису FTP

Для налаштування підключення до FTP/SFTP сервера необхідно створити обліковий запис.

Створення облікового запису

1. Натисніть кнопку , яка відкриє функцію Пошук та введіть Облікові записи FTP, перейдіть за відповідним посиланням.
2. Натисніть кнопку Створити.
3. На картці облікового запису заповніть необхідні поля:

Основні налаштування підключення

Поле	Опис
Назва облікового запису	Унікальна назва облікового запису для ідентифікації підключення в системі. Використовується для відображення в списках та вибору облікового запису при роботі з файлами.
Azure Function Url	URL-адреса Azure Function, яка використовується як проміжний шлюз для виконання операцій з FTP сервером. За замовчуванням використовується загальнодоступна функція SMART business. Ви можете розгорнути власну функцію для додаткового контролю безпеки, інтеграції з VNet або приватними кінцевими точками.
Код авторизації Azure Function	Код авторизації на рівні функції для автентифікації запитів до Azure Function. Якщо поле залишити порожнім, буде використовуватись анонімна автентифікація. Заповніть це поле, якщо використовуєте власну захищену Azure Function.

Налаштування протоколу та адреси

Поле	Опис
Протокол	Протокол передачі файлів, який буде використовуватися для підключення: - SFTP - SSH File Transfer Protocol, забезпечує безпечну передачу файлів через SSH - SCP - Secure Copy Protocol, використовується для простого копіювання файлів через SSH - FTP - File Transfer Protocol, стандартний протокол передачі файлів (може використовуватись з додатковим шифруванням) - WebDAV - Web Distributed Authoring and Versioning, протокол для роботи з файлами через HTTP/HTTPS - S3 - Amazon S3 протокол для роботи з об'єктним сховищем
FTP Secure	Тип безпечного з'єднання для FTP протоколу (доступно лише при виборі протоколу FTP): - None - незашифроване з'єднання - Implicit - неявне шифрування (FTPS), з'єднання шифрується з самого початку - Explicit - явне шифрування (FTPES), шифрування встановлюється за допомогою команди після початкового незахищеного з'єднання
Адреса FTP	Повна адреса сервера, до якого здійснюється підключення. Можна вказати як IP-адресу (наприклад, 192.168.1.100), так і доменне ім'я (наприклад, ftp.example.com).
Номер порту	Порт для підключення до сервера. Стандартні значення: - Порт 22 для SFTP/SCP - Порт 21 для FTP - Порт 990 для FTPS (Implicit) Якщо ваш сервер використовує нестандартний порт, вкажіть відповідне значення.
Базова папка	Початковий каталог на сервері, з якого буде здійснюватись робота. Усі шляхи до файлів будуть відносно цього каталогу. За замовчуванням використовується кореневий каталог ("/"). Наприклад, якщо вказати "/documents", всі операції будуть виконуватись відносно папки documents.

Автентифікація

Поле	Опис
Ім'я користувача	Ім'я користувача для автентифікації на FTP/SFTP сервері. Це поле зберігається в захищеному сховищі.
Пароль	Пароль користувача для автентифікації. Дані зберігаються в ізольованому сховищі Business Central і шифруються. При перегляді існуючого облікового запису пароль відображається як "***".

Налаштування безпеки SSH (для SFTP/SCP)

При використанні протоколів SFTP або SCP доступні додаткові параметри безпеки для роботи з SSH.

Поле	Опис
Політика ключа хоста SSH	Визначає, як система перевірятиме ключ хоста SSH сервера при підключенні: - Check - суворо перевіряти відповідність ключа хоста. Підключення буде дозволено, лише якщо ключ хоста точно відповідає вказаному відбитку. Рекомендується для максимальної безпеки. - Accept New - автоматично приймати новий ключ хоста при першому підключенні, але перевіряти його при наступних підключеннях. Корисно, коли відбиток ключа невідомий заздалегідь. - Give Up Security And Accept Any - приймати будь-який ключ хоста без перевірки. Не рекомендується для використання в продуктивному середовищі через ризики безпеки (атаки типу man-in-the-middle).
Відбиток ключа хоста SSH	Відбиток (fingerprint) SSH ключа хоста сервера для перевірки автентичності. Використовується для захисту від атак підміни сервера. Формат відбитку: алгоритм:значення, наприклад: - ssh-rsa 2048 xx:xx:xx:...:xx - ssh-ed25519 256 xx:xx:xx:...:xx Отримати відбиток ключа можна від адміністратора сервера або за допомогою команди ssh-keyscan. Поле активне лише якщо політика ключа хоста встановлена як "Check".
Приватний ключ SSH	Приватний SSH ключ для автентифікації на основі ключів (замість пароля). Підтримуються формати OpenSSH та PuTTY PPK. Використання SSH ключів забезпечує вищий рівень безпеки порівняно з паролями. Для завантаження ключа натисніть на поле та оберіть файл з приватним ключем. Файл ключа зберігається в базі даних у зашифрованому вигляді. Якщо приватний ключ захищено паролем (passphrase), вкажіть його в полі "Пароль".

Інші параметри

Поле	Опис
Вимкнено	Позначка, яка вказує, чи вимкнено обліковий запис. Якщо встановлено, обліковий запис не може бути використаний для операцій з файлами. Це поле автоматично встановлюється при створенні sandbox середовища для запобігання небажаних операцій з продуктивними серверами.

Розгортання власної Azure Function

За замовчуванням додаток використовує загальнодоступну Azure Function від SMART business для виконання операцій з FTP серверами. Однак, для підвищення безпеки, інтеграції з корпоративною мережею або відповідності внутрішнім політикам безпеки, ви можете розгорнути власну Azure Function.

Коли варто використовувати власну Azure Function

• Потрібна інтеграція з віртуальною приватною мережею (VNet)
• Необхідне підключення через приватні кінцеві точки (Private Endpoints)
• Вимоги щодо ізоляції та контролю доступу
• Необхідність розширеного аудиту операцій
• Корпоративні політики безпеки вимагають використання лише власних ресурсів

Процес розгортання

1. На картці Обліковий запис FTP натисніть кнопку Розгорнути Azure Function в меню "Дії".
2. Відкриється портал Azure з попередньо заповненим ARM шаблоном для розгортання.
3. Виконайте наступні кроки в порталі Azure:
   • Виберіть підписку Azure
   • Виберіть існуючу або створіть нову групу ресурсів
   • Виберіть регіон для розгортання (рекомендується той самий регіон, що й Business Central)
   • Перегляньте та підтвердьте параметри розгортання
4. Почніть розгортання та дочекайтесь його завершення (зазвичай займає 5-10 хвилин).
5. Після завершення розгортання:
   • Перейдіть до створеної Azure Function в порталі Azure
   • Скопіюйте URL функції (Function URL)
   • Скопіюйте код авторизації функції (Function Key), якщо він був налаштований
6. Поверніться до картки Обліковий запис FTP в Business Central:
   • Вставте URL функції в поле Azure Function Url
   • Вставте код авторизації в поле Код авторизації Azure Function

Використання

Основні операції з файлами

Після налаштування облікового запису FTP, він автоматично інтегрується з модулем External File Storage і стає доступним для виконання операцій з файлами:

• Перегляд вмісту каталогів - переглядайте файли та підкаталоги на FTP сервері
• Завантаження файлів - завантажуйте файли з FTP сервера в Business Central
• Вивантаження файлів - завантажуйте файли з Business Central на FTP сервер
• Видалення файлів - видаляйте файли на FTP сервері
• Створення каталогів - створюйте нові каталоги на сервері
• Видалення каталогів - видаляйте порожні каталоги

Інтеграція з External File Storage Module

Після налаштування FTP конектор автоматично реєструється в модулі External File Storage, що дозволяє:

• Використовувати уніфікований API для роботи з файлами незалежно від типу сховища
• Централізоване управління доступом до файлових операцій
• Єдиний інтерфейс для роботи з різними джерелами зберігання (FTP, Azure Blob Storage, SharePoint тощо)
• Стандартизовані операції з файлами в різних модулях Business Central
• Можливість легко змінювати місце зберігання файлів без зміни бізнес-логіки

Використання з власного AL коду

У цьому розділі описано, як працювати з FTP конектором програмно з ваших AL розширень.

Налаштування файлового сценарію

Перед використанням API необхідно пов'язати FTP обліковий запис з файловим сценарієм:

1. Відкрийте Налаштування файлових сценаріїв (знайдіть через пошук у Business Central).
2. Натисніть Новий та оберіть сценарій у колонці Сценарій.
3. У колонці Конектор оберіть SMART FTP.
4. У колонці Назва облікового запису оберіть раніше налаштований FTP обліковий запис.

Сценарій — це логічна назва, яку ваш AL код використовує для звернення до облікового запису. Це відокремлює бізнес-логіку від фізичного облікового запису — можна перенаправити сценарій на інший обліковий запис без зміни коду.

Щоб зареєструвати власний сценарій, додайте enum extension до "File Scenario" у вашому AL проекті:

enumextension 50100 "My File Scenarios" extends "File Scenario"
{
    value(50100; "EDI Provider")
    {
        Caption = 'EDI Provider';
    }
}

Роздільна здатність шляхів

Усі шляхи, що передаються в API, є відносними до базової папки, налаштованої на картці FTP облікового запису. Конектор автоматично додає базову папку перед кожним запитом до сервера.

Налаштування	Значення
Базова папка (картка облікового запису)	/edi/
Шлях в AL коді	/inbox/
Фактичний шлях на сервері	/edi/inbox/

Це означає, що AL код ніколи не містить жорстко закодованих кореневих шляхів сервера. Зміна кореневої папки потребує лише одного налаштування на картці облікового запису, а не зміни коду.

Використовуйте ExternalFileStorage.CombinePath() при динамічній побудові шляхів — він коректно обробляє слеші на початку та в кінці для всіх типів конекторів.

Читання файлів з inbox та переміщення до processed

Типовий патерн інтеграції: отримати список файлів з папки inbox, завантажити кожен, обробити, а потім перемістити до папки processed, щоб файл не оброблявся повторно.

procedure ProcessInboxFiles()
var
    TempFileAccountContent: Record "File Account Content" temporary;
    ExternalFileStorage: Codeunit "External File Storage";
    FilePaginationData: Codeunit "File Pagination Data";
    FileInStr: InStream;
    SourcePath: Text;
    DestinationPath: Text;
begin
    // Ініціалізація зі сценарієм. BC знаходить пов'язаний обліковий запис через File Scenario Setup.
    ExternalFileStorage.Initialize(Enum::"File Scenario"::"EDI Provider");

    // Перевірка існування необхідних папок перед ітерацією.
    if not ExternalFileStorage.DirectoryExists('/inbox/') then
        Error('Папка inbox не існує.');
    if not ExternalFileStorage.DirectoryExists('/processed/') then
        Error('Папка processed не існує.');

    ExternalFileStorage.ListFiles('/inbox/', FilePaginationData, TempFileAccountContent);

    if not TempFileAccountContent.FindSet() then
        exit;

    repeat
        SourcePath := ExternalFileStorage.CombinePath(
            TempFileAccountContent."Parent Directory",
            TempFileAccountContent.Name);

        // GetFile є [TryFunction]: повертає false при помилці замість виключення.
        // Це гарантує, що один проблемний файл не зупинить обробку решти.
        if ExternalFileStorage.GetFile(SourcePath, FileInStr) then begin
            // Обробіть вміст файлу тут (парсинг XML, JSON тощо)

            DestinationPath := ExternalFileStorage.CombinePath('/processed/', TempFileAccountContent.Name);
            ExternalFileStorage.MoveFile(SourcePath, DestinationPath);
        end;
    until TempFileAccountContent.Next() = 0;
end;

Створення та завантаження файлу в outbox

Щоб сформувати файл і відправити його на FTP сервер, запишіть вміст у Temp Blob і передайте в CreateFile. Temp Blob — стандартний механізм BC для формування бінарного або текстового вмісту в пам'яті перед передачею в API, що очікує InStream.

procedure UploadToOutbox(FileName: Text; var ContentTempBlob: Codeunit "Temp Blob")
var
    ExternalFileStorage: Codeunit "External File Storage";
    ContentInStr: InStream;
    FilePath: Text;
begin
    ExternalFileStorage.Initialize(Enum::"File Scenario"::"EDI Provider");

    FilePath := ExternalFileStorage.CombinePath('/outbox/', FileName);

    // Конвертуємо blob в InStream для завантаження.
    ContentTempBlob.CreateInStream(ContentInStr, TextEncoding::UTF8);

    if not ExternalFileStorage.CreateFile(FilePath, ContentInStr) then
        Error('Не вдалося завантажити "%1" в outbox.', FileName);
end;

Обробка помилок

Наступні методи оголошені як [TryFunction], тобто вони повертають false при помилці замість виклику runtime error:

Метод	Поведінка при помилці
GetFile	Повертає false. Файл залишається на місці.
CreateFile	Повертає false. Файл не створюється на сервері.
MoveFile	Повертає false. Файл-джерело не переміщується.
CopyFile	Повертає false. Копія не створюється.
DeleteFile	Повертає false. Файл не видаляється.
ListDirectories	Повертає false. Результуючий запис порожній.
CreateDirectory	Повертає false. Каталог не створюється.
DeleteDirectory	Повертає false. Каталог не видаляється.

DirectoryExists та FileExists не є TryFunction — вони кидають виключення при несподіваних помилках (наприклад, помилка автентифікації), але повертають false, якщо шлях просто не існує.

Завжди перевіряйте повернене значення TryFunction явно:

if not ExternalFileStorage.CreateFile(FilePath, ContentInStr) then
    Error('Завантаження "%1" не вдалося. Перевірте налаштування FTP облікового запису.', FileName);

Для пакетних операцій (наприклад, обробка кількох файлів) використовуйте повернення false для пропуску окремого файлу без переривання циклу — дивіться приклад з inbox вище.