將 Data API builder 部署至 Azure App 服務

本指南將示範如何在不建置或管理容器映像的情況下，將 Data API 建置器（DAB）部署到 Azure App 服務。 App Service 內建支援 TLS、自訂網域、擴展、監控及 Microsoft Entra 認證。

先決條件

• 一個有有效訂閱的 Azure 帳號。 免費註冊帳號。
• 數據 API 產生器 CLI。 安裝 CLI。
• Azure CLI。 安裝 Azure CLI。
• 安裝在本地開發或建置機上的 .NET 8 SDK 或更新版本。
• 一個 Azure 可以存取的現有支援資料庫。

建置組態檔

建立一個 DAB 設定檔來連接你現有的資料庫。

1. 在本地機器建立一個空白目錄來存放設定檔和部署產出物。

2. 使用 dab init初始化新的基底組態檔。 用這個 @env() 函式參考 DATABASE_CONNECTION_STRING 環境變數，這樣憑證就不會被儲存在設定檔裡。

   dab init --database-type "<database-type>" --connection-string "@env('DATABASE_CONNECTION_STRING')"
   

   Important

   請以<database-type>替換，例如 mssql、 postgresql、 mysql或 cosmosdb_nosql。 有些資料庫類型在初始化時需要額外的設定設定。

3. 將至少一個資料庫實體新增至組態。 使用 dab add 命令來設定實體。 重複dab add以符合您所需的實體次數。

   dab add "<entity-name>" --source "<schema>.<table>" --permissions "anonymous:*"
   

4. 開啟並檢閱 dab-config.json 檔案的內容。 請確認：

   • data-source.connection-string 使用 @env('DATABASE_CONNECTION_STRING')
   • 你的實體與權限正確無誤

   Important

   不要在dab-config.json中嵌入字串或秘密。 使用這個 @env() 函式，讓值能在執行時從環境變數中解析出來。

將 DAB 固定用於建置

使用本地的 .NET 工具清單，將 DAB 版本釘選到你的開發或建置機上。 清單讓建置可以重現，但它不包含還原的 DAB 二進位檔。 你會在本指南後面把這些二進位檔複製到部署套件裡。

1. 在你的專案目錄中建立一個 .NET 本地工具清單。

   dotnet new tool-manifest
   

2. 安裝特定的 Data API 建構器版本作為本地工具。 用你想部署的版本取代 <dab-version> ，例如 2.0.9。

   dotnet tool install microsoft.dataapibuilder --version "<dab-version>"
   

3. 確認清單是否存在於 .config/dotnet-tools.json。

4. 在開發或建置機器上還原已釘選的工具。

   dotnet tool restore
   

   備註

   還原操作會填充本地 NuGet 套件快取。 App Service 部署套件必須包含還原的執行時有效載荷;只 .config/dotnet-tools.json 部署是不夠的。

本地測試

部署到 Azure 前，先確認執行時啟動且端點正常運作。

1. 將 連接字串 設為本地環境變數。

   • PowerShell
   • 巴什

   $env:DATABASE_CONNECTION_STRING = "<your-connection-string>"
   

2. 在本地啟動 DAB 執行環境。

   dotnet tool run dab start
   

3. 使用 Swagger 介面或發送請求至 /api/<entity-name> 來測試 REST 端點。

4. 測試位於 /graphql 的 GraphQL 端點。

5. 驗證所有端點後停止執行時。

建立 App Service 資源

建立 Azure 資源，以在 App Service 上架設 DAB。

1. 建立新的資源群組。 你在本指南中使用這個資源群組來獲取所有新資源。

   az group create --name "<resource-group-name>" --location "<location>"
   

   提示

   考慮將資源群組命名為 msdocs-dab-appservice。

2. 建立 App Service 方案。

   az appservice plan create --name "<plan-name>" --resource-group "<resource-group-name>" --sku B1 --is-linux
   

   備註

   本指南使用 Linux 上的 B1 （基礎）等級。

3. 建立使用 .NET 8 執行環境和系統指派的管理身份的網頁應用程式。

   az webapp create --name "<app-name>" --resource-group "<resource-group-name>" --plan "<plan-name>" --runtime "DOTNETCORE:8.0" --assign-identity "[system]"
   

   提示

   使用 az webapp list-runtimes --os linux 驗證你的計畫中可用的執行時環境。

設定 App 服務設定

設定 App Service 執行 DAB 所需的環境變數和啟動指令。

1. 將資料庫的連接字串設為 App Service 應用程式的設定。

   az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings DATABASE_CONNECTION_STRING="<your-connection-string>"
   

   提示

   請使用不包含機密資訊的連接字串。 相反地，請使用受管理身份和 Microsoft Entra 認證來管理資料庫與 App Service 之間的存取。 如需詳細資訊，請參閱 使用受控識別的 Azure 服務。

2. 設定 DAB 監聽的位址。 8080 連接埠是內建 Linux App Service 堆疊的應用程式連接埠。

   az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings ASPNETCORE_URLS="http://0.0.0.0:8080"
   

3. 在第一次部署前啟用 Always On 和檔案系統日誌。 Always On 在本指南所用的 B1 層級可用。

   az webapp config set --name "<app-name>" --resource-group "<resource-group-name>" --always-on true
   
   az webapp log config --name "<app-name>" --resource-group "<resource-group-name>" --application-logging filesystem --docker-container-logging filesystem --level information
   

4. 建立一個啟動腳本，啟動部署套件中包含的 DAB 執行時有效載荷。 在你的專案目錄中建立一個檔案 startup.sh 名稱。

   #!/bin/sh
   set -eu
   exec dotnet ./dab/Microsoft.DataApiBuilder.dll start --config ./dab-config.json
   

   Important

   確保 startup.sh 使用 LF（Unix）行尾，而非 CRLF。 Windows 編輯器預設可能以 CRLF 儲存，導致 Linux App Service 主機上的腳本失敗。

5. 在 App Service 裡設定啟動指令。

   az webapp config set --name "<app-name>" --resource-group "<resource-group-name>" --startup-file "sh startup.sh"
   

設定 Azure SQL 的受控識別

如果你的資料來源是 Azure SQL，請在資料庫中授權網頁應用程式系統指派的管理身份。 如果你使用不同的資料庫或認證方式，請跳過這部分。

1. 以 Microsoft Entra 管理員身份連接到目標資料庫。

2. 建立供網頁應用程式身分識別使用的獨立資料庫使用者，並且僅授與 DAB 實體所需的權限。 以下範例支援讀寫操作。

   CREATE USER [<app-name>] FROM EXTERNAL PROVIDER;
   ALTER ROLE [db_datareader] ADD MEMBER [<app-name>];
   ALTER ROLE [db_datawriter] ADD MEMBER [<app-name>];
   

   備註

   Microsoft Entra 的身份傳播在網頁應用程式建立後可能需要幾分鐘。 如果 CREATE USER 無法立即解決身份，請等待並重試。

3. 將 DATABASE_CONNECTION_STRING 設為 Azure SQL 受控識別的連接字串。

   az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings DATABASE_CONNECTION_STRING="Server=tcp:<sql-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Authentication=Active Directory Managed Identity;Encrypt=True;TrustServerCertificate=False;"
   

部署至「App Service」

將還原的 DAB 執行時複製到你的應用程式目錄，然後用 ZIP 部署該目錄。

1. 建立一個包含 DAB 設定、啟動腳本及還原執行時有效載荷的應用程式目錄。

   範例中使用 DAB 版本 2.0.9。 將版本設為與你在 .config/dotnet-tools.json 中釘選的版本相同。

   • PowerShell
   • 巴什

   $dabVersion = "2.0.9"
   $globalPackages = (dotnet nuget locals global-packages --list) -replace '^global-packages:\s*', ''
   $dabPayload = Join-Path $globalPackages "microsoft.dataapibuilder/$dabVersion/tools/net8.0/any"
   $appDirectory = Join-Path (Get-Location) "app"
   
   Remove-Item $appDirectory -Recurse -Force -ErrorAction SilentlyContinue
   New-Item -ItemType Directory -Path (Join-Path $appDirectory "dab") -Force | Out-Null
   Copy-Item dab-config.json, startup.sh -Destination $appDirectory
   Copy-Item (Join-Path $dabPayload "*") -Destination (Join-Path $appDirectory "dab") -Recurse
   
   if (-not (Test-Path (Join-Path $appDirectory "dab/Microsoft.DataApiBuilder.dll"))) {
       throw "The restored DAB runtime payload wasn't found."
   }
   

   Important

   在你還原固定 DAB 工具的同一台機器上執行這些指令。 如果您的環境覆寫了 NuGet 全域套件目錄，dotnet nuget locals 會解析該目錄的位置。

2. 建立具有可攜式 / 項目分隔符的 ZIP。 歸檔根必須直接包含 dab-config.json、 startup.sh，以及 dab/ 目錄。 不要壓縮父 app 目錄。

   • PowerShell
   • 巴什

   Remove-Item deploy.zip -Force -ErrorAction SilentlyContinue
   tar.exe -a -c -f deploy.zip -C $appDirectory dab-config.json startup.sh dab
   

   Warning

   在 Windows 上，Compress-Archive可以儲存帶有\分隔符的巢狀條目。 Kudu ZIP 部署可能會以 HTTP 400 拒絕該封存檔。 使用會保留 / 分隔符號的 ZIP 工具，若部署後回傳 HTTP 400 且沒有詳細資訊，請檢查壓縮檔中的項目。

3. 將 ZIP 套件部署到 App Service。

   az webapp deploy --resource-group "<resource-group-name>" --name "<app-name>" --src-path deploy.zip --type zip --clean true --restart false --timeout 600000
   

4. 部署完成後重新啟動網頁應用程式。

   az webapp restart --resource-group "<resource-group-name>" --name "<app-name>"
   

驗證部署

部署後，確認 DAB 是否在 App Service 上成功啟動。

1. 打開 App Service 網址。 根回應包含 DAB 狀態與版本。

   https://<app-name>.azurewebsites.net
   

2. 用你在本地測試過的實體路徑測試 REST 和 GraphQL 端點。 部署後的應用程式使用相同的 dab-config.json，因此端點行為應該與你本地執行時相符。

   https://<app-name>.azurewebsites.net/api/<entity-name>
   https://<app-name>.azurewebsites.net/graphql
   

   備註

   在生產模式下，當呼叫者未被授權查看完整健康報告時， /health 可以回傳 HTTP 403。 如果根端和授權實體端點成功返回，收到 403 回應 /health 並不代表啟動失敗。

3. 如果端點回傳意外錯誤，請檢視或下載應用程式日誌。 本指南中，已在部署前啟用記錄功能。

   az webapp log tail --name "<app-name>" --resource-group "<resource-group-name>"
   
   az webapp log download --name "<app-name>" --resource-group "<resource-group-name>" --log-file appservice-logs.zip
   

設定驗證 （選擇性）

用 Microsoft Entra ID 保護你的 App Service 端點以供生產使用。

詳細步驟請參見 「配置 App Service 認證」。

啟用 App Service 認證後，設定 DAB 信任 App Service 注入的身份標頭。 在你的開發機器上執行這個指令，然後重建並重新部署 ZIP 套件。

dab configure --runtime.host.authentication.provider AppService

針對部署進行疑難排解

請參考以下症狀來識別常見的部署問題。

清理資源

當你不再需要網頁應用程式及其資源時，刪除資源群組。

az group delete --name "<resource-group-name>" --yes --no-wait

相關內容

• Easy Auth（App Service）認證
• 設定檔參考
• 執行時主機與認證設定
• 部署至 Azure 容器應用程式
• 與 Application Insights 整合