Compartir a través de

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

  • Artículo

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 trabajos 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 más información sobre la configuración de firewall e identidad administrada de la base de datos.

Nombre Tipo Firewall Identidad administrada
Azure Cosmos DB Estándar Configuración del firewall Configuración de una identidad administrada
SQL de Azure Estándar Configuración del firewall Configuración de una identidad administrada
Azure Database for MySQL Flex Configuración del firewall No compatible
Azure Database para PostgreSQL Flex Configuración del firewall No compatible
Azure Database for PostgreSQL (único) Single Configuración del firewall Configuración de una identidad administrada

Configuración

Defina 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:

  • Asignar rutas de acceso fuera del punto de conexión de /data-api a las tablas o entidades de la base de datos
  • Exponer puntos de conexión de REST o GraphQL (o ambos)
  • Definición de 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 invalidar 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 del generador de API de datos.

{
  "$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 del Generador de API de base de datos 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 sección de configuración de host 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 una base de datos está conectada 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 un código auxiliar 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.

Use 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

Configuración de la conectividad de base de datos

Azure Static Web Apps debe 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.
  • Active 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.

Conexión de una base de datos

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

  1. Abra la aplicación web estática en Azure Portal.

  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 Value
    Tipo de base de datos Seleccione el tipo de base de datos en la lista desplegable.
    Subscription 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 la 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 mediante una de las siguientes bases de datos:

Además, puede obtener información sobre cómo usar el Generador de API de datos con Azure Static Web Apps.