Bereitstellen des Daten-API-Generators für Azure App Service

In diesem Handbuch erfahren Sie, wie Sie den Daten-API-Generator (DATA API Builder, DAB) für Azure App Service bereitstellen, ohne Containerimages zu erstellen oder zu verwalten. App Service bietet integrierte Unterstützung für TLS, benutzerdefinierte Domänen, Skalierung, Überwachung und Microsoft Entra Authentifizierung.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Kostenlos ein Konto erstellen.
• CLI des Daten-API-Erstellers. Installieren Sie die CLI-.
• Azure CLI. Installieren Sie die Azure-Befehlszeilenschnittstelle.
• .NET 8 SDK oder höher auf Ihrem lokalen Entwicklungs- oder Buildcomputer installiert.
• Eine vorhandene unterstützte Datenbank, auf die Azure zugreifen können.

Erstellen der Konfigurationsdatei

Erstellen Sie eine DAB-Konfigurationsdatei, um eine Verbindung mit Ihrer vorhandenen Datenbank herzustellen.

1. Erstellen Sie ein leeres Verzeichnis auf Ihrem lokalen Computer, um die Konfigurationsdatei und Bereitstellungsartefakte zu speichern.

2. Initialisieren Sie eine neue Basiskonfigurationsdatei mit dab init. Verwenden Sie die @env() Funktion, um auf die DATABASE_CONNECTION_STRING Umgebungsvariable zu verweisen, sodass Anmeldeinformationen nicht in der Konfigurationsdatei gespeichert werden.

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

   Important

   Ersetzen Sie <database-type> mit einem unterstützten Datenbanktyp, wie mssql, postgresql, mysql oder cosmosdb_nosql. Für einige Datenbanktypen sind zusätzliche Konfigurationseinstellungen für die Initialisierung erforderlich.

3. Fügen Sie der Konfiguration mindestens eine Datenbankentität hinzu. Verwenden Sie den Befehl dab add, um eine Entität zu konfigurieren. Wiederholen Sie dab add so oft, wie Sie für Ihre Entitäten benötigen.

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

4. Öffnen und überprüfen Sie den Inhalt der dab-config.json Datei. Überprüfen Sie Folgendes:

   • data-source.connection-string verwendet @env('DATABASE_CONNECTION_STRING')
   • Ihre Entitäten und Berechtigungen sind korrekt.

   Important

   Betten Sie keine wörtlichen Verbindungszeichenfolgen oder geheimen Zugangsdaten in dab-config.json ein. Verwenden Sie die @env() Funktion, sodass Werte aus Umgebungsvariablen zur Laufzeit aufgelöst werden.

DAB für den Buildvorgang anheften

Verwenden Sie ein Manifest für lokale .NET-Tools, um die DAB-Version auf Ihrem Entwicklungs- oder Buildcomputer festzulegen. Das Manifest macht Builds reproduzierbar, enthält aber nicht die wiederhergestellten DAB-Binärdateien. Sie kopieren diese Binärdateien weiter unten in diesem Handbuch in das Bereitstellungspaket.

1. Erstellen Sie ein .NET lokalen Toolmanifest in Ihrem Projektverzeichnis.

   dotnet new tool-manifest
   

2. Installieren Sie eine bestimmte Daten-API-Generator-Version als lokales Tool. Ersetzen Sie <dab-version> durch die Version, die Sie bereitstellen möchten, z. B. 2.0.9.

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

3. Überprüfen Sie, ob das Manifest vorhanden ist unter .config/dotnet-tools.json.

4. Stellen Sie das angeheftete Tool auf dem Entwicklungs- oder Build-Computer wiederher.

   dotnet tool restore
   

   Note

   Der Wiederherstellungsvorgang füllt den lokalen NuGet-Paketcache auf. Das App Service-Bereitstellungspaket muss die wiederhergestellte Laufzeitnutzlast enthalten. Die Bereitstellung nur von .config/dotnet-tools.json reicht nicht aus.

Lokales Testen

Vergewissern Sie sich vor der Bereitstellung für Azure, dass die Laufzeit gestartet wird und Ihre Endpunkte funktionieren.

1. Legen Sie die Verbindungszeichenfolge als lokale Umgebungsvariable fest.

   • PowerShell
   • Bash

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

2. Starten Sie die DAB-Laufzeit lokal.

   dotnet tool run dab start
   

3. Testen Sie den REST-Endpunkt, indem Sie zur Swagger-Benutzeroberfläche navigieren oder eine Anfrage an /api/<entity-name> senden.

4. Testen Sie den GraphQL-Endpunkt bei /graphql.

5. Beenden Sie die Laufzeit, nachdem Sie alle Endpunkte überprüft haben.

Erstellen der App Service-Ressourcen

Erstellen Sie die Azure Ressourcen, die zum Hosten von DAB in App Service erforderlich sind.

1. Eine neue Ressourcengruppe erstellen. Sie verwenden diese Ressourcengruppe für alle neuen Ressourcen in diesem Handbuch.

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

   Tip

   Erwägen Sie die Benennung der Ressourcengruppe "msdocs-dab-appservice".

2. Erstellen eines App Service-Plans

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

   Note

   In diesem Leitfaden wird die Ebene B1 (Basic) unter Linux verwendet.

3. Erstellen Sie die Web-App mit der .NET 8 Laufzeit und einer vom System zugewiesenen verwalteten Identität.

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

   Tip

   Überprüfen Sie die verfügbaren Laufzeiten für Ihren Plan mit az webapp list-runtimes --os linux.

Konfigurieren von App Service-Einstellungen

Konfigurieren Sie die Umgebungsvariablen und den Startbefehl, den Der App-Dienst zum Ausführen von DAB benötigt.

1. Legen Sie die Datenbank-Verbindungszeichenfolge als App Service Anwendungseinstellung fest.

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

   Tip

   Verwenden Sie eine Verbindungszeichenfolge, die keine geheimen Schlüssel enthält. Verwenden Sie stattdessen verwaltete Identitäten und Microsoft Entra Authentifizierung, um den Zugriff zwischen Ihrer Datenbank und Dem App Service zu verwalten. Weitere Informationen finden Sie unter Azure-Dienste, die verwaltete Identitätenverwenden.

2. Konfigurieren Sie die Adresse, auf die DAB lauscht. Port 8080 ist der Anwendungsport für den integrierten Linux App Service-Stapel.

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

3. Aktivieren Sie die AlwaysOn- und Dateisystemprotokollierung vor der ersten Bereitstellung. Always On ist auf der in diesem Handbuch verwendeten B1-Ebene verfügbar.

   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. Erstellen Sie ein Startskript, das die im Bereitstellungspaket enthaltene DAB-Laufzeitnutzlast startet. Erstellen Sie eine Datei mit dem Namen startup.sh in Ihrem Projektverzeichnis.

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

   Important

   Stellen Sie sicher, dass startup.sh LF-Zeilenenden (Unix) verwendet, nicht CRLF. Windows Editoren können standardmäßig mit CRLF gespeichert werden, was dazu führt, dass das Skript auf dem Linux App Service-Host fehlschlägt.

5. Legen Sie den Startbefehl in App Service fest.

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

Konfigurieren der verwalteten Identität für Azure SQL

Wenn Ihre Datenquelle Azure SQL ist, autorisieren Sie die vom System zugewiesene verwaltete Identität der Web-App in der Datenbank. Überspringen Sie diesen Abschnitt, wenn Sie eine andere Datenbank oder Authentifizierungsmethode verwenden.

1. Stellen Sie eine Verbindung mit der Zieldatenbank als Microsoft Entra Administrator her.

2. Erstellen Sie einen enthaltenen Datenbankbenutzer für die Web-App-Identität, und erteilen Sie nur die Berechtigungen, die von Ihren DAB-Entitäten benötigt werden. Im folgenden Beispiel werden Lese- und Schreibvorgänge unterstützt.

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

   Note

   Die Microsoft Entra-Identitätsweitergabe kann nach dem Erstellen der Web-App einige Minuten dauern. Wenn CREATE USER die Identität nicht sofort ermitteln kann, warten Sie und versuchen Sie es erneut.

3. Legen Sie DATABASE_CONNECTION_STRING auf eine Azure SQL-Verbindungszeichenfolge für eine verwaltete Identität fest.

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

Bereitstellen in App Service

Kopieren Sie die wiederhergestellte DAB-Laufzeit in Ihr Anwendungsverzeichnis, und stellen Sie dann das Verzeichnis mithilfe der ZIP-Bereitstellung bereit.

1. Erstellen Sie ein Anwendungsverzeichnis, das die DAB-Konfiguration, das Startskript und die wiederhergestellte Laufzeitnutzlast enthält.

   In den Beispielen wird die DAB-Version 2.0.9verwendet. Legen Sie die Version auf die gleiche Version fest, die Sie in .config/dotnet-tools.json angeheftet haben.

   • 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

   Führen Sie diese Befehle auf demselben Computer aus, auf dem Sie das angeheftete DAB-Tool wiederhergestellt haben. Wenn Ihre Umgebung das globale NuGet-Paketverzeichnis überschreibt, ermittelt dotnet nuget locals dessen Speicherort.

2. Erstellen Sie eine ZIP-Datei mit portablen / Trennzeichen für Einträge. Das Stammverzeichnis des Archivs muss dab-config.json, startup.sh und das Verzeichnis dab/ direkt enthalten. Komprimieren Sie das übergeordnete app-Verzeichnis nicht.

   • PowerShell
   • Bash

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

   Warnung

   Unter Windows kann Compress-Archive geschachtelte Einträge unter Verwendung von \ als Trennzeichen speichern. Die Kudu-ZIP-Bereitstellung kann dieses Archiv mit HTTP 400 zurückweisen. Verwenden Sie ein ZIP-Tool, das Trennzeichen / speichert, und überprüfen Sie die Einträge im Archiv, wenn bei der Bereitstellung HTTP 400 ohne Details zurückgegeben wird.

3. Stellen Sie das ZIP-Paket in App Service bereit.

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

4. Starten Sie die Web-App neu, nachdem die Bereitstellung abgeschlossen ist.

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

Überprüfen Sie die Bereitstellung

Vergewissern Sie sich nach der Bereitstellung, dass DAB erfolgreich im App-Dienst gestartet wird.

1. Öffnen Sie die App-Dienst-URL. Die Stammantwort enthält den DAB-Status und die Version.

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

2. Testen Sie REST- und GraphQL-Endpunkte mit denselben Entitätspfaden, die Sie lokal getestet haben. Die bereitgestellte App verwendet dasselbe dab-config.json, sodass das Endpunktverhalten ihrer lokalen Laufzeit entsprechen sollte.

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

   Note

   Im Produktionsmodus kann /health HTTP 403 zurückgeben, wenn der Aufrufer nicht berechtigt ist, den umfassenden Integritätsbericht anzuzeigen. Wenn die Stamm- und die Endpunkte der autorisierten Entität erfolgreich antworten, weist eine 403-Antwort von /health nicht auf einen Startfehler hin.

3. Wenn ein Endpunkt einen unerwarteten Fehler zurückgibt, überprüfen oder herunterladen Sie die Anwendungsprotokolle. Die Protokollierung wurde in dieser Anleitung vor der Bereitstellung aktiviert.

   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
   

Konfigurieren der Authentifizierung (optional)

Schützen Sie Ihren App Service-Endpunkt mit Microsoft Entra ID für die Produktionsverwendung.

Ausführliche Schritte finden Sie unter Konfigurieren der App Service-Authentifizierung.

Nachdem Sie die App Service-Authentifizierung aktiviert haben, konfigurieren Sie DAB so, dass es den von App Service eingefügten Identitätsheadern vertraut. Führen Sie diesen Befehl auf Ihrem Entwicklungscomputer aus und erstellen Sie dann das ZIP-Paket neu und stellen Sie es erneut bereit.

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

Problembehandlung bei der Bereitstellung

Verwenden Sie die folgenden Symptome, um häufige Bereitstellungsprobleme zu identifizieren.

Bereinigen von Ressourcen

Wenn Sie die Web-App und die zugehörigen Ressourcen nicht mehr benötigen, löschen Sie die Ressourcengruppe.

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

Verwandte Inhalte

• Easy Auth (App Service)-Authentifizierung
• Konfigurationsdateireferenz
• Laufzeithost- und Authentifizierungskonfiguration
• Bereitstellen in Azure Container Apps
• Integrieren mit Application Insights