Як легше керувати зовнішніми файлами в Business Central за допомогою єдиного API
Guidelines / Tutorials Technical Microsoft Dynamics 365 Business Central
черв. 23, 2025 2715 перегляди 1 час читання

Як легше керувати зовнішніми файлами в Business Central за допомогою єдиного API

Одним із найскладніших завдань під час оновлення Microsoft Dynamics 365 Business Central до SaaS або під час розробки сучасних, готових до відповідності рішень у хмарі, є керування зовнішніми файлами поза Business Central. Протягом останніх кількох років партнери та розробники мали труднощі зі створенням інтеграцій, які дозволяють завантажувати, зберігати та отримувати файли із зовнішніх систем безпечним та перспективним способом. Різні клієнти мають різні вимоги: деяким потрібен SharePoint, інші віддають перевагу SFTP, Azure Blob або OneDrive. Як результат, різні партнери та розробники часто створювали власні функції для взаємодії із зовнішніми файловими системами, кожен дотримуючись власних шаблонів та підходів. Іноді це може призвести до фрагментованих рішень, які важко підтримувати, які є непослідовними у своїй реалізації та часто вимагають великого користувацького коду AL або зовнішніх доповнень.


API єдиного зовнішнього сховища файлів

Щоб вирішити ці проблеми, Microsoft представила модуль зовнішнього сховища файлів, який був попередньо представлений у першій хвилі випуску Dynamics 365 Business Central 2025. Ця нова функція виступає уніфікованим API та розширюваною платформою для обробки зовнішніх файлів. Вона стандартизує спосіб завантаження, вивантаження та керування файлами незалежно від вибраного постачальника. Платформа наразі підтримує вбудовані постачальники для Azure Blob, Azure FileShare та SharePoint, але розроблена для легкого розширення.

Ключові переваги такого рішення:

  • Уніфікований підхід для різних постачальників сховищ
  • Спрощена розробка AL за допомогою стандартного API
  • Розширювані користувацькі сценарії (наприклад, OneDrive, SFTP)

Як налаштувати

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

1. Переконайтеся, що необхідні програми External File Storage Connector встановлено та готові до використання.

2. Відкрийте сторінку Зовнішні облікові записи файлів у веб-клієнті Business Central і виберіть дію Додати обліковий запис файлу .

3. Виберіть «Далі» , щоб розпочати.

4. Виберіть один із зовнішніх файлових облікових записів, доступних за замовчуванням, наприклад, Blob Storage (Сховище BLOB-об’єктів ), а потім натисніть кнопку Далі (Далі) .

5. Заповніть наступну інформацію, щоб налаштувати обліковий запис сховища BLOB-об’єктів Azure :

  • Ім’я облікового запису: Ім’я цього зовнішнього файлового облікового запису ( для ідентифікації в Business Central ).
  • Ім’я облікового запису сховища: ім’я облікового запису сховища Azure.
  • Тип авторизації: метод, що використовується для автентифікації ( спільний токен підпису доступу або спільний ключ ).
  • Секрет: фактичне значення токена підпису спільного доступу або спільного ключа.
  • Ім’я контейнера: конкретний контейнер у вашому обліковому записі сховища BLOB-об’єктів.

6. Натисніть кнопку «Готово» , щоб завершити налаштування.

7. Повторіть кроки 2–6 і заповніть наступну інформацію, щоб налаштувати обліковий запис спільного доступу до файлів Azure :

  • Ім’я облікового запису: Ім’я цього зовнішнього файлового облікового запису.
  • Ім’я облікового запису сховища: ім’я облікового запису сховища Azure.
  • Тип авторизації: метод, що використовується для автентифікації ( спільний токен підпису доступу або спільний ключ ).
  • Секрет: фактичне значення токена підпису спільного доступу або спільного ключа.
  • Ім’я спільного файлового ресурсу: ім’я спільного файлового ресурсу у вашому обліковому записі сховища.

8. Повторіть кроки 2–6 і заповніть наступну інформацію, щоб налаштувати обліковий запис SharePoint :

  • Ім’я облікового запису: Ім’я цього зовнішнього файлового облікового запису.
  • Ідентифікатор клієнта: ідентифікатор клієнта вашої реєстрації програми.
  • Ідентифікатор клієнта: ідентифікатор клієнта вашої реєстрації програми.
  • Секрет клієнта: Секрет клієнта реєстрації вашої програми.
  • Ім’я SharePoint: SharePoint, який використовуватиметься для облікового запису сховища.
  • Базовий відносний шлях до папки: шлях до папки відносно колекції сайтів.

Почніть з назви бібліотеки документів або папки ( наприклад, Спільні документи/звіти ). Цей шлях можна скопіювати з URL-адреси папки в SharePoint після колекції сайтів ( наприклад, /Спільні документи/звіти з https://mysharepoint.sharepoint.com/sites/ProjectX... ).

Тепер у вас створено три нові облікові записи зовнішніх файлів, які готові до використання.

Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати
Як налаштувати

Як орієнтуватися в зовнішньому сховищі файлів

Після завершення налаштування ви можете почати взаємодіяти із зовнішнім сховищем безпосередньо зі сторінки «Облікові записи зовнішніх файлів» :

1. Виберіть один з облікових записів сховища зі списку ( наприклад, «Демо-сховище Azure Blob» ) і натисніть дію « Оглядач сховища» . Система відкриє сторінку «Оглядач зовнішнього сховища» , на якій повністю відображається вміст відповідного контейнера сховища Azure Blob.

2. На сторінці «Оглядач зовнішнього сховища» можна виконувати кілька основних операцій з файлами в налаштованому контейнері Blob:

  • Завантажити новий файл
  • Завантажити новий файл
  • Видалити файл або каталог
  • Створити новий каталог
  • Навігація по підкаталогах у вашому кореневому контейнері

Ви матимете такий самий користувацький інтерфейс під час роботи з попередньо налаштованим спільним файловим ресурсом Azure.

або облікові записи зовнішнього сховища SharePoint .

Як орієнтуватися в зовнішньому сховищі файлів
Як орієнтуватися в зовнішньому сховищі файлів
Як орієнтуватися в зовнішньому сховищі файлів
Як орієнтуватися в зовнішньому сховищі файлів

Як працює уніфікований API зовнішнього сховища файлів

Функція зовнішнього сховища файлів побудована на модульній та розширюваній архітектурі, що складається з:

1. Модуль зовнішнього сховища файлів ( частина застосунку Microsoft System Application ).

Надає простий у використанні API для зберігання файлів поза Business Central.

2. Окремі програми розширення для різних систем зберігання даних.

Кожна система зберігання даних ( наприклад, Azure Blob, FileShare, SharePoint, custom ) реалізує стандартний інтерфейс із модуля зовнішнього сховища файлів. Наразі доступні три окремі розширення конектора:

  • Зовнішнє сховище файлів – з’єднувач служби Azure Blob
  • Зовнішнє сховище файлів – з’єднувач служби файлів Azure
  • Зовнішнє сховище файлів – SharePoint Connector

3. Додаткові модулі в системній програмі Microsoft, що допомагають взаємодіяти з різними системами зберігання даних:

  • Модуль API служб Azure Blob
  • Модуль API файлових служб Azure
  • Модуль SharePoint

Загальний огляд уніфікованого API зовнішнього сховища файлів показано на діаграмі нижче:

Кожне розширення для системи зберігання даних повинно містити щонайменше такі п'ять основних об'єктів. На прикладі конектора служби Azure Blob Service це:

  • таблиця 4560 "Зовнішній обліковий запис сховища BLOB-об'єктів" – зберігає відомості про підключення для облікових записів сховища BLOB-об'єктів Azure.
  • сторінка 4560 «Обліковий запис зовнішнього сховища BLOB-об’єктів» – сторінка картки для перегляду або редагування інформації з таблиці «Обліковий запис зовнішнього сховища BLOB-об’єктів».
  • сторінка 4561 «Майстер облікових записів зовнішнього сховища BLOB-об’єктів» – допомагає користувачам вводити дані облікового запису сховища BLOB-об’єктів Azure під час створення нового облікового запису сховища.
  • enumextension 4560 "Ext. Blob Storage Connector" – розширює список облікових записів сховища новим типом сховища.
  • кодовий блок 4560 "Імплементація з'єднувача зовнішнього сховища BLOB-об'єктів" – реалізує уніфікований інтерфейс "З'єднувач зовнішнього сховища файлів" з модуля зовнішнього сховища файлів.

Одна з ключових ідей полягає в тому, що уніфікований інтерфейс «З’єднувача зовнішнього сховища файлів» надає набір попередньо визначених процедур для взаємодії з будь-яким обліковим записом зовнішнього сховища, таких як:

  • ListFiles – Отримує список файлів, що зберігаються у вказаному обліковому записі.
  • GetFile – Отримує файл із наданого облікового запису.
  • CreateFile – створює файл для наданого облікового запису.
  • CopyFile – копіює як файл у наданий обліковий запис.
  • MoveFile – Перемістити як файл у межах наданого облікового запису.
  • FileExists – перевіряє, чи існує файл у вказаному обліковому записі.
  • DeleteFile – Видаляє файл, що існує у вказаному обліковому записі.
  • ListDirectories – Отримує список каталогів, що зберігаються у вказаному обліковому записі.
  • CreateDirectory – створює каталог для наданого облікового запису.
  • DirectoryExists – перевіряє, чи існує каталог для вказаного облікового запису.
  • DeleteDirectory – Видаляє існуючий каталог для вказаного облікового запису.
  • та більше...

Кожне розширення зовнішнього сховища файлів має власний кодовий модуль «Реалізація конектора» з логікою для своєї конкретної системи зберігання. Однак усі конектори надають однаковий набір методів з однаковими параметрами, що робить весь фреймворк гнучким, стандартизованим та перспективним:

  • кодовий блок 4560 "Зовнішнє зберігання BLOB-об'єктів. Реалізація з'єднувача."
  • кодовий блок 4570 "Зовнішній з'єднувач спільного доступу до файлів, що реалізовано"
  • кодовий блок 4580 "Зовнішня реалізація конектора SharePoint"
Як працює уніфікований API зовнішнього сховища файлів
Як працює уніфікований API зовнішнього сховища файлів
Як працює уніфікований API зовнішнього сховища файлів
Як працює уніфікований API зовнішнього сховища файлів

Як використовувати модуль зовнішнього сховища файлів у вашому коді

Щоб використовувати модуль Зовнішнє сховище файлів у вашому коді AL, спочатку потрібно визначити файлові сценарії та пов’язати їх з вашими обліковими записами сховища. Ось як це зробити:

1. Створіть розширення переліку для стандартного переліку 9451 "Сценарій файлу" та додайте власні сценарії. Наприклад, ви можете створити три сценарії для трьох різних облікових записів сховища ( наприклад, Azure Blob, FileShare, SharePoint ).

2. Відкрийте сторінку «Зовнішні файлові облікові записи» у веб-клієнті Business Central і виберіть «Сценарії файлів».

3. Призначте сценарії, створені на кроці 1, відповідним обліковим записам зовнішнього сховища файлів.

Тепер ви готові програмно взаємодіяти із зовнішнім сховищем файлів. Ви можете написати просту процедуру для завантаження файлу за допомогою кодового блоку 9454 "Зовнішнє сховище файлів" з модуля Зовнішнє сховище файлів.

Той самий шаблон коду застосовується до всіх підключених облікових записів сховища, незалежно від постачальника. Єдине, що вам потрібно змінити, це назву сценарію, яку ви встановили в процедурі ініціалізації перед початком операцій з іншою зовнішньою файловою системою.

Розширення модуля зовнішнього сховища файлів

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

Наприклад, щоб увімкнути підтримку OneDrive або SFTP як додаткових зовнішніх сховищ, потрібно виконати такі дії:

1. Створіть окремі розширення для SFTP та OneDrive:

  • Зовнішнє сховище файлів – SFTP-конектор
  • Зовнішнє сховище файлів – OneDrive Connector

2. Додайте необхідний набір об’єктів, щоб дотримуватися архітектури API модуля зовнішнього сховища файлів, як описано вище. Як приклади можна використовувати існуючі конектори Azure Blob, Azure FileShare або SharePoint.

3. Створіть відповідні кодові одиниці «SFTP-клієнт» та «OneDrive Client», які містять логіку, необхідну для взаємодії з певними зовнішніми системами зберігання даних.

Після створення та встановлення цих розширень у списку доступних файлових облікових записів ви побачите два нових типи зовнішніх облікових записів сховища:

Як використовувати модуль зовнішнього сховища файлів у вашому коді
Як використовувати модуль зовнішнього сховища файлів у вашому коді
Як використовувати модуль зовнішнього сховища файлів у вашому коді
Як використовувати модуль зовнішнього сховища файлів у вашому коді
Як використовувати модуль зовнішнього сховища файлів у вашому коді
Як використовувати модуль зовнішнього сховища файлів у вашому коді

SFTP

Скористайтеся майстром зовнішніх файлових облікових записів, щоб заповнити необхідну інформацію та налаштувати свій обліковий запис SFTP:

  • Ім’я облікового запису: Ім’я облікового запису SFTP.
  • URL-адреса програми Azure Function App: URL-адреса вашої програми Azure Function App, яка оброблятиме запити SFTP.
  • Ключ програми Azure Function: ключ програми Azure Function.
  • Ім'я хоста: Ім'я хоста SFTP ( наприклад, sftp.example.com ).
  • Номер порту: Номер порту SFTP-сервера.
  • Ім'я користувача : Ім'я користувача для SFTP-сервера.
  • Пароль : Пароль для SFTP-сервера.
  • Робочий каталог за замовчуванням : каталог за замовчуванням на SFTP-сервері ( наприклад, "upload" ).

Після налаштування ви можете скористатися дією «Оглядач сховища» , щоб перевірити, чи обліковий запис сховища правильно відображає вміст вашого SFTP-сервера.

Загальна архітектура рішення для зберігання SFTP у нашому випадку така:

Давайте детальніше розглянемо, як це працює на основі операції створення файлу:

  • Уніфікована процедура CreateFile з кодового блоку " Ext. SFTP Connector Impl." викликає процедуру CreateFile з кодового блоку "SFTP File Client" .
  • Процедура CreateFile з кодового блоку "SFTP File Client" передає деталі SFTP-з'єднання та відповідний файл ( як рядок Base64 ) до функції Azure UploadFile через параметри.
  • Функція Azure отримує ці параметри та викликає свою внутрішню функцію-обробник UploadFile .
  • Функція обробника UploadFile використовує бібліотеку Renci.SshNet для завантаження файлу на SFTP-сервер.
SFTP
SFTP
SFTP
SFTP
SFTP
SFTP
SFTP

OneDrive

Скористайтеся майстром зовнішніх файлових облікових записів, щоб заповнити необхідну інформацію для вашого облікового запису OneDrive:

  • Ім’я облікового запису: Ім’я облікового запису OneDrive.
  • Ідентифікатор клієнта: ідентифікатор клієнта реєстрації програми.
  • Ідентифікатор клієнта: ідентифікатор клієнта реєстрації програми.
  • Секрет клієнта: Секрет клієнта реєстрації програми.
  • Ім’я OneDrive: OneDrive, який використовуватиметься як обліковий запис сховища.
  • Ім’я користувача OneDrive : унікальний ідентифікатор облікового запису користувача, до OneDrive якого ви хочете отримати доступ.
  • Базовий відносний шлях до папки : робочий каталог за замовчуванням ( наприклад, домашній каталог користувача або певна папка на OneDrive ).

Знову ж таки, скористайтеся дією «Оглядач сховища» , щоб перевірити, чи обліковий запис сховища відображає ваш вміст OneDrive.

Загальна архітектура рішення для зберігання даних OneDrive така:

Давайте детальніше розглянемо, як це працює на основі тієї ж операції створення файлу:

  • Уніфікована процедура CreateFile з кодового блоку "Ext. OneDrive Connector Impl." викликає процедуру AddFileToFolder з кодового блоку клієнта "OneDrive Client" :
  • Процедура AddFileToFolder з "OneDrive Client" надсилає запит PUT до відповідної кінцевої точки Microsoft Graph API:

ВАЖЛИВО : Ви повинні налаштувати правильну реєстрацію програми з необхідними дозволами для API OneDrive.

Необхідні делеговані дозволи для взаємодії з OneDrive через Graph API можуть включати:

  • Файли.Читання
  • Файли.Читання.Все
  • Файли.Читання/Запис
  • Files.ReadWrite.All
  • Файли.ЧитанняЗапису.ПапкаАппапки
  • Файли.Прочитано.Вибрано
  • Файли.ЧитанняЗапису.Вибрані

Необхідні дозволи програми можуть включати:

  • Файли.Читання.Все
  • Files.ReadWrite.All

Тепер ви можете розширити стандартний перелік 9451 "Сценарій файлу" сценаріями для ваших нових облікових записів сховища.

і почніть використовувати їх у своєму коді.

OneDrive
OneDrive
OneDrive
OneDrive
OneDrive
OneDrive
OneDrive


Висновок

Впровадження єдиного модуля зовнішнього сховища файлів у Microsoft Dynamics 365 Business Central – це крок уперед у спрощенні та стандартизації способів керування зовнішніми файлами в хмарному середовищі для компаній. Надаючи єдиний розширюваний інтерфейс API для різних постачальників сховищ, включаючи готові Azure Blob, FileShare, SharePoint та будь-які користувацькі конектори, такі як SFTP або OneDrive, Microsoft покращила процес керування зовнішніми файлами як для розробників, так і для клієнтів.

Завдяки цій платформі рішення стають більш перспективними та простішими в обслуговуванні. Можливість розширення платформи за допомогою нових постачальників гарантує, що ваше середовище Business Central зможе адаптуватися до змінних бізнес-вимог та технологічних тенденцій, дозволяючи вам швидко перейти на альтернативну зовнішню систему зберігання даних за потреби. Якщо ви ще не вивчили модуль Зовнішнього сховища файлів, зараз саме час розглянути його впровадження та почати використовувати цей уніфікований API у ваших рішеннях Business Central.


Посилання

Для отримання детальнішої інформації див. офіційні ресурси Microsoft:


Ви випадково щось знаєте про Xpand?

Xpand — це компанія з розробки програмного забезпечення для продуктів та послуг з понад 15-річним досвідом роботи на ринку та партнером Microsoft з 2016 року, яка допомагає організаціям по всьому світу керувати їхніми системами Microsoft Dynamics ERP. Ми пропонуємо широкий спектр послуг для клієнтів та партнерів, включаючи впровадження та розробку Microsoft Dynamics 365 Business Central, а також оновлення з попередніх версій, таких як Navision Financials 2.0. Дізнайтеся більше про наші послуги на сайті https://www.xpandsoftware.com/services .

Сподобалася стаття? Перегляньте ще одну статтю автора про технічне письмо та його нюанси - Як автоматизувати приймальне тестування в Business Central за допомогою інструмента створення сценаріїв сторінок