Creación de archivos de configuración para Data API Builder

Completados

Data API Builder (DAB) es un motor multiplataforma de código abierto que crea puntos de conexión REST y GraphQL modernos para la base de datos sin necesidad de escribir código personalizado. Con un único archivo de configuración, puede exponer los objetos de base de datos a través de API seguras y escalables que admiten la autenticación, la autorización y el almacenamiento en caché.

Si trabaja con bases de datos SQL de Azure o bases de datos SQL en Microsoft Fabric, probablemente se haya enfrentado a solicitudes para hacer que sus datos sean accesibles para los desarrolladores de aplicaciones. La creación de capas de API personalizadas tarda tiempo y agrega sobrecarga de mantenimiento. Data API Builder elimina ese trabajo mediante la generación de API directamente desde el esquema de la base de datos.

Descripción del archivo de configuración de Data API Builder

Todo en Data API Builder comienza con un archivo de configuración. Este archivo JSON indica a DAB cómo conectarse a la base de datos, qué objetos exponer, cómo controlar la autenticación y cómo comportarse en tiempo de ejecución. Cuando se inicia DAB, lee esta configuración y genera automáticamente los puntos de conexión REST y GraphQL.

Un archivo de configuración típico tiene cuatro secciones principales:

  • $schema : hace referencia al esquema JSON para la validación e compatibilidad con IntelliSense
  • origen de datos : define la cadena y el tipo de conexión de la base de datos.
  • runtime : controla el comportamiento en tiempo de ejecución, como la configuración del host, la autenticación y el almacenamiento en caché.
  • entities : especifica los objetos de base de datos que se van a exponer y cómo configurarlos.

Esta es una estructura básica del archivo de configuración:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.1.7/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "cors": {
        "origins": ["http://localhost:3000"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {}
}

¿Te has dado cuenta de la propiedad $schema en la parte superior? Esto habilita el autocompletado y la validación en el editor mientras escribe. Use siempre la versión de esquema que coincida con la instalación de DAB.

Configuración de la conexión del origen de datos

En la data-source sección se indica a DAB cómo conectarse a la base de datos. En el caso de las bases de datos SQL Server, Azure SQL Database y SQL en Microsoft Fabric, se usa mssql como tipo de base de datos.

"data-source": {
  "database-type": "mssql",
  "connection-string": "@env('DATABASE_CONNECTION_STRING')",
  "options": {
    "set-session-context": true
  }
}

Puede colocar la cadena de conexión directamente en el archivo de configuración, pero no. Use la @env() sintaxis en su lugar para hacer referencia a variables de entorno. Esto mantiene las credenciales fuera de los archivos de configuración y el control de código fuente.

Vale la pena destacar la set-session-context opción. Cuando está habilitada, DAB pasa información de identidad de usuario a SQL Server a través del contexto de sesión. Los procedimientos almacenados y las funciones pueden leer esta información mediante SESSION_CONTEXT(), lo que resulta útil para implementar el registro de auditoría o seguridad de nivel de fila.

Sugerencia

Para el desarrollo local, puede usar el comando dab init con el parámetro --connection-string para configurar rápidamente el archivo de configuración inicial.

Configuración de opciones en tiempo de ejecución

La sección runtime controla cómo funciona DAB al atender solicitudes. Aquí puede configurar los puntos de conexión REST y GraphQL por separado, junto con la configuración global del host, como CORS y el almacenamiento en caché.

"runtime": {
  "rest": {
    "enabled": true,
    "path": "/api",
    "request-body-strict": true
  },
  "graphql": {
    "enabled": true,
    "path": "/graphql",
    "allow-introspection": true
  },
  "host": {
    "cors": {
      "origins": ["https://myapp.azurewebsites.net"],
      "allow-credentials": true
    },
    "mode": "production"
  },
  "cache": {
    "enabled": true,
    "ttl-seconds": 5
  }
}

Las path propiedades definen la ruta base de la URL de cada tipo de API. Los puntos de conexión REST aparecen en /api/EntityName, mientras que las consultas de GraphQL van a /graphql. La allow-introspection configuración de GraphQL determina si los clientes pueden consultar el propio esquema, lo que resulta útil durante el desarrollo, pero a menudo deben deshabilitarse en producción para la seguridad.

La configuración de CORS (uso compartido de recursos entre orígenes) en la sección host especifica qué dominios pueden llamar a la API desde aplicaciones basadas en navegador. La mode propiedad cambia entre development y production comportamiento, lo que afecta a características como mensajes de error detallados.

Uso de la CLI de DAB para la administración de configuración

La CLI de Data API Builder proporciona comandos para crear y modificar archivos de configuración sin edición manual de JSON. Este enfoque reduce los errores y garantiza la sintaxis de configuración válida.

Para crear un nuevo archivo de configuración:

dab init --database-type mssql --connection-string "@env('DATABASE_CONNECTION_STRING')" --host-mode development

Este comando crea un dab-config.json archivo en el directorio actual con la configuración de línea base. Desde allí, puede agregar entidades mediante comandos de la CLI o editar el archivo directamente.

Para agregar una entidad para una tabla:

dab add Product --source dbo.Products --permissions "anonymous:read"

La CLI controla el formato JSON y valida la configuración en el esquema automáticamente. Si trabaja en un equipo, el uso de comandos de la CLI también facilita las revisiones de solicitudes de incorporación de cambios, ya que el formato sigue siendo coherente.

Importante

Almacene siempre los archivos de configuración en el control de código fuente, pero nunca registre cadenas de conexión reales. Utilice referencias de variables de entorno, y administre credenciales mediante mecanismos seguros, como Azure Key Vault o secretos de canalización de implementación.

Organización de la configuración de varios entornos

La mayoría de los proyectos necesitan una configuración diferente para el desarrollo, el almacenamiento provisional y la producción. Es posible que desee habilitar la introspección durante el desarrollo, pero deshabilitarla en producción, o diferentes orígenes CORS para cada entorno.

DAB admite esto a través de la fusión de configuraciones. Comience con un archivo base dab-config.json que contenga la configuración compartida y luego cree modificaciones específicas del entorno:

  • dab-config.development.json - Configuración específica del desarrollo
  • dab-config.staging.json - Configuración del entorno de ensayo
  • dab-config.production.json - Configuración de producción

Al iniciar DAB con el --config parámetro , combina la configuración del archivo con la configuración base:

dab start --config dab-config.production.json

Los archivos específicos del entorno solo necesitan contener configuraciones que difieren de la base. DAB controla la combinación automáticamente, con valores específicos del entorno que tienen prioridad sobre la configuración base.