Skip to main content

SMART External File Storage - On-Premises Connector

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

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

  • Прямий доступ до локальних файлових систем через WebAPI сервіс
  • Безпечна автентифікація OAuth 2.0 з Microsoft Entra ID
  • Контроль доступу до файлів через дозволи облікового запису Windows
  • Підтримка всіх стандартних операцій з файлами: створення, читання, завантаження, видалення
  • Управління каталогами: створення, перегляд вмісту, видалення
  • Інтеграція з модулем External File Storage для уніфікованого доступу

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

Для налаштування підключення до локальної файлової системи необхідно створити обліковий запис та розгорнути WebAPI сервіс.

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

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

Налаштування підключення​

ПолеОпис
Назва облікового записуУнікальна назва облікового запису для ідентифікації підключення в системі. Використовується для відображення в списках та вибору облікового запису при роботі з файлами.
URL кінцевої точки файлового сервісуURL-адреса WebAPI сервісу, розгорнутого на вашому IIS сервері. Наприклад: https://yourserver/api/filehelper або http://fileserver.company.local:8080/api. Цей сервіс повинен бути доступний з Business Central і має бути розгорнутий використовуючи пакет, наданий розширенням.
Базова папкаПочатковий каталог на сервері, з якого буде здійснюватись робота. Усі шляхи до файлів будуть відносно цього каталогу. За замовчуванням використовується кореневий каталог ("/"). Наприклад, якщо вказати "C:/Documents", всі операції будуть виконуватись відносно папки Documents. Доступ до цієї папки контролюється обліковим записом Windows, під яким працює пул додатків IIS.

Налаштування автентифікації​

ПолеОпис
АвторизаціяМетод автентифікації, який використовується для підключення до WebAPI сервісу:
- (Порожньо) - автентифікація не потрібна (не рекомендується для продуктивного середовища)
- OAuth 2.0 - використовувати автентифікацію Microsoft Entra ID з потоком облікових даних клієнта. При виборі стають доступними додаткові поля для tenant, client, audience та secret.
TenantІдентифікатор tenant Microsoft Entra (також відомий як Directory ID), де створено вашу реєстрацію додатка. Ви можете знайти його на порталі Azure в розділі Microsoft Entra ID > Огляд. Формат: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Обов'язкове при використанні автентифікації OAuth 2.0.
Client IdClient ID (також відомий як Application ID) з вашої реєстрації додатка в Microsoft Entra ID. Ви можете знайти його на порталі Azure в розділі Реєстрації додатків > [Ваш додаток] > Огляд. Формат: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Цей ідентифікатор визначає ваш екземпляр Business Central для WebAPI сервісу. Обов'язкове при використанні автентифікації OAuth 2.0.
AudienceURL audience (область) для запиту токена OAuth 2.0. Має відповідати API ідентифікатору (Application ID URI), налаштованому у вашій реєстрації додатка. Наприклад: api://filehelper або https://company.onmicrosoft.com/filehelper. WebAPI сервіс перевіряє вхідні токени відносно цього значення audience. Обов'язкове при використанні автентифікації OAuth 2.0.
Client SecretЗначення секрету клієнта з вашої реєстрації додатка в Microsoft Entra ID. Це облікові дані, подібні до пароля, які використовуються для автентифікації Business Central до WebAPI сервісу. Ви можете згенерувати цей секрет на порталі Azure в розділі Реєстрації додатків > [Ваш додаток] > Сертифікати та секрети > Новий секрет клієнта. Секрет зберігається безпечно в ізольованому сховищі Business Central і відображається як "********" після збереження. Обов'язкове при використанні автентифікації OAuth 2.0.

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

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

Розгортання WebAPI сервісу в IIS​

On-Premises Connector вимагає розгортання WebAPI сервісу на IIS сервері з доступом до вашої файлової системи. Сервіс діє як безпечний міст між Business Central та файловою системою.

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

  1. На сторінці майстра Обліковий запис On-Premises File або на картці облікового запису натисніть кнопку Розгорнути в IIS.
  2. Почнеться завантаження пакета WebAPI сервісу (ZIP файл).
  3. Розпакуйте ZIP файл у тимчасове місце на вашому IIS сервері.
  4. Розгорніть сервіс в IIS:
    • Відкрийте Менеджер IIS на вашому сервері
    • Створіть новий пул додатків (рекомендується) або використовуйте існуючий
    • Налаштуйте ідентифікатор пулу додатків для запуску під обліковим записом Windows, який має відповідні дозволи до файлової системи
    • Створіть новий веб-сайт або додаток, що вказує на розпаковані файли сервісу
    • Переконайтеся, що веб-сайт/додаток має необхідні прив'язки (HTTP/HTTPS)
    • Налаштуйте HTTPS сертифікат, якщо використовуються безпечні підключення (рекомендується)

Важливо: Ідентифікатор пулу додатків​

Обліковий запис Windows, під яким працює пул додатків IIS, визначає, до яких файлів та папок Business Central може отримати доступ. Наприклад:

  • Для доступу до C:\CompanyFiles\, обліковий запис ідентифікатора пулу додатків повинен мати дозволи на читання/запис для цієї папки
  • Ви можете використовувати обліковий запис домену, локальний обліковий запис або вбудований обліковий запис (не рекомендується для продуктивного середовища)
  • Дотримуйтесь принципу найменших привілеїв: надавайте лише ті дозволи, які потрібні для операцій з файлами

Налаштування автентифікації OAuth 2.0​

Якщо ви хочете захистити WebAPI сервіс за допомогою автентифікації OAuth 2.0, вам потрібно налаштувати його у файлі appsettings.json, розташованому в папці розгортання сервісу.

Крок 1: Створення реєстрації додатка в Microsoft Entra ID​

  1. Перейдіть на портал Azure (https://portal.azure.com)
  2. Перейдіть до Microsoft Entra ID > Реєстрації додатків > Нова реєстрація
  3. Введіть назву для вашого додатка (наприклад, "BC File Service")
  4. Виберіть Облікові записи лише в цьому організаційному каталозі
  5. Натисніть Зареєструвати
  6. Зверніть увагу на наступні значення зі сторінки Огляд:
    • Application (client) ID - це буде ваш Client ID
    • Directory (tenant) ID - це буде ваш Tenant ID

Крок 2: Створення секрету клієнта​

  1. У вашій реєстрації додатка перейдіть до Сертифікати та секрети
  2. Натисніть Новий секрет клієнта
  3. Введіть опис та виберіть період дії
  4. Натисніть Додати
  5. Важливо: Скопіюйте Значення секрету негайно - ви не зможете побачити його знову
  6. Це значення буде вашим Client Secret

Крок 3: Налаштування дозволів API (опціонально)​

Хоча це не є обов'язковим для потоку облікових даних клієнта, ви можете налаштувати дозволи API залежно від вимог безпеки вашої організації.

Крок 4: Встановлення URI ідентифікатора додатка (Audience)​

  1. У вашій реєстрації додатка перейдіть до Представити API
  2. Натисніть Встановити поруч з URI ідентифікатора додатка
  3. Прийміть значення за замовчуванням або введіть власний URI (наприклад, api://filehelper або api://yourcompany.com/filehelper)
  4. Натисніть Зберегти
  5. Цей URI буде вашим значенням Audience

Крок 5: Налаштування appsettings.json​

Відкрийте файл appsettings.json в папці WebAPI сервісу та оновіть розділ OAuthParams:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "OAuthParams": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "",
    "TenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Опис полів:

  • Instance: URL центру OAuth. Залишіть як https://login.microsoftonline.com/ для Microsoft Entra ID
  • Domain: (Опціонально) Доменне ім'я вашої організації. Може бути залишене порожнім
  • TenantId: Directory (tenant) ID з вашої реєстрації додатка
  • ClientId: Application (client) ID з вашої реєстрації додатка. Це API ідентифікатор, який перевірятиме токени

Крок 6: Налаштування облікового запису Business Central​

  1. Поверніться до Business Central і відкрийте картку Обліковий запис On-Premises File
  2. Встановіть Авторизація в OAuth 2.0
  3. Заповніть наступні поля:
    • Tenant: Directory (tenant) ID з порталу Azure
    • Client Id: Application (client) ID з вашої реєстрації додатка (той, що викликає API)
    • Audience: URI ідентифікатора додатка з кроку 4 (наприклад, api://filehelper)
    • Client Secret: Значення секрету, яке ви скопіювали в кроці 2

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

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

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

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

Дозволи доступу до файлів​

Доступ до файлів контролюється обліковим записом Windows, під яким працює пул додатків IIS:

  • Операції читання (перегляд, завантаження): Обліковий запис потребує дозволів на читання
  • Операції запису (вивантаження, створення): Обліковий запис потребує дозволів на запис
  • Операції видалення: Обліковий запис потребує дозволів на зміну або повний контроль
  • Операції з каталогами: Обліковий запис потребує відповідних дозволів на батьківські каталоги

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

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

  • Використовувати уніфікований API для роботи з файлами незалежно від типу сховища
  • Централізоване управління доступом до файлових операцій
  • Єдиний інтерфейс для роботи з різними джерелами зберігання (локальні, FTP, Azure Blob Storage, SharePoint тощо)
  • Стандартизовані операції з файлами в різних модулях Business Central
  • Можливість легко змінювати місце зберігання файлів без зміни бізнес-логіки
In this article
https://bc.smart-it.com/
© 2008 - 2023 SMART business