Data API Builder implementeren in Azure App Service

Deze handleiding laat zien hoe u Data API Builder (DAB) implementeert in Azure App Service zonder containerinstallatiekopieën te bouwen of te beheren. App Service biedt ingebouwde ondersteuning voor TLS, aangepaste domeinen, schalen, bewaken en Microsoft Entra verificatie.

Prerequisites

• Een Azure-account met een actief abonnement. Gratis een account maken
• Data-API-bouwer CLI. Installeer de CLI.
• Azure CLI. Installeer de Azure CLI.
• .NET 8 SDK of hoger geïnstalleerd op uw lokale ontwikkel- of buildcomputer.
• Een bestaande ondersteunde database waartoe Azure toegang heeft.

Het configuratiebestand bouwen

Maak een DAB-configuratiebestand om verbinding te maken met uw bestaande database.

1. Maak een lege map op uw lokale computer om het configuratiebestand en de implementatieartefacten op te slaan.

2. Initialiseer een nieuw basisconfiguratiebestand met behulp van dab init. Gebruik de @env() functie om te verwijzen naar de DATABASE_CONNECTION_STRING omgevingsvariabele, zodat referenties niet worden opgeslagen in het configuratiebestand.

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

   Important

   Vervangen <database-type> door een ondersteund databasetype, zoals mssql, postgresql, mysqlof cosmosdb_nosql. Voor sommige databasetypen zijn extra configuratie-instellingen vereist voor initialisatie.

3. Voeg ten minste één database-entiteit toe aan de configuratie. Gebruik de dab add opdracht om een entiteit te configureren. Herhaal dab add dit zo vaak als u nodig hebt voor uw entiteiten.

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

4. Open en controleer de inhoud van het dab-config.json-bestand . Controleer of:

   • data-source.connection-string Gebruikt @env('DATABASE_CONNECTION_STRING')
   • Uw entiteiten en machtigingen zijn juist

   Important

   Sluit letterlijke verbindingsreeksen of geheimen niet in dab-config.json. Gebruik de @env() functie zodat waarden tijdens runtime worden omgezet vanuit omgevingsvariabelen.

DAB vastzetten voor de build

Gebruik een lokaal .NET hulpprogrammamanifest om de DAB-versie vast te maken op uw ontwikkel- of buildcomputer. Het manifest maakt builds reproduceerbaar, maar bevat niet de herstelde DAB-binaries. U kopieert deze binaire bestanden naar het implementatiepakket verderop in deze handleiding.

1. Maak een .NET lokaal hulpprogrammamanifest in uw projectmap.

   dotnet new tool-manifest
   

2. Installeer een specifieke data-API builder-versie als een lokaal hulpprogramma. Vervang <dab-version> door de versie die u wilt implementeren, zoals 2.0.9.

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

3. Controleer of het manifest bestaat op .config/dotnet-tools.json.

4. Herstel de vastgezette tool op de ontwikkel- of build-machine.

   dotnet tool restore
   

   Note

   De herstelbewerking vult de lokale NuGet-pakketcache in. Het App Service-implementatiepakket moet de herstelde runtime-nettolading bevatten; alleen .config/dotnet-tools.json implementeren is niet voldoende.

Lokaal testen

Controleer voordat u implementeert op Azure of de runtime wordt gestart en uw eindpunten werken.

1. Stel de verbindingsreeks in als een lokale omgevingsvariabele.

   • PowerShell
   • Bash

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

2. Start de DAB-runtime lokaal.

   dotnet tool run dab start
   

3. Test het REST-eindpunt door naar de Swagger UI te navigeren of een verzoek naar /api/<entity-name> te sturen.

4. Test het GraphQL-eindpunt op /graphql.

5. Stop de runtime na het verifiëren van alle eindpunten.

De App Service-resources maken

Maak de Azure resources die nodig zijn voor het hosten van DAB in App Service.

1. Een nieuwe resourcegroep maken. U gebruikt deze resourcegroep voor alle nieuwe resources in deze handleiding.

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

   Tip

   Overweeg de resourcegroep msdocs-dab-appservice een naam te geven.

2. Maak een App Service-plan.

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

   Note

   In deze handleiding wordt de B1-laag (Basic) in Linux gebruikt.

3. Maak de web-app met de .NET 8 runtime en een door het systeem toegewezen beheerde identiteit.

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

   Tip

   Valideer beschikbare runtimes voor uw plan met az webapp list-runtimes --os linux.

App Service-instellingen configureren

Configureer de omgevingsvariabelen en de opstartopdracht die App Service nodig heeft om DAB uit te voeren.

1. Stel de database-verbindingsreeks in als een App Service-toepassingsinstelling.

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

   Tip

   Gebruik een verbindingsreeks die geen geheimen bevat. Gebruik in plaats daarvan beheerde identiteiten en Microsoft Entra verificatie om de toegang tussen uw database en App Service te beheren. Zie Azure-services die gebruikmaken van beheerde identiteiten voor meer informatie.

2. Configureer het adres waarop DAB luistert. Poort 8080 is de toepassingspoort voor de ingebouwde Linux App Service-stack.

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

3. Schakel AlwaysOn- en bestandssysteemlogboekregistratie in vóór de eerste implementatie. AlwaysOn is beschikbaar op de B1-laag die in deze handleiding wordt gebruikt.

   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. Maak een opstartscript dat de DAB-runtimepayload start die is opgenomen in het implementatiepakket. Maak een bestand met de naam startup.sh in de projectmap.

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

   Important

   Zorg ervoor dat startup.sh gebruik maakt van LF-regelafbrekingen (Unix) in plaats van CRLF. Windows editors kunnen standaard opslaan met CRLF, waardoor het script mislukt op de Linux App Service-host.

5. Stel de opstartopdracht in App Service in.

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

Beheerde identiteit configureren voor Azure SQL

Als uw gegevensbron is Azure SQL, autoriseert u de door het systeem toegewezen beheerde identiteit van de web-app in de database. Sla deze sectie over als u een andere database of verificatiemethode gebruikt.

1. Maak verbinding met de doeldatabase als Microsoft Entra-beheerder.

2. Maak een ingesloten databasegebruiker voor de web-app-identiteit en ververleent alleen de machtigingen die zijn vereist voor uw DAB-entiteiten. In het volgende voorbeeld worden lees- en schrijfbewerkingen ondersteund.

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

   Note

   Microsoft Entra identiteitsdoorgifte kan enkele minuten duren nadat de web-app is gemaakt. Als CREATE USER de identiteit niet onmiddellijk kan vaststellen, wacht dan en probeer het opnieuw.

3. Stel DATABASE_CONNECTION_STRING in op een Azure SQL-verbindingsreeks voor beheerde identiteit.

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

Uitrollen naar App Service

Kopieer de herstelde DAB-runtime naar uw toepassingsmap en implementeer vervolgens de map met behulp van ZIP Deploy.

1. Maak een toepassingsmap die de DAB-configuratie, het opstartscript en de herstelde runtime-nettolading bevat.

   In de voorbeelden wordt de DAB-versie 2.0.9gebruikt. Stel de versie in op dezelfde versie die u in .config/dotnet-tools.json hebt vastgezet.

   • 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

   Voer deze opdrachten uit op dezelfde machine waarop u het vastgezette DAB-hulpprogramma hebt hersteld. Als uw omgeving de map met globale NuGet-pakketten overschrijft, dotnet nuget locals wordt de locatie omgezet.

2. Maak een ZIP met draagbare scheidingstekens tussen /-items. De hoofdmap van het archief moet direct dab-config.json, startup.sh en de map dab/ bevatten. Comprimeer de bovenliggende map app niet.

   • PowerShell
   • Bash

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

   Warning

   In Windows kan Compress-Archive geneste items opslaan met \ als scheidingstekens. Kudu ZIP-implementatie kan dat archief weigeren met HTTP 400. Gebruik een ZIP-hulpprogramma waarmee / scheidingstekens worden opgeslagen en inspecteer de archiefvermeldingen als de implementatie HTTP 400 retourneert zonder details.

3. Implementeer het ZIP-pakket in 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. Start de web-app opnieuw op nadat de implementatie is voltooid.

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

De implementatie controleren

Controleer na de implementatie of DAB succesvol is gestart in App Service.

1. Open de App Service-URL. Het hoofdantwoord bevat de DAB-status en -versie.

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

2. Test REST- en GraphQL-eindpunten met behulp van dezelfde entiteitspaden die u lokaal hebt getest. De geïmplementeerde app maakt gebruik van hetzelfde dab-config.json, dus het eindpuntgedrag moet overeenkomen met uw lokale runtime.

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

   Note

   In de productiemodus /health kan HTTP 403 worden geretourneerd wanneer de aanroeper niet is gemachtigd om het uitgebreide statusrapport weer te geven. Als de root- en geautoriseerde-entiteit-eindpunten succesvol reageren, duidt een 403-antwoord van /health niet op een opstartfout.

3. Als een eindpunt een onverwachte fout retourneert, controleert of downloadt u de toepassingslogboeken. Logboekregistratie is ingeschakeld vóór de implementatie in deze handleiding.

   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
   

Verificatie configureren (optioneel)

Beveilig uw App Service-eindpunt met Microsoft Entra ID voor productiegebruik.

Zie App Service-verificatie configureren voor gedetailleerde stappen.

Nadat u App Service-verificatie hebt ingeschakeld, configureert u DAB om identiteitsheaders te vertrouwen die zijn geïnjecteerd door App Service. Voer deze opdracht uit op uw ontwikkelcomputer en bouw het ZIP-pakket opnieuw en implementeer het.

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

Problemen met implementatie oplossen

Gebruik de volgende symptomen om veelvoorkomende implementatieproblemen te identificeren.

De hulpbronnen opschonen

Wanneer u de web-app en de bijbehorende resources niet meer nodig hebt, verwijdert u de resourcegroep.

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

Verwante inhoud

• Eenvoudige verificatie (App Service)
• Configuratiebestandsreferentie
• Runtimehost- en verificatieconfiguratie
• Implementeren in Azure Container Apps
• Integreren met Application Insights