針對 Data API 建構器中常見的 SQL Server 連接、認證及實體配置問題的解決方案。
常見問題
DAB 中 SQL Server 支援是什麼？
Data API 建構器支援 Microsoft SQL Server 與 Azure SQL 作為關聯式資料庫後端。 DAB 透過 Microsoft.Data.SqlClient 驅動程式連接，並將 REST 與 GraphQL 請求轉換為 T-SQL 查詢。 支援本地 SQL Server 實例與 Azure SQL 資料庫。
SQL Server 使用什麼連線字串格式？
DAB 使用 ADO.NET 樣式的 SQL Server 連接字串。 典型的字串看起來像 Server=localhost,1433;Database=mydb;User Id=sa;Password=yourpassword;TrustServerCertificate=True;。 將連接字串設在 data-source.connection-string 的 dab-config.json 欄位中，或透過 --connection-string 中的 dab init選項傳遞。
支援哪些認證模式？
DAB 支援 SQL 認證（使用者名稱與密碼）、Windows 整合認證，以及 Azure SQL 的 Microsoft Entra 認證（前稱 Azure Active Directory）。 要使用 Entra 認證，請在連接字串中設定 Authentication=Active Directory Default 或 Active Directory Managed Identity ，並確保管理身份或服務主體已被授權資料庫存取。
常見問題
無法連接 SQL Server 容器
症狀： DAB 無法啟動時會出現連線錯誤，例如 A network-related or instance-specific error occurred。
原因： SQL Server 容器埠沒有正確映射、主機名稱錯誤，或容器尚未準備好接受連線。
解決： 確認容器是否運行於 docker ps。 確認埠位映射（預設 1433）並在連接字串中使用 localhost,1433 。 如果使用自簽憑證，請加入 TrustServerCertificate=True 。 如果容器剛啟動，請等幾秒鐘 SQL Server 初始化後再開始 DAB。
使用者的登入失敗
症狀： DAB 日誌顯示 Login failed for user 'sa' 或類似的認證錯誤。
原因： 連接字串中的使用者名稱、密碼或認證模式與 SQL Server 設定不符。 SQL Server 也可能以僅 Windows 認證模式運行。
解決： 確認憑證與容器或伺服器建立時設定的相符。 如果使用容器，請檢查 SA_PASSWORD 環境變數。 要在現有實例啟用 SQL 認證，請在 SQL Server Management Studio 的>中，將伺服器認證模式設為 SQL Server 和 Windows 認證模式。
找不到實體的錯誤
症狀： REST 或 GraphQL 請求會回傳 404 or 結構錯誤，表示該實體的來源資料表不存在。
原因： 實體 source 欄位中的資料表名稱或結構前綴與實際資料庫物件不符。 SQL Server 的資料表名稱預設不區分大小寫，但若未使用預設架構，則必須包含結構前綴（例如 dbo）。
解決： 檢查 source 中的 dab-config.json數值。 請使用完整限定的名稱，例如 dbo.Products。 在目標資料庫中執行 SELECT * FROM INFORMATION_SCHEMA.TABLES 以確認資料表名稱和結構。
防火牆或網路導致的錯誤與 Azure SQL 連線問題
症狀： 連接 Azure SQL Database 超時或返回 Cannot open server ... requested by the login。
原因： Azure SQL Server 防火牆規則不允許使用用戶端 IP 位址，或者 Azure 服務存取設定被停用。
解決：在 Azure 入口網站中，導覽到 SQL 伺服器資源並選擇網路。 將用戶端 IP 位址加入防火牆允許清單，或啟用 允許 Azure 服務與資源存取（ 若 DAB 在 Azure 執行）。 對於受管理的身份驗證，請確認該身份是否已被新增為資料庫使用者。CREATE USER [identity-name] FROM EXTERNAL PROVIDER
JSON 欄位不會自動偵測到
症狀： 具有 JSON 或 NVARCHAR（MAX） 類型的欄位，若儲存 JSON 資料，則不會在 API 架構中以結構化物件形式暴露。
原因： Data API 建構器尚未能自動偵測並映射 Azure SQL 中的 JSON 欄位。 這是 GitHub issue #444 中追蹤的已知限制。
解決： 目前沒有解決方法。 欄位會以純字串值的形式暴露。 請追蹤 GitHub issue 以獲取何時加入原生 JSON 欄位支援的最新消息。