Déployer le générateur d’API de données sur Azure App Service

Ce guide vous montre comment déployer le générateur d’API de données (DAB) sur Azure App Service sans générer ou gérer des images conteneur. App Service fournit une prise en charge intégrée de TLS, de domaines personnalisés, de mise à l’échelle, de supervision et d’authentification Microsoft Entra.

Prerequisites

• Un compte Azure avec un abonnement actif. Créez un compte gratuitement.
• CLI du générateur d'API de données. Installez l’interface CLI.
• Azure CLI. Installez Azure CLI.
• .NET 8 SDK ou version ultérieure installée sur votre ordinateur de développement ou de build local.
• Une base de données existante prise en charge à laquelle Azure peut accéder.

Générer le fichier de configuration

Créez un fichier de configuration DAB pour vous connecter à votre base de données existante.

1. Créez un répertoire vide sur votre ordinateur local pour stocker les artefacts de configuration et de déploiement.

2. Initialisez un nouveau fichier de configuration de base à l’aide dab initde . Utilisez la @env() fonction pour référencer la DATABASE_CONNECTION_STRING variable d’environnement afin que les informations d’identification ne soient pas stockées dans le fichier de configuration.

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

   Important

   Remplacez par <database-type> un type de base de données pris en charge, tel que mssql, , postgresqlmysqlou cosmosdb_nosql. Certains types de base de données nécessitent des paramètres de configuration supplémentaires lors de l’initialisation.

3. Ajoutez au moins une entité de base de données à la configuration. Utilisez la dab add commande pour configurer une entité. Répétez dab add autant de fois que nécessaire pour vos entités.

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

4. Ouvrez et examinez le contenu du fichier dab-config.json . Vérifiez que :

   • data-source.connection-string Utilise @env('DATABASE_CONNECTION_STRING')
   • Vos entités et autorisations sont correctes

   Important

   N’incorporez pas de chaînes de connexion littérales ou de secrets dans dab-config.json. Utilisez la fonction @env() pour résoudre les valeurs depuis les variables d’environnement au moment de l’exécution.

Épingler DAB pour la build

Utilisez un manifeste d’outil .NET local pour épingler la version DAB sur votre ordinateur de développement ou de build. Le manifeste rend reproductible les builds, mais ne contient pas les fichiers binaires DAB restaurés. Vous copiez ces fichiers binaires dans le package de déploiement plus loin dans ce guide.

1. Créez un manifeste d’outil local .NET dans votre répertoire de projet.

   dotnet new tool-manifest
   

2. Installez une version spécifique du générateur d’API de données en tant qu’outil local. Remplacez <dab-version> par la version que vous souhaitez déployer, par 2.0.9exemple .

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

3. Vérifiez que le manifeste existe à .config/dotnet-tools.json.

4. Restaurez l'outil épinglé sur l'ordinateur de développement ou de compilation.

   dotnet tool restore
   

   Note

   L’opération de restauration remplit le cache de package NuGet local. Le package de déploiement de l’App Service doit inclure le contenu d’exécution restauré ; le déploiement de .config/dotnet-tools.json seul n’est pas suffisant.

Tester localement

Avant de déployer sur Azure, vérifiez que le runtime démarre et que vos points de terminaison fonctionnent.

1. Définissez la chaîne de connexion en tant que variable d’environnement locale.

   • Powershell
   • Bash

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

2. Démarrez le runtime DAB localement.

   dotnet tool run dab start
   

3. Testez le point de terminaison REST en accédant au Swagger UI ou en effectuant une demande à /api/<entity-name>.

4. Testez le point de terminaison GraphQL à l’adresse /graphql.

5. Arrêtez le runtime après avoir vérifié tous les points de terminaison.

Créer les ressources App Service

Créez les ressources Azure requises pour héberger DAB sur App Service.

1. Créez un groupe de ressources. Vous utilisez ce groupe de ressources pour toutes les nouvelles ressources de ce guide.

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

   Tip

   Envisagez de nommer le groupe de ressources msdocs-dab-appservice.

2. Créez un plan App Service.

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

   Note

   Ce guide utilise le niveau B1 (De base) sur Linux.

3. Créez l’application web avec le runtime .NET 8 et une identité managée affectée par le système.

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

   Tip

   Validez les runtimes disponibles pour votre plan avec az webapp list-runtimes --os linux.

Configurer les paramètres App Service

Configurez les variables d’environnement et la commande de démarrage dont App Service a besoin pour exécuter DAB.

1. Définissez la chaîne de connexion de la base de données en tant que paramètre de l'application App Service.

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

   Tip

   Utilisez un chaîne de connexion qui n'inclut pas de secrets. Utilisez plutôt des identités managées et Microsoft Entra l’authentification pour gérer l’accès entre votre base de données et App Service. Pour plus d’informations, consultez les services Azure qui utilisent des identités managées.

2. Configurez l’adresse sur laquelle DAB écoute. Le port 8080 correspond au port utilisé par l’application pour la pile Linux App Service intégrée.

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

3. Activez Always On et la journalisation du système de fichiers avant le premier déploiement. Always On est disponible sur le niveau B1 utilisé dans ce guide.

   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. Créez un script de démarrage qui démarre la charge utile du runtime DAB incluse dans le package de déploiement. Créez un fichier nommé startup.sh dans le répertoire de votre projet.

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

   Important

   S'assurer que startup.sh utilise les terminaisons de ligne LF (Unix) au lieu de CRLF. Windows éditeurs peuvent enregistrer avec CRLF par défaut, ce qui entraîne l’échec du script sur l’hôte App Service Linux.

5. Définissez la commande de démarrage dans App Service.

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

Configurer l’identité managée pour Azure SQL

Si votre source de données est Azure SQL, autorisez l'identité managée affectée par le système de l'application web dans la base de données. Ignorez cette section si vous utilisez une autre base de données ou méthode d’authentification.

1. Connectez-vous à la base de données cible en tant qu’administrateur Microsoft Entra.

2. Créez un utilisateur de base de données autonome pour l’identité de l’application web et accordez uniquement les autorisations requises par vos entités DAB. L’exemple suivant prend en charge les opérations de lecture et d’écriture.

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

   Note

   La propagation de l’identité Microsoft Entra peut prendre quelques minutes après la création d’une application web. Si CREATE USER ne peut pas vérifier l’identité immédiatement, attendez, puis réessayez.

3. Définissez DATABASE_CONNECTION_STRING sur une chaîne de connexion d’identité managée 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;"
   

Déployer sur App Service

Copiez le runtime DAB restauré dans votre répertoire d’application, puis déployez le répertoire à l’aide du déploiement ZIP.

1. Créez un répertoire d’application qui contient la configuration DAB, le script de démarrage et la charge utile du runtime restaurée.

   Les exemples utilisent la version 2.0.9DAB . Définissez la version sur la même que celle que vous avez épinglée dans .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

   Exécutez ces commandes sur la même machine que celle sur laquelle vous avez restauré l’outil DAB épinglé. Si votre environnement redéfinit le répertoire global des packages NuGet, dotnet nuget locals en détermine l'emplacement.

2. Créez un fichier ZIP avec des séparateurs d’entrée portables / . La racine d’archivage doit contenir dab-config.json, startup.shet le dab/ répertoire directement. Ne compressez pas le répertoire parent 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
   

   Avertissement

   Sous Windows, Compress-Archive peut stocker des entrées imbriquées avec \ comme séparateurs. Le déploiement ZIP via Kudu peut rejeter cette archive avec le code HTTP 400. Utilisez un outil ZIP qui conserve les séparateurs /, et examinez les entrées de l’archive si le déploiement renvoie une erreur HTTP 400 sans plus de détails.

3. Déployez le package ZIP sur 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. Redémarrez l’application web une fois le déploiement terminé.

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

Vérifier le déploiement

Après le déploiement, vérifiez que DAB démarre correctement sur App Service.

1. Ouvrez l’URL de l’App Service. La réponse racine inclut l’état et la version de DAB.

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

2. Testez les points de terminaison REST et GraphQL à l’aide des mêmes chemins d’entité que ceux que vous avez testés localement. L’application déployée utilise le même dab-config.json, donc le comportement du point de terminaison doit correspondre à votre environnement d'exécution local.

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

   Note

   En mode de production, /health peut renvoyer HTTP 403 lorsque l'appelant n'est pas autorisé à afficher le rapport d'intégrité complet. Si les points de terminaison racine et d'entité autorisée répondent correctement, une réponse 403 de la part de /health n'indique pas un échec du démarrage.

3. Si un point de terminaison retourne une erreur inattendue, examinez ou téléchargez les journaux d’activité de l’application. La journalisation a été activée avant le déploiement dans ce guide.

   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
   

Configurer l’authentification (facultatif)

Protégez votre point de terminaison App Service avec Microsoft Entra ID pour une utilisation en production.

Pour obtenir des instructions détaillées, consultez Configurer l’authentification App Service.

Après avoir activé l’authentification App Service, configurez DAB pour approuver les en-têtes d’identité injectés par App Service. Exécutez cette commande sur votre ordinateur de développement, puis régénérez et redéployez le package ZIP.

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

Résoudre les problèmes de déploiement

Utilisez les symptômes suivants pour identifier les problèmes de déploiement courants.

Nettoyer les ressources

Lorsque vous n’avez plus besoin de l’application web et de ses ressources, supprimez le groupe de ressources.

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

Contenu connexe

• Authentification simple (App Service)
• Informations de référence sur le fichier de configuration
• Configuration de l’hôte et de l’authentification du runtime
• Déployer sur Azure Container Apps
• Intégrer à Application Insights