Distribuera data-API-byggare till Azure App Service

Den här guiden visar dig hur du distribuerar Data API builder (DAB) till Azure App Service utan att skapa eller hantera containeravbildningar. App Service har inbyggt stöd för TLS, anpassade domäner, skalning, övervakning och Microsoft Entra autentisering.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto kostnadsfritt.
• Data-API-byggarens CLI. Installera CLI.
• Azure CLI. Installera Azure CLI.
• .NET 8 SDK eller senare installerat på din lokala utvecklings- eller byggdator.
• En befintlig databas som stöds och som Azure kan komma åt.

Skapa konfigurationsfilen

Skapa en DAB-konfigurationsfil för att ansluta till din befintliga databas.

1. Skapa en tom katalog på den lokala datorn för att lagra konfigurationsfilen och distributionsartefakter.

2. Initiera en ny baskonfigurationsfil med .dab init @env() Använd funktionen för att referera DATABASE_CONNECTION_STRING till miljövariabeln så att autentiseringsuppgifterna inte lagras i konfigurationsfilen.

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

   Important

   Ersätt <database-type> med en databastyp som stöds, till exempel mssql, postgresql, mysqleller cosmosdb_nosql. Vissa databastyper kräver extra konfigurationsinställningar vid initiering.

3. Lägg till minst en databasentitet i konfigurationen. dab add Använd kommandot för att konfigurera en entitet. Upprepa dab add så många gånger du behöver för dina entiteter.

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

4. Öppna och granska innehållet i dab-config.json-filen . Kontrollera att:

   • data-source.connection-string Använder @env('DATABASE_CONNECTION_STRING')
   • Dina entiteter och behörigheter är korrekta

   Important

   Bädda inte in literala anslutningssträngar eller hemligheter i dab-config.json. Använd @env()-funktionen så att värden hämtas från miljövariabler under körning.

Fäst DAB till bygget

Använd ett lokalt .NET verktygsmanifest för att fästa DAB-versionen på utvecklings- eller byggdatorn. Manifestet gör byggen reproducerbara, men innehåller inte de återställda DAB-binärfilerna. Du kopierar dessa binärfiler till distributionspaketet senare i den här guiden.

1. Skapa ett .NET lokalt verktygsmanifest i projektkatalogen.

   dotnet new tool-manifest
   

2. Installera en specifik version av Data API Builder som ett lokalt verktyg. Ersätt <dab-version> med den version som du vill distribuera, till exempel 2.0.9.

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

3. Kontrollera att manifestet finns på .config/dotnet-tools.json.

4. Återställ det fästa verktyget på utvecklings- eller byggdatorn.

   dotnet tool restore
   

   Note

   Återställningen fyller på den lokala NuGet-paketcachen. Distributionspaketet för App Service måste innehålla den återställda payloaden för körmiljön; att endast distribuera .config/dotnet-tools.json räcker inte.

Testa lokalt

Innan du distribuerar till Azure bekräftar du att körningen startar och att slutpunkterna fungerar.

1. Ange reťazec pripojenia som en lokal miljövariabel.

   • PowerShell
   • Bash

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

2. Starta DAB-programkörningen lokalt.

   dotnet tool run dab start
   

3. Testa REST-slutpunkten genom att navigera till Swagger-användargränssnittet eller göra en begäran till /api/<entity-name>.

4. Testa GraphQL-slutpunkten på /graphql.

5. Stoppa körningen när du har verifierat alla slutpunkter.

Skapa App Service-resurserna

Skapa de Azure resurser som krävs för att vara värd för DAB på App Service.

1. Skapa en ny resursgrupp. Du använder den här resursgruppen för alla nya resurser i den här guiden.

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

   Tip

   Överväg att namnge resursgruppen msdocs-dab-appservice.

2. Skapa en App Service-plan.

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

   Note

   Den här guiden använder B1-nivån (Basic) i Linux.

3. Skapa webbappen med .NET 8 som körningsmiljö och en systemtilldelad hanterad identitet.

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

   Tip

   Kontrollera tillgängliga körmiljöer för din plan med az webapp list-runtimes --os linux.

Konfigurera App Service-inställningar

Konfigurera miljövariablerna och startkommandot som App Service behöver för att köra DAB.

1. Ange databas-anslutningssträngen som en App Service-programinställning.

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

   Tip

   Använd en reťazec pripojenia som inte innehåller hemligheter. Använd i stället hanterade identiteter och Microsoft Entra autentisering för att hantera åtkomst mellan databasen och App Service. Mer information finns i Azure-tjänster som använder hanterade identiteter.

2. Konfigurera adressen som DAB lyssnar på. Port 8080 är programporten för den inbyggda Linux App Service-stacken.

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

3. Aktivera AlwaysOn- och filsystemloggning före den första distributionen. AlwaysOn är tillgängligt på B1-nivån som används i den här guiden.

   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. Skapa ett startskript som startar DAB-körningsnyttolasten som ingår i distributionspaketet. Skapa en fil med namnet startup.sh i projektkatalogen.

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

   Important

   Se till att startup.sh använder LF-radslut (Unix), inte CRLF. Windows textredigerare kan spara med CRLF som standard, vilket gör att skriptet inte fungerar på Linux App Service-plattformen.

5. Ange startkommandot i App Service.

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

Konfigurera hanterad identitet för Azure SQL

Om datakällan är Azure SQL auktoriserar du webbappens systemtilldelade hanterade identitet i databasen. Hoppa över det här avsnittet om du använder en annan databas eller autentiseringsmetod.

1. Anslut till måldatabasen som dess Microsoft Entra administratör.

2. Skapa en innesluten databasanvändare för webbappens identitet och bevilja endast de behörigheter som krävs av dina DAB-entiteter. Följande exempel stöder läs- och skrivåtgärder.

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

   Note

   Det kan ta några minuter innan spridningen av Microsoft Entra-identitet har slutförts efter att webbappen har skapats. Om CREATE USER inte kan fastställa identiteten omedelbart, vänta och försök igen.

3. Ange DATABASE_CONNECTION_STRING som en Azure SQL-anslutningssträng för hanterad identitet.

   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;"
   

Distribuera till App Service

Kopiera den återställda DAB-körningen till programkatalogen och distribuera sedan katalogen med zip-distribution.

1. Skapa en programkatalog som innehåller DAB-konfigurationen, startskriptet och den återställda körningsnyttolasten.

   Exemplen använder DAB-versionen 2.0.9. Ställ in versionen på samma version som du har fäst i .config/dotnet-tools.json.

   • PowerShell
   • Bash

   $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

   Kör dessa kommandon på samma dator där du återställde det fästa DAB-verktyget. Om din miljö åsidosätter NuGets globala paketkatalog fastställer dotnet nuget locals dess plats.

2. Skapa en ZIP med portabla / inmatningsavgränsare. Arkivroten måste innehålla dab-config.json, startup.shoch dab/ katalogen direkt. Komprimera inte den överordnade katalogen app.

   • PowerShell
   • Bash

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

   Varning

   I Windows kan Compress-Archive lagra kapslade poster med \ som avgränsare. Kudu ZIP-distributionen kan avvisa arkivet med HTTP 400. Använd ett ZIP-verktyg som lagrar / avgränsare och inspektera arkivposterna om distributionen returnerar HTTP 400 utan information.

3. Distribuera ZIP-paketet till 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. Starta om webbappen när distributionen är klar.

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

Verifiera driftsättningen

Efter distributionen bekräftar du att DAB startar framgångsrikt på App Service.

1. Öppna App Service-URL:en. Rotsvaret innehåller DAB-status och version.

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

2. Testa REST- och GraphQL-slutpunkter med samma entitetssökvägar som du testade lokalt. Den distribuerade appen använder samma dab-config.json, så slutpunktsbeteendet bör matcha din lokala miljö.

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

   Note

   I produktionsläge /health kan returnera HTTP 403 när anroparen inte har behörighet att visa den omfattande hälsorapporten. Om rot- och auktoriserade entitetsslutpunkter returnerar korrekt innebär ett 403-svar från /health inte att starten har misslyckats.

3. Om en slutpunkt returnerar ett oväntat fel, granska eller ladda ned applikationsloggarna. Loggning aktiverades före distributionen i den här guiden.

   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
   

Konfigurera autentisering (valfritt)

Skydda din App Service-slutpunkt med Microsoft Entra ID för produktionsanvändning.

Detaljerade steg finns i Konfigurera App Service-autentisering.

När du har aktiverat App Service-autentisering konfigurerar du DAB för att lita på identitetshuvuden som matas in av App Service. Kör det här kommandot på utvecklingsdatorn och återskapa och distribuera om ZIP-paketet.

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

Felsökning av driftsättning

Använd följande symptom för att identifiera vanliga distributionsproblem.

Rensa resurser

När du inte längre behöver webbappen och dess resurser tar du bort resursgruppen.

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

Relaterat innehåll

• Easy Auth-autentisering (App Service)
• Referens för konfigurationsfil
• Miljö för körning och konfiguration för autentisering
• Distribuera till Azure Container Apps
• Integrera med Application Insights