Implementación de Data API Builder en Azure App Service

En esta guía se muestra cómo implementar Data API Builder (DAB) para Azure App Service mediante un modelo de implementación basado en código, sin compilar ni administrar imágenes de contenedor. App Service proporciona compatibilidad integrada con TLS, dominios personalizados, escalado, supervisión y autenticación Microsoft Entra.

Tip

Si su entorno usa contenedores, consulte Implementación en Azure Container Apps o Implementación en Azure Kubernetes Service como alternativa.

Prerequisites

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• CLI para el generador de APIs de datos. Instale la CLI.
• CLI de Azure. Instalación de la CLI de Azure.
• .NET 8 o posterior instalado localmente.
• Base de datos compatible existente accesible por Azure.

Compilación del archivo de configuración

Cree un archivo de configuración DAB para conectarse a la base de datos existente.

1. Cree un directorio vacío en la máquina local para almacenar el archivo de configuración y los artefactos de implementación.

2. Inicialice un nuevo archivo de configuración base mediante dab init. Use la @env() función para hacer referencia a la DATABASE_CONNECTION_STRING variable de entorno, por lo que las credenciales no se almacenan en el archivo de configuración.

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

   Importante

   Reemplace por <database-type> un tipo de base de datos compatible, como mssql, postgresql, mysqlo cosmosdb_nosql. Algunos tipos de base de datos requieren opciones de configuración adicionales en la inicialización.

3. Agregue al menos una entidad de base de datos a la configuración. Use el dab add comando para configurar una entidad. Repita dab add tantas veces como necesite para sus entidades.

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

4. Abra y revise el contenido del archivo dab-config.json . Compruebe que:

   • data-source.connection-string usa @env('DATABASE_CONNECTION_STRING')
   • Las entidades y los permisos son correctos

   Importante

   No inserte cadenas de conexión literales ni secretos en dab-config.json. Use la @env() función para que los valores se resuelvan a partir de variables de entorno en tiempo de ejecución.

Crea un manifiesto de herramienta local

Use un manifiesto de herramienta de .NET local para que el paquete de implementación incluya DAB como dependencia del proyecto. Este enfoque evita depender de una herramienta instalada globalmente dentro de App Service.

1. Cree un manifiesto de herramienta local de .NET en el directorio de su proyecto.

   dotnet new tool-manifest
   

2. Instale Data API Builder como una herramienta local.

   dotnet tool install microsoft.dataapibuilder --prerelease
   

3. Compruebe que el manifiesto existe en .config/dotnet-tools.json.

   Nota:

   La --prerelease marca instala la versión preliminar más reciente de Data API Builder. Quite la marca para instalar la versión estable más reciente en su lugar.

Realiza una prueba local

Antes de implementar en Azure, confirme que el tiempo de ejecución se inicia y los puntos de conexión funcionan.

1. Establezca el cadena de conexión como una variable de entorno local.

   PowerShell

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

   Bash

   export DATABASE_CONNECTION_STRING="<your-connection-string>"
   

2. Inicie el entorno de ejecución de DAB localmente.

   dab start
   

3. Pruebe el punto de conexión REST; para ello, vaya a la interfaz de usuario de Swagger o realice una solicitud a /api/<entity-name>.

4. Pruebe el punto de conexión de GraphQL en /graphql.

5. Detenga el tiempo de ejecución después de comprobar todos los puntos de conexión.

Creación de los recursos de App Service

Cree los recursos de Azure necesarios para hospedar DAB en App Service.

1. Crear un nuevo grupo de recursos. Este grupo de recursos se usa para todos los recursos nuevos de esta guía.

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

   Tip

   Considere la posibilidad de asignar un nombre al grupo de recursos msdocs-dab-appservice.

2. Creación de un plan de App Service.

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

   Nota:

   En esta guía se usa el nivel B1 (Básico) en Linux.

3. Cree la aplicación web con el entorno de ejecución de .NET 8.

   az webapp create \
     --name <app-name> \
     --resource-group <resource-group-name> \
     --plan <plan-name> \
     --runtime "DOTNETCORE:8.0"
   

   Tip

   Valide los entornos de ejecución disponibles para el plan con az webapp list-runtimes --os linux.

Configuración de las opciones de App Service

Configure las variables de entorno y el comando de inicio que App Service necesita para ejecutar DAB.

1. Configure el proveedor de autenticación para App Service. Esta configuración indica a DAB que confíe en la autenticación integrada de App Service (Autenticación sencilla) para obtener información de identidad.

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

2. Establezca la cadena de conexión de la base de datos como una configuración de aplicación de App Service.

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

   Tip

   Use un cadena de conexión que no incluya secretos. En su lugar, use identidades administradas y la autenticación de Microsoft Entra para administrar el acceso entre su base de datos y App Service. Para más información, consulte Servicios de Azure que usan identidades administradas.

3. Cree un script de inicio que restaure el manifiesto de herramienta local e inicie DAB. Cree un archivo denominado startup.sh en el directorio del proyecto.

   #!/bin/sh
   dotnet tool restore
   dotnet tool run dab start
   

   Importante

   Asegúrese startup.sh de que usa finales de línea LF (Unix), no CRLF. Los editores de Windows pueden guardar con CRLF de forma predeterminada, lo que hace que el script falle en el host de Linux App Service.

4. Establezca el comando de inicio en App Service.

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

Despliegue en Azure App Service

Empaquete los archivos del proyecto e impleméntelos en App Service mediante la implementación ZIP.

1. Cree un paquete de implementación que contenga los archivos del proyecto. Como mínimo, incluya:

   • dab-config.json
   • .config/dotnet-tools.json
   • startup.sh
   PowerShell

   Compress-Archive -Path dab-config.json, .config, startup.sh -DestinationPath deploy.zip -Force
   

   Bash

   zip -r deploy.zip dab-config.json .config startup.sh
   

   Importante

   El ARCHIVO ZIP debe contener archivos en el nivel raíz. No comprima una carpeta primaria que contenga los archivos. La raíz de archivo debe incluir dab-config.json, .config/y startup.sh directamente.

2. Implemente el paquete ZIP en App Service.

   az webapp deploy \
     --resource-group <resource-group-name> \
     --name <app-name> \
     --src-path deploy.zip \
     --type zip
   

Comprobación de la implementación

Después de la implementación, confirme que DAB se inicia correctamente en App Service.

1. Abra la dirección URL de App Service.

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

2. Compruebe el punto de comprobación de salud.

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

3. Pruebe los puntos de conexión REST y GraphQL mediante las mismas rutas de acceso de entidad que ha probado localmente. La aplicación implementada usa el mismo dab-config.json, por lo que el comportamiento del punto de conexión debe coincidir con el tiempo de ejecución local.

4. Si algún punto de conexión devuelve un error inesperado, habilite el registro de aplicaciones y revise los registros.

   az webapp log config \
     --name <app-name> \
     --resource-group <resource-group-name> \
     --application-logging filesystem \
     --level information
   
   az webapp log tail \
     --name <app-name> \
     --resource-group <resource-group-name>
   

Configuración de la autenticación (opcional)

Proteja el punto de conexión de App Service con Microsoft Entra ID para su uso en producción.

Para ver los pasos detallados, consulte la Configuración de la autenticación de App Service.

Importante

El proveedor de autenticación AppService en dab-config.json confía en los encabezados que inserta la autenticación de App Service. Asegúrese de que la autenticación de App Service está habilitada al usar este proveedor en producción. Para obtener más información, consulte Easy Auth (App Service) (Autenticación sencilla [App Service]).

Nota:

La autenticación de App Service protege la entrada al punto de conexión. Los permisos de entidad DAB siguen regir las operaciones que permite el entorno de ejecución. Si desea el acceso basado en roles, actualice los permisos de entidad para usar roles específicos en lugar de anonymous:*.

Limpieza de recursos

Cuando ya no necesite la aplicación o los recursos de ejemplo, quite la implementación correspondiente y todos los recursos.

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

Contenido relacionado

• Autenticación de Easy Auth (App Service)
• Referencia del archivo de configuración
• Configuración del host de tiempo de ejecución y autenticación
• Implementación en Azure Container Apps
• Integración con Application Insights