Configuración de la conexión a bases de datos en Azure Static Web Apps (versión preliminar)

Las conexiones de base de datos de Azure Static Web Apps funcionan con varias bases de datos de Azure.

A medida que conecta una base de datos a la aplicación web estática, debe configurar el firewall de la base de datos para aceptar el acceso de red desde los procesos de trabajo de Static Web Apps al permitir el acceso de red desde recursos de Azure. No se admite la habilitación de direcciones IP específicas de Static Web Apps.

Si usa el tipo de autenticación de identidad administrada, debe configurar el perfil de identidad administrada de la aplicación web estática para acceder a la base de datos.

Use esta tabla para obtener detalles sobre la configuración de firewall y Managed Identity de la base de datos.

Nombre Tipo Cortafuegos Identidad administrada
Azure Cosmos DB Estándar Configurar firewall Configurar identidad administrada
Azure SQL Estándar Configurar el firewall Configurar identidad administrada
Azure Database for MySQL Flex Configurar el firewall No compatible
Azure Database para PostgreSQL Flex Configurar el firewall No compatible
Azure Database for PostgreSQL (único) Soltero Configurar firewall Configurar identidad administrada

Configuración

Define el comportamiento en tiempo de ejecución de la conexión de base de datos en el archivo staticwebapp.database.config.json. Antes de vincular una base de datos a la aplicación web estática, debe crear este archivo en el repositorio. Por convención, este archivo existe en la carpeta swa-db-connections en la raíz del repositorio, pero puede reubicarlo si lo desea.

El propósito del archivo de configuración es el de:

  • Asignar rutas de acceso fuera del punto de conexión de /data-api a las tablas o entidades de la base de datos
  • Exponer endpoints REST o GraphQL (o ambos)
  • Definir reglas de seguridad de entidad
  • Control de las opciones de configuración de desarrollo

Si usa Azure Cosmos DB con GraphQL, también debe proporcionar un gql archivo de esquema.

Nota

Las conexiones de base de datos de Static Web Apps requieren una carpeta que contenga los archivos de configuración. Esta carpeta debe contener el archivo de configuración de staticwebapp.database.config.json para todos los tipos de base de datos. En el caso de las bases de datos NoSQL de Cosmos DB, también se requiere un archivo de esquema staticwebapp.database.schema.gql.

Por convención, esta carpeta se denomina swa-db-connections y se coloca en la raíz del repositorio. Esta convención se puede anular con un custom-configuration-folder.

Archivo de configuración de ejemplo

El siguiente archivo de configuración de ejemplo muestra cómo conectarse a una base de datos de Azure SQL y exponer puntos de conexión de REST y GraphQL. Para obtener información completa sobre el archivo de configuración y sus características admitidas, consulte la documentación de Data API Builder.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": false 
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/rest"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "production",
      "cors": {
        "origins": ["http://localhost:4280"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {
    "Person": {
      "source": "dbo.MyTestPersonTable",
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete"],
          "role": "anonymous"
        }
      ]
    }
  }
}
Propiedad Descripción
$schema La versión de Database API builder que usa Azure Static Web Apps para interpretar el archivo de configuración.
data-source Opciones de configuración específicas de la base de datos de destino. La propiedad database-type acepta mssql, postgresql, cosmosdb_nosql o mysql.

La cadena de conexión se sobrescribe tras la implementación cuando una base de datos está conectada al recurso de Static Web Apps. Durante el desarrollo local, la cadena de conexión definida en el archivo de configuración es lo que se usa para conectarse a la base de datos.
runtime Sección que define los puntos de conexión expuestos. Las propiedades rest y graphql controlan el fragmento de dirección URL usado para acceder al protocolo de API correspondiente. En la host sección de configuración se definen las opciones específicas del entorno de desarrollo. Asegúrese de que la matriz de origins incluya la dirección y el puerto de localhost. El host.mode se sobrescribe en production cuando se conecta una base de datos al recurso de Static Web Apps.
entities Sección que asigna la ruta de acceso URL a las entidades y tablas de base de datos. Las mismas reglas de autenticación basadas en roles que se usan para proteger las rutas de acceso también protegen las entidades de base de datos y se pueden usar para definir permisos para cada entidad. El objeto entities también especifica las relaciones entre entidades.

Generar archivo de configuración

La CLI de Static Web Apps permite generar una plantilla de archivo de configuración.

Importante

Para mejorar la seguridad de las implementaciones de la CLI de Static Web Apps, se introdujo un cambio importante que requiere que actualice a la versión más reciente (2.0.2) de la CLI de Static Web Apps antes del 15 de enero de 2025.

Utilice el swa db init --database-type <YOUR_DATABASE_TYPE> para generar un archivo de configuración. De forma predeterminada, la CLI crea un nuevo staticwebapp.database.config.json en una carpeta denominada swa-db-connections.

Entre los tipos de base de datos admitidos se incluyen:

  • mssql
  • postgresql
  • cosmosdb_nosql
  • mysql

Carpeta de configuración personalizada

El nombre de carpeta predeterminado del archivo staticwebapp.database.config.json es swa-db-connections. Si desea usar una carpeta diferente, debe actualizar el archivo de flujo de trabajo para indicar al entorno de ejecución de aplicaciones web estáticas dónde encontrar el archivo de configuración. La propiedad data_api_location permite definir la ubicación de la carpeta de configuración.

Nota

La carpeta que contiene el archivo staticwebapp.database.config.json debe estar en la raíz del repositorio de aplicaciones web estáticas.

En el código siguiente se muestra cómo usar una carpeta denominada db-config para el archivo de configuración de base de datos.

app_location: "/src"
api_location: "api"
output_location: "/dist"
data_api_location: "db-config" # Folder holding the staticwebapp.database.config.json file

Configurar la conectividad de la base de datos

Azure Static Web Apps deben tener acceso de red a la base de datos para que funcionen las conexiones de base de datos. Además, para usar una base de datos de Azure para el desarrollo local, debe configurar la base de datos para permitir las solicitudes desde su propia dirección IP. Los siguientes son pasos genéricos que se aplican a todas las bases de datos. Para conocer los pasos específicos del tipo de base de datos, consulte los vínculos anteriores.

  • Vaya a la base de datos en Azure Portal.
  • Vaya a la pestaña Redes.
  • En la sección Reglas de firewall, seleccione Agregar la dirección IPv4 de cliente. Este paso garantiza que se pueda usar esta base de datos para el desarrollo local.
  • Seleccione la casilla Permitir que los servicios y recursos de Azure accedan a este servidor. Este paso garantiza que el recurso de Static Web Apps implementado pueda acceder a la base de datos.
  • Seleccione Guardar.

Conectar una base de datos

La vinculación de una base de datos a tu aplicación web estática establece la conexión de producción entre tu sitio web y tu base de datos cuando se publica en Azure.

  1. Abra la aplicación web estática en el portal de Azure.

  2. En la sección Configuración, seleccione Conexión de base de datos.

  3. En la sección Producción, seleccione el vínculo Vincular base de datos existente.

  4. En la ventana Vincular base de datos existente, escriba los valores siguientes:

    Propiedad Importancia
    Tipo de base de datos Seleccione el tipo de base de datos en la lista desplegable.
    Suscripción Seleccione la suscripción de Azure en la lista desplegable.
    Nombre de recurso Seleccione el nombre del servidor de bases de datos que tiene la base de datos deseada.
    Nombre de la base de datos Seleccione el nombre de la base de datos que quiere vincular a su aplicación web estática.
    Tipo de autenticación Seleccione el tipo de conexión necesario para conectarse a la base de datos.

Contenido relacionado

Agregue una base de datos a la aplicación web estática usando una de las siguientes bases de datos:

Además, puede obtener información sobre cómo usar Data API builder con Azure Static Web Apps.

  • Se actualizó por última vez el