Automation API của Business Central: publish extension, đổ dữ liệu, rà quyền không cần mở giao diện

Automation API là nhóm API Microsoft làm riêng cho việc dựng và quản trị môi trường Business Central: tạo company, chạy RapidStart package, cài và gỡ extension, xem user và permission set, bật tắt tính năng trong Feature Management. Nó không dùng để nhập đơn bán hay hoá đơn; việc đó là của API chuẩn api/v2.0.

Tài liệu gốc: Introduction to automation APIs.

Bài này viết cho consultant và người làm triển khai. Mọi lệnh bên dưới tôi đã chạy trên một môi trường sandbox BC 28 SaaS, bằng một Entra app đăng nhập kiểu service-to-service (S2S), không mở trình duyệt.

Ba loại API của Business Central, đừng lẫn#

Một điểm hay làm người mới bối rối: Automation API vẫn nằm dưới companies({id}), kể cả với những việc áp cho cả môi trường như cài extension. Company nào cũng được, miễn là company có thật. Kết quả không bị giới hạn trong company đó.

Những endpoint đã gọi được#

Kiểm ngày 21/09/2026 trên một sandbox, với Entra app đã đăng ký trong BC:

Ứng dụng 1: publish extension không cần VS Code#

Đây là việc tôi dùng nhiều nhất. Phần build file .app tôi giao cho AI chạy bằng script. Phần đẩy lên BC là bốn lệnh Automation API:

POST  .../extensionUpload
      {"schedule": "Current version", "schemaSyncMode": "Add"}

PATCH .../extensionUpload({id})/extensionContent
      Content-Type: application/octet-stream
      If-Match: *
      <noi dung file .app>

POST  .../extensionUpload({id})/Microsoft.NAV.upload

GET   .../extensionDeploymentStatus

Lệnh thứ ba trả về ngay, còn BC cài ở phía sau. Phải hỏi extensionDeploymentStatus mỗi vài giây cho tới khi trạng thái thành Completed hoặc Failed. Với một extension khoảng 140 object, mỗi lần cài mất từ 90 đến 135 giây.

Completed vẫn chưa đủ để báo "đã cài". Tôi luôn đọc lại extensions và so đúng số version với bản vừa build. Đã có lần tin vào trạng thái rồi báo xong, trong khi bản đang cài vẫn là bản cũ.

schemaSyncMode có hai giá trị. Add là mặc định an toàn. Force Sync cho phép xoá bảng hoặc trường, và dữ liệu của trường bị xoá mất theo. Chỉ dùng khi đã hỏi người có quyền quyết.

Microsoft đã báo: extensionUpload là đường cũ, dự kiến gỡ ở 2027 release wave 1. Đường thay thế là API của Business Central Admin Center. Script nào đang dùng extensionUpload thì nên lên kế hoạch chuyển trong năm 2027.

Ứng dụng 2: gỡ extension sạch sẽ#

Gỡ một extension gồm hai bước, dùng packageId lấy từ GET extensions:

POST .../extensions({packageId})/Microsoft.NAV.uninstall
POST .../extensions({packageId})/Microsoft.NAV.unpublish

uninstall giữ lại dữ liệu của extension, cài lại là thấy. Muốn xoá luôn bảng của extension thì dùng Microsoft.NAV.uninstallAndDeleteExtensionData, và bước này không hoàn tác được. unpublish chỉ có từ bản 25.4 trở đi, và chỉ chạy với extension đã uninstall.

Tôi dùng cặp lệnh này cho một thói quen: công cụ phụ để test (API liệt kê object, hàm tạo dữ liệu mẫu) không nhét vào extension của khách mà để trong một extension tạm riêng, cài khi cần, gỡ khi xong. Extension của khách không bị lẫn mã test, và dải ID của khách không bị chiếm.

Ứng dụng 3: đổ dữ liệu master bằng RapidStart#

Consultant nào cũng quen RapidStart trên giao diện. Qua Automation API thì làm được cùng việc đó bằng lệnh, lặp lại cho nhiều company hoặc nhiều môi trường:

POST  .../configurationPackages
      {"code": "MIG-ITEM", "packageName": "Item master"}

PATCH .../configurationPackages({packageId})/file('MIG-ITEM')/content
      Content-Type: application/octet-stream
      If-Match: *
      <file RapidStart>

POST  .../configurationPackages({packageId})/Microsoft.NAV.import
POST  .../configurationPackages({packageId})/Microsoft.NAV.apply

Import và apply chạy lâu với package lớn. Trạng thái của từng bước đọc lại bằng GET configurationPackages.

Hai trường hợp nên dùng đường này:

• Dựng company training hoặc company test lặp lại nhiều lần. Tạo company bằng automationCompanies, đổ bộ package chuẩn vào, xong trong một lần chạy script.
• Kiểm thử chuyển dữ liệu nhiều vòng trước go-live. Mỗi vòng chạy lại đúng một chuỗi lệnh, không phụ thuộc người bấm nhớ đúng thứ tự.

Company tạo bằng automationCompanies là company trống, chưa khởi tạo gì. Tài liệu Microsoft ghi rõ điều này.

Ứng dụng 4: rà quyền trước go-live#

Năm endpoint chỉ đọc cho biết ai có quyền gì, không sửa được gì:

Trước go-live, xuất userPermissionSets ra Excel là có ngay danh sách để khách hàng ký duyệt phân quyền, thay vì chụp màn hình từng user.

Ứng dụng 5: bật tính năng đồng đều giữa các môi trường#

GET features liệt kê các tính năng trong Feature Management kèm trạng thái. Bật một tính năng:

POST .../features({featureId})/Microsoft.NAV.activate
     {"updateInBackground": false}

Có ba môi trường Dev, UAT, Production thì chạy cùng một script cho cả ba, tránh trường hợp UAT bật một tính năng mà Production quên bật, rồi người dùng thấy hai màn hình khác nhau.

Những bẫy đã gặp#

Chuẩn bị một lần#

Để gọi được Automation API bằng S2S cần ba việc, đều làm trên giao diện và chỉ làm một lần cho mỗi môi trường:

1. Đăng ký app trong Microsoft Entra ID, tạo client secret.
2. Cấp quyền ứng dụng Automation.ReadWrite.All cho Dynamics 365 Business Central, kèm admin consent.
3. Trong BC, mở trang Microsoft Entra Applications, thêm app đó và gán permission set cần thiết.

Sau đó mọi lệnh trong bài đều gọi được từ Python, PowerShell hay Power Automate, không cần ai ngồi bấm.