Freigeben über

Konfiguration der Datenbankverbindung in Azure Static Web Apps (Vorschau)

  • Artikel

Azure Static Web Apps-Datenbankverbindungen funktionieren mit verschiedenen Azure-Datenbanken.

Wenn Sie eine Datenbank mit Ihrer statischen Web-App verbinden, müssen Sie die Firewall Ihrer Datenbank so konfigurieren, dass der Netzwerkzugriff von den Static Web Apps-Workern akzeptiert wird, indem Sie den Netzwerkzugriff von Azure-Ressourcen zulassen. Das Zulassen bestimmter IP-Adressen für Static Web Apps wird nicht unterstützt.

Wenn Sie den Authentifizierungstyp „Verwaltete Identität“ verwenden, müssen Sie das Profil der verwalteten Identität Ihrer statischen Web-App für den Zugriff auf Ihre Datenbank konfigurieren.

In dieser Tabelle finden Sie Details zur Konfiguration der Firewall und der verwalteten Identität für Ihre Datenbank.

Name type Firewall Verwaltete Identität
Azure Cosmos DB Standard Konfigurieren der Firewall Konfigurieren einer verwalteten Identität
Azure SQL Standard Konfigurieren der Firewall Konfigurieren einer verwalteten Identität
Azure Database for MySQL Flex Konfigurieren der Firewall Nicht unterstützt
Azure-Datenbank für PostgreSQL Flex Konfigurieren der Firewall Nicht unterstützt
Azure Database for PostgreSQL (Single) Single Konfigurieren der Firewall Konfigurieren einer verwalteten Identität

Konfiguration

Sie definieren das Runtimeverhalten der Datenbankverbindung in der Datei staticwebapp.database.config.json. Bevor Sie eine Datenbank mit Ihrer statischen Web-App verknüpfen, müssen Sie diese Datei in Ihrem Repository erstellen. Standardmäßig befindet sich diese Datei im Ordner swa-db-connections im Stammverzeichnis Ihres Repositorys, aber Sie können sie auch verschieben.

Der Zweck der Konfigurationsdatei ist es:

  • Pfade vom Endpunkt /data-api Ihren Datenbanktabellen oder Entitäten zuzuordnen
  • REST- oder GraphQL-Endpunkte (oder beides) verfügbar zu machen
  • Sicherheitsregeln für Entitäten zu definieren
  • Einstellungen der Entwicklungskonfiguration zu steuern

Wenn Sie Azure Cosmos DB mit GraphQL verwenden, müssen Sie auch eine gql-Schemadatei bereitstellen.

Hinweis

Static Web Apps-Datenbankverbindungen erfordern einen Ordner mit den Konfigurationsdateien. Dieser Ordner muss die Konfigurationsdatei staticwebapp.database.config.json für alle Datenbanktypen enthalten. Für Cosmos DB für NoSQL-Datenbanken ist auch die Schemadatei staticwebapp.database.schema.gql erforderlich.

Dieser Ordner heißt standardmäßig swa-db-connections und befindet sich im Stammverzeichnis des Repositorys. Diese Konvention kann mit einem benutzerdefinierten Konfigurationsordner außer Kraft gesetzt werden.

Beispiel für eine Konfigurationsdatei

Die folgende Beispielkonfigurationsdatei zeigt, wie Sie eine Verbindung mit einer Azure SQL-Datenbank herstellen und sowohl REST- als auch GraphQL-Endpunkte verfügbar machen. Ausführliche Informationen zu der Konfigurationsdatei und den unterstützten Funktionen finden Sie in der Dokumentation zum Daten-API-Generator.

{
  "$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"
        }
      ]
    }
  }
}
Eigenschaft Beschreibung
$schema Die vom Datenbank-API-Generator verwendete Version von Azure Static Web Apps, um die Konfigurationsdatei zu interpretieren.
data-source Konfigurationseinstellungen, die für die Zieldatenbank spezifisch sind. Die Eigenschaft database-type akzeptiert mssql, postgresql, cosmosdb_nosql oder mysql.

Die Verbindungszeichenfolge wird bei der Bereitstellung überschrieben, wenn eine Datenbank mit Ihrer Static Web Apps-Ressource verbunden ist. Während der lokalen Entwicklung wird die in der Konfigurationsdatei definierte Verbindungszeichenfolge verwendet, um eine Verbindung mit der Datenbank herzustellen.
runtime Abschnitt, der die verfügbar gemachten Endpunkte definiert. Die Eigenschaften rest und graphql steuern das URL-Fragment, das für den Zugriff auf das jeweilige API-Protokoll verwendet wird. Im Konfigurationsabschnitt host sind Einstellungen definiert, die für Ihre Entwicklungsumgebung spezifisch sind. Stellen Sie sicher, dass das origins-Array Ihre Localhost-Adresse und Ihren Port enthält. „host.mode“ wird mit production überschrieben, wenn eine Datenbank mit Ihrer Static Web Apps-Ressource verbunden ist.
entities Abschnitt, der den URL-Pfad den Datenbankentitäten und -tabellen zuordnet. Die gleichen rollenbasierten Authentifizierungsregeln, die zur Sicherung von Pfaden verwendet werden, sichern auch Datenbankentitäten und können zum Festlegen von Berechtigungen für jede Entität verwendet werden. Das Entitätsobjekt legt auch die Beziehungen zwischen Entitäten fest.

Konfigurationsdateien generieren

Mit der Static Web Apps CLI können Sie einen Konfigurationsdatei-Stub generieren.

Wichtig

Um die Sicherheit von Bereitstellungen aus der Static Web Apps CLI zu verbessern, wurde ein Breaking Change eingeführt, der es erforderlich macht, bis zum 15. Januar 2025 ein Upgrade auf die neueste Version (2.0.2) der Static Web Apps CLI durchzuführen.

Verwenden Sie swa db init --database-type <YOUR_DATABASE_TYPE>, um eine Konfigurationsdatei zu generieren. Standardmäßig erstellt die CLI die neue Datei staticwebapp.database.config.json in einem Ordner mit dem Namen swa-db-connections.

Zu den unterstützten Datenbanktypen gehören:

  • mssql
  • postgresql
  • cosmosdb_nosql
  • mysql

Benutzerdefinierter Konfigurationsordner

Der Name des Standardordners für die Datei staticwebapp.database.config.json lautet swa-db-connections. Wenn Sie einen anderen Ordner verwenden möchten, müssen Sie Ihre Workflowdatei aktualisieren, um der Static Web Apps-Runtime mitzuteilen, wo sich Ihre Konfigurationsdatei befindet. Mit der Eigenschaft data_api_location können Sie den Speicherort Ihres Konfigurationsordners festlegen.

Hinweis

Der Ordner, der die Datei staticwebapp.database.config.json enthält, muss sich im Stammverzeichnis Ihres Repositorys für statische Web-Apps befinden.

Der folgende Code zeigt, wie Sie einen Ordner namens db-config für die Datenbankkonfigurationsdatei verwenden.

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

Konfigurieren der Datenbankkonnektivität

Azure Static Web Apps benötigt Netzwerkzugriff auf Ihre Datenbank, damit Datenbankverbindungen funktionieren. Um eine Azure-Datenbank für die lokale Entwicklung zu verwenden, müssen Sie Ihre Datenbank zudem so konfigurieren, dass Anforderungen von Ihrer eigenen IP-Adresse zugelassen werden. Im Folgenden finden Sie allgemeine Schritte, die für alle Datenbanken gelten. Spezifische Schritte für Ihren Datenbanktyp finden Sie unter den oben genannten Links.

  • Rufen Sie im Azure-Portal Ihre Datenbank auf.
  • Wechseln Sie zur Registerkarte Netzwerk.
  • Wählen Sie im Abschnitt „Firewallregeln“ die Option Fügen Sie Ihre Client-IPv4-Adresse hinzu aus. Mit diesem Schritt wird sichergestellt, dass Sie diese Datenbank für Ihre lokale Entwicklung verwenden können.
  • Aktivieren Sie das Kontrollkästchen Azure-Diensten und -Ressourcen den Zugriff auf diesen Server gestatten. Mit diesem Schritt wird sichergestellt, dass Ihre bereitgestellte Static Web Apps-Ressource auf Ihre Datenbank zugreifen kann.
  • Wählen Sie Speichern.

Verbinden einer Datenbank

Beim Verknüpfen einer Datenbank mit Ihrer statischen Web-App wird die Produktionsverbindung zwischen Ihrer Website und der Datenbank hergestellt, wenn sie in Azure veröffentlicht wird.

  1. Öffnen Sie Ihre statische Web-App im Azure-Portal.

  2. Wählen Sie im Abschnitt Einstellungen die Option Datenbankverbindung aus.

  3. Wählen Sie im Abschnitt Produktion den Link Vorhandene Datenbank verknüpfen aus.

  4. Geben Sie im Fenster Vorhandene Datenbank verknüpfen die folgenden Werte ein:

    Eigenschaft Wert
    Datenbanktyp Wählen Sie in der Dropdownliste den Datenbanktyp aus.
    Subscription Wählen Sie in der Dropdownliste Ihr Azure-Abonnement aus.
    Ressourcenname Wählen Sie den Namen des Datenbankservers aus, der die gewünschte Datenbank enthält.
    Datenbankname Wählen Sie den Namen der Datenbank aus, die Sie mit Ihrer statischen Web-App verknüpfen möchten.
    Authentifizierungstyp Wählen Sie den Verbindungstyp aus, der für die Verbindung mit Ihrer Datenbank erforderlich ist.

Zugehöriger Inhalt

Fügen Sie Ihrer statischen Web-App eine der folgenden Datenbanken hinzu:

Außerdem können Sie sich über die Verwendung des Daten-API-Generators mit Azure Static Web Apps informieren.