BC CLI

Tôi viết công cụ này sau nhiều lần phải mở trình duyệt chỉ để tải một file .app lên, hay để xem extension đã cài xong chưa. Mọi lệnh đi qua API của BC bằng một Entra app với quyền ứng dụng (S2S), nên chạy được trong script, trong pipeline build, hoặc để AI agent tự gọi.

Gói tải về gồm bc.py, .env.example và README.md.

Cài đặt#

1. Cần Python 3.10 trở lên. Chạy pip install requests msal.
2. Giải nén, chép .env.example thành .env rồi điền 5 giá trị: tenant, client id, secret, tên môi trường, tên company.
3. Chạy python bc.py companies. Ra 200 kèm danh sách company là xong.

File .env chứa secret. Đừng commit nó lên git và đừng gửi nó qua chat.

Chuẩn bị phía BC, làm một lần#

1. Trên Microsoft Entra, đăng ký một app và tạo client secret.
2. Vào API permissions, thêm quyền ứng dụng của Dynamics 365 Business Central: API.ReadWrite.All và Automation.ReadWrite.All. Bấm Grant admin consent.
3. Trong BC, mở trang Microsoft Entra Applications, thêm Client ID của app, đặt State là Enabled.
4. Gán permission set cho app. Microsoft gợi ý D365 AUTOMATION và EXTEN. MGT. - ADMIN cho các việc tự động hóa, cộng thêm quyền trên các bảng bạn cần đọc ghi. App không được gán SUPER.

Khi app ghi dữ liệu, BC lưu Created By và Modified By là user của chính app đó, không phải người chạy lệnh.

Các lệnh#

python bc.py companies                      danh sách company
python bc.py get <đường dẫn>                GET bất kỳ đường dẫn nào sau /v2.0/<tenant>/<env>/
python bc.py post <đường dẫn> '<json>'      POST, dùng cho bound action của API page
python bc.py patch <đường dẫn> '<json>'     PATCH một bản ghi
python bc.py extensions                     extension đã publish, kèm trạng thái cài
python bc.py upload <file .app> [force]     publish và chờ tới khi BC báo xong
python bc.py unpublish "<tên app>"          gỡ bản đã publish nhưng không cài
python bc.py ws <Service> <Hàm> '<json>'    gọi unbound action của codeunit web service
python bc.py symbols <Publisher> <AppName> <Version> <thư mục>

Build và publish không cần VS Code#

Tải symbol bằng API, build bằng alc.exe của extension AL Language, rồi publish bằng upload:

python bc.py symbols Microsoft "Base Application" 28.4.53241.54346 .alpackages
python bc.py symbols Microsoft "System Application" 28.4.53241.54346 .alpackages
alc.exe /project:. /packagecachepath:.alpackages /out:out/MyApp.app
python bc.py upload out/MyApp.app

Từ extension AL Language 18, alc.exe nằm ở bin\alc.exe thay vì bin\win32\alc.exe, và cần .NET 10. Máy chỉ có .NET 8 thì lệnh build báo thiếu Microsoft.NETCore.App version 10.0.0 ngay khi chạy.

Lỗi hay gặp#

Bound action trả 400 "is not a valid parameter for the operation". Tham số của unbound action lấy theo tên tham số của hàm AL. Hàm procedure Apply(configJson: Text) thì payload là {"configJson": "<chuỗi json>"}, không phải chính object đó.

Publish báo lỗi đồng bộ schema. Bản mới xóa bảng hoặc field thì phải chạy upload <file> force để Force Sync. Dữ liệu của bảng và field bị xóa sẽ mất, nên đọc kỹ trước khi chạy.

HTTP 403 kèm số bảng. Permission set của app thiếu quyền trên bảng đó. Thông báo lỗi luôn ghi rõ số bảng, đọc nó thay vì đoán.

Thêm các bẫy khác ở bài 7 bẫy khi gọi API Business Central.

Lưu ý về lệnh upload#

Microsoft đã đánh dấu endpoint extensionUpload của Automation API là deprecated, dự kiến gỡ ở 2027 release wave 1. Đường thay thế là Business Central Admin Center API, có quyền AdminCenter.ReadWrite.All riêng. Tôi sẽ cập nhật BC CLI sang đường mới trước mốc đó.