Configurazione della connessione al database in App Web statiche di Azure (anteprima)

Le connessioni al database di Azure Static Web Apps funzionano con vari database di Azure.

Quando si connette un database all'app Web statica, è necessario configurare il firewall del database per accettare l'accesso di rete dai worker di App Web statiche consentendo l'accesso alla rete dalle risorse di Azure. L'autorizzazione di indirizzi IP specifici di App Web statiche non è supportata.

Se si usa il tipo di autenticazione identità gestita, è necessario configurare il profilo di identità gestita dell'app Web statica per accedere al database.

Usare questa tabella per informazioni dettagliate sulla configurazione del firewall e dell'identità gestita per il database.

Nome TIPO Muro di Fuoco Identità gestita
Azure Cosmos DB Normale Configura il firewall Configurare l'identità gestita
SQL Azure Normale Configurare il firewall Configurare l'identità gestita
Database di Azure per MySQL Flex Configurare il firewall Non supportato
Database di Azure per PostgreSQL Flex Configurare il firewall Non supportato
Database di Azure per PostgreSQL (singolo) Singolo Configura il firewall Configurare l'identità gestita

Configurazione

Si definisce il comportamento di runtime della connessione al database nel file staticwebapp.database.config.json. Prima di collegare un database all'app Web statica, è necessario creare questo file all'interno del repository. Per convenzione, questo file esiste nella cartella swa-db-connections nella radice del repository, ma è possibile rilocarlo se lo si desidera.

Lo scopo del file di configurazione è:

  • Eseguire il mapping dei percorsi esposti nell'endpoint /data-api alle tabelle o alle entità del database
  • Esporre endpoint REST o GraphQL (o entrambi)
  • Definire le regole di sicurezza delle entità
  • Controllare le impostazioni di configurazione dello sviluppo

Se si usa Azure Cosmos DB con GraphQL, è necessario specificare anche un gql file di schema.

Nota

Le connessioni al database di App Web statiche richiedono una cartella contenente i file di configurazione. Questa cartella deve contenere il file di configurazione staticwebapp.database.config.json per tutti i tipi di database. Per i database Cosmos DB for NoSQL, è necessario anche un file di schema staticwebapp.database.schema.gql.

Per convenzione, questa cartella è denominata swa-db-connections e posizionata nella radice del repository. Questa convenzione può essere sovrascritta con una custom-configuration-folder.

File di configurazione di esempio

Il file di configurazione di esempio seguente illustra come connettersi a un database SQL di Azure ed esporre endpoint REST e GraphQL. Per informazioni dettagliate sul file di configurazione e sulle relative funzionalità supportate, vedere la documentazione di 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"
        }
      ]
    }
  }
}
Proprietà Descrizione
$schema Versione del Database API builder usata da App Web statiche di Azure per interpretare il file di configurazione.
data-source Impostazioni di configurazione specifiche del database di destinazione. La database-type proprietà accetta mssql, postgresql, cosmosdb_nosqlo mysql.

La stringa di connessione viene sovrascritta al momento della distribuzione quando un database è connesso alla risorsa App Web statiche. Durante lo sviluppo locale, la stringa di connessione definita nel file di configurazione è ciò che viene usato per connettersi al database.
runtime Sezione che definisce gli endpoint esposti. Le proprietà rest e graphql controllano il frammento di URL usato per accedere al rispettivo protocollo API. La host sezione di configurazione definisce le impostazioni specifiche dell'ambiente di sviluppo. Assicurarsi che l'origins array includa l'indirizzo localhost e la porta. Il file host.mode viene sovrascritto in production quando un database è connesso alla risorsa App Web statiche.
entities Sezione che esegue il mapping del percorso URL alle entità e alle tabelle di database. Le stesse regole di autenticazione basate sui ruoli usate per proteggere i percorsi proteggono anche le entità di database e possono essere usate per definire le autorizzazioni per ogni entità. L'oggetto entità specifica anche le relazioni tra entità.

Genera il file di configurazione

La App Web statiche CLI consente di generare uno stub del file di configurazione.

Importante

Per migliorare la sicurezza delle distribuzioni da App Web statiche CLI, è stata introdotta una modifica di rilievo che richiede l'aggiornamento alla versione più recente (2.0.2) di App Web statiche CLI entro il 15 gennaio 2025.

Usare swa db init --database-type <YOUR_DATABASE_TYPE> per generare un file di configurazione. Per impostazione predefinita, l'interfaccia della riga di comando crea un nuovo staticwebapp.database.config.json in una cartella denominata swa-db-connections.

I tipi di database supportati includono:

  • mssql
  • postgresql
  • cosmosdb_nosql
  • mysql

Cartella di configurazione personalizzata

Il nome predefinito della cartella per il file staticwebapp.database.config.json è swa-db-connections. Se si vuole usare una cartella diversa, è necessario aggiornare il file del flusso di lavoro per indicare al runtime delle app Web statiche dove trovare il file di configurazione. La data_api_location proprietà consente di definire il percorso della cartella di configurazione.

Nota

La cartella che contiene il file staticwebapp.database.config.json deve trovarsi nella radice del repository delle app Web statiche.

Il codice seguente illustra come usare una cartella denominata db-config per il file di configurazione del database.

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

Configurare la connettività del database

App Web statiche di Azure devono disporre dell'accesso di rete al database per consentire il funzionamento delle connessioni al database. Inoltre, per usare un database di Azure per lo sviluppo locale, è necessario configurare il database per consentire le richieste provenienti dal proprio indirizzo IP. Di seguito sono riportati i passaggi generici che si applicano a tutti i database. Per i passaggi specifici per il tipo di database, vedere i collegamenti precedenti.

  • Passare al database nel portale di Azure.
  • Passare alla scheda Rete.
  • Nella sezione Regole del firewall selezionare Aggiungi l'indirizzo IPv4 del client. Questo passaggio garantisce che sia possibile usare questo database per lo sviluppo locale.
  • Selezionare la casella di controllo Consenti a servizi e risorse di Azure di accedere a questo server . Questo passaggio garantisce che la risorsa App Web statiche distribuita possa accedere al database.
  • Seleziona Salva.

Connettere un database

Il collegamento di un database all'app Web statica stabilisce la connessione di produzione tra il sito Web e il database quando il sito Web viene pubblicato in Azure.

  1. Aprire l'app Web statica nel portale di Azure.

  2. Nella sezione Impostazioni selezionare Connessione database.

  3. Nella sezione Produzione, selezionare il collegamento Collega database esistente.

  4. Nella finestra Collega database esistente immettere i valori seguenti:

    Proprietà Valore
    Tipo di database Selezionare il tipo di database dall'elenco a discesa.
    Abbonamento Selezionare la sottoscrizione di Azure dall'elenco a discesa.
    Nome della risorsa Selezionare il nome del server di database con il database desiderato.
    Nome del database Selezionare il nome del database da collegare all'app Web statica.
    Tipo di autenticazione Selezionare il tipo di connessione necessario per connettersi al database.

Contenuto correlato

Aggiungere un database all'app Web statica usando uno dei database seguenti:

È anche possibile ottenere informazioni su come usare Data API builder con App Web statiche di Azure.

  • Ultimo aggiornamento: