Tutorial: Hinzufügen einer Azure Cosmos DB-Datenbankverbindung in Azure Static Web Apps (Vorschau)

  • Artikel

In diesem Tutorial erfahren Sie, wie Sie eine Azure Cosmos DB for NoSQL-Datenbank mit Ihrer statischen Web-App verbinden. Nach der Konfiguration können Sie GraphQL-Anforderungen an den integrierten /data-api-Endpunkt senden, um Daten zu bearbeiten, ohne Back-End-Code schreiben zu müssen.

Der Einfachheit halber wird in diesem Tutorial gezeigt, wie Sie eine Azure-Datenbank für die lokale Entwicklung verwenden. Sie können aber auch einen lokalen Datenbankserver für Ihre lokalen Entwicklungsanforderungen nutzen.

Hinweis

In diesem Tutorial erfahren Sie, wie Sie Azure Cosmos DB for NoSQL verwenden. Wenn Sie eine andere Datenbank verwenden möchten, lesen Sie die Tutorials zu Azure SQL, MySQL oder PostgreSQL.

Webbrowser mit Ergebnissen aus Cosmos DB im Entwicklertools-Konsolenfenster

In diesem Tutorial lernen Sie Folgendes:

  • Verknüpfen einer Azure Cosmos DB for NoSQL-Datenbank mit Ihrer statischen Web-App
  • Erstellen, Lesen, Aktualisieren und Löschen von Daten

Voraussetzungen

Für dieses Tutorial benötigen Sie eine vorhandene Azure Cosmos DB for NoSQL-Datenbank und eine statische Web-App.

Resource BESCHREIBUNG
Azure Cosmos DB for NoSQL-Datenbank Wenn Sie noch keine besitzen, führen Sie die Schritte im Leitfaden Erstellen einer Azure Cosmos DB-Datenbank aus.
Vorhandene statische Web-App Wenn Sie noch keine besitzen, führen Sie die Schritte in der Anleitung zu den ersten Schritten aus, um eine statische Web-App ohne Framework zu erstellen.

Konfigurieren Sie zunächst Ihre Datenbank so, dass sie mit dem Feature für die Azure Static Web Apps-Datenbankverbindung funktioniert.

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.

  1. Navigieren Sie im Azure-Portal zu Ihrem Azure Cosmos DB for NoSQL-Konto.

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

  3. Wählen Sie im Abschnitt Öffentlicher Zugriff die Option Alle Netzwerke aus. Mit dieser Aktion können Sie die Clouddatenbank für die lokale Entwicklung verwenden, damit Ihre bereitgestellte Static Web Apps-Ressource auf Ihre Datenbank zugreifen kann und Sie Ihre Datenbank über das Portal abfragen können.

  4. Wählen Sie Speichern aus.

Abrufen der Datenbankverbindungszeichenfolge für die lokale Entwicklung

Um Ihre Azure-Datenbank für die lokale Entwicklung zu verwenden, müssen Sie die Verbindungszeichenfolge Ihrer Datenbank abrufen. Sie können diesen Schritt überspringen, wenn Sie eine lokale Datenbank für Entwicklungszwecke verwenden möchten.

  1. Navigieren Sie im Azure-Portal zu Ihrem Azure Cosmos DB for NoSQL-Konto.

  2. Wählen Sie im Abschnitt Einstellungen die Option Schlüssel aus.

  3. Kopieren Sie im Feld PRIMÄRE VERBINDUNGSZEICHENFOLGE die Verbindungszeichenfolge, und fügen Sie sie in einen Text-Editor ein.

Erstellen von Beispieldaten

Erstellen Sie eine Beispieltabelle, und füllen Sie sie dem Tutorial entsprechend mit Beispieldaten.

  1. Wählen Sie im linken Navigationsfenster Daten-Explorer aus.

  2. Wählen Sie Neuer Container aus. Geben Sie die Datenbank-ID für Create new und MyTestPersonDatabase als Wert ein.

  3. Geben Sie die Container-ID von MyTestPersonContainer ein.

  4. Geben Sie den Partitionsschlüssel id ein. (Dieser Wert wird mit dem Präfix / versehen.)

  5. Klicken Sie auf OK.

  6. Wählen Sie den Container MyTestPersonContainer aus.

  7. Wählen Sie die zugehörigen Elemente aus.

  8. Wählen Sie Neues Element aus, und geben Sie den folgenden Wert ein:

    {
    "id": "1",
    "Name": "Sunny"
}

Konfigurieren der statischen Web-App

Der Rest dieses Tutorials konzentriert sich auf das Bearbeiten des Quellcodes Ihrer statischen Web-App, um Datenbankverbindungen lokal zu verwenden.

Wichtig

Bei den folgenden Schritten wird davon ausgegangen, dass Sie die statische Web-App verwenden, die im Leitfaden zu den ersten Schritten erstellt wurde. Wenn Sie ein anderes Projekt verwenden, passen Sie die folgenden Git-Befehle unbedingt an Ihre Branchnamen an.

  1. Wechseln Sie in den main-Branch.

    git checkout main

  2. Synchronisieren Sie mithilfe von git pull Ihre lokale Version mit den Elementen auf GitHub.

    git pull origin main

Erstellen der Datenbankkonfigurationsdatei

Erstellen Sie als Nächstes die Konfigurationsdatei, die Ihre statische Web-App für die Verbindung mit der Datenbank verwendet.

  1. Öffnen Sie Ihr Terminal, und erstellen Sie eine neue Variable, die Ihre Verbindungszeichenfolge enthält. Die spezifische Syntax kann je nach verwendetem Shelltyp variieren.

    export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'

    Ersetzen Sie <YOUR_CONNECTION_STRING> unbedingt durch den Wert der Verbindungszeichenfolge, den Sie im Text-Editor gespeichert haben.

  2. Verwenden Sie npm, um die Static Web Apps-CLI zu installieren oder zu aktualisieren. Wählen Sie aus, welcher Befehl für Ihre Situation am besten geeignet ist.

    Verwenden Sie npm install zum Installieren.

    npm install -g @azure/static-web-apps-cli

    Verwenden Sie npm update zum Aktualisieren.

    npm update

  3. Verwenden Sie den Befehl swa db init, um eine Datenbankkonfigurationsdatei zu generieren.

    swa db init --database-type cosmosdb_nosql --cosmosdb_nosql-database MyTestPersonDatabase

    Der Befehl init erstellt die Datei staticwebapp.database.config.json im Ordner swa-db-connections.

  4. Fügen Sie dieses Beispielschema in die von Ihnen erstellte Datei staticwebapp.database.schema.gql ein.

    Da Cosmos DB for NoSQL eine schemaunabhängige Datenbank ist, können Azure Static Web Apps-Datenbankverbindungen das Schema Ihrer Datenbank nicht extrahieren. Mit der Datei staticwebapp.database.schema.gql können Sie das Schema Ihrer Cosmos DB for NoSQL-Datenbank für Static Web Apps angeben.

    type Person @model {
  id: ID
  Name: String
}

  5. Fügen Sie diese Beispielkonfiguration in die von Ihnen generierte Datei staticwebapp.database.config.json ein. Beachten Sie, dass Cosmos DB for NoSQL über weitere Optionen im Objekt data-source zum Angeben der Cosmos DB-Datenbank und der Schemadatei verfügt, die erforderlich ist, damit Datenbankverbindungen das Schema der Datenbank verstehen können.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "MyTestPersonDatabase",
      "schema": "staticwebapp.database.schema.gql"
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "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": "MyTestPersonContainer",
      "permissions": [
        {
          "actions": ["*"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Bevor Sie mit dem nächsten Schritt fortfahren, sehen Sie sich die folgende Tabelle an, in der verschiedene Aspekte der Konfigurationsdatei erläutert werden. Eine vollständige Dokumentation zur Konfigurationsdatei und zur Funktionalität, etwa zu Beziehungen und Richtlinien für die Sicherheit auf Elementebene, finden Sie in der Dokumentation zum Daten-API-Generator.

Funktion Erklärung
Datenbankverbindung In der Entwicklung liest die Runtime die Verbindungszeichenfolge aus dem Wert der Verbindungszeichenfolge in der Konfigurationsdatei. Sie können Ihre Verbindungszeichenfolge zwar direkt in der Konfigurationsdatei angeben, eine bewährte Methode besteht jedoch darin, Verbindungszeichenfolgen in einer lokalen Umgebungsvariablen zu speichern. Sie können in der Konfigurationsdatei über die Notation @env('DATABASE_CONNECTION_STRING') auf Umgebungsvariablenwerte verweisen. Der Wert der Verbindungszeichenfolge wird von Static Web Apps für die bereitgestellte Website mit den Informationen überschrieben, die beim Herstellen einer Datenbankverbindung gesammelt werden.
API-Endpunkt Der GraphQL-Endpunkt ist über /data-api/graphql verfügbar, wie in dieser Konfigurationsdatei konfiguriert. Sie können den GraphQL-Pfad konfigurieren, aber das Präfix /data-api ist nicht konfigurierbar.
API-Sicherheit Mit den runtime.host.cors-Einstellungen können Sie zulässige Ursprünge definieren, die Anforderungen an die API senden können. In diesem Fall spiegelt die Konfiguration eine Entwicklungsumgebung wider und setzt den Ort http://localhost:4280 auf die Positivliste.
Entitätsmodell Definiert die Entitäten, die über Routen als Typen im GraphQL-Schema verfügbar gemacht werden. In diesem Fall ist der Name Person der Name, der für den Endpunkt verfügbar gemacht wird. Bei entities.<NAME>.source handelt es sich um das Datenbankschema und die Tabellenzuordnung. Beachten Sie, dass der Name des API-Endpunkts nicht mit dem Tabellennamen identisch sein muss.
Entitätssicherheit Im Array entity.<NAME>.permissions aufgeführte Berechtigungsregeln steuern die Autorisierungseinstellungen für eine Entität. Sie können eine Entität mit Rollen auf die gleiche Weise schützen, wie Sie Routen mit Rollen schützen.

Hinweis

Die Eigenschaften connection-string, host.mode und graphql.allow-introspection der Konfigurationsdatei werden überschrieben, wenn Sie Ihre Website bereitstellen. Ihre Verbindungszeichenfolge wird mit den Authentifizierungsdetails überschrieben, die erfasst werden, wenn Sie Ihre Datenbank mit Ihrer Static Web Apps-Ressource verbinden. Die host.mode-Eigenschaft wird auf production und die graphql.allow-introspection-Eigenschaft auf false festgelegt. Diese Außerkraftsetzungen sorgen für Konsistenz in Ihren Konfigurationsdateien für Ihre Entwicklungs- und Produktionsworkloads und stellen sicher, dass Ihre Static Web Apps-Ressource mit aktivierten Datenbankverbindungen sicher und produktionsbereit ist.

Wenn die statische Web-App für die Verbindung mit der Datenbank konfiguriert ist, können Sie jetzt die Verbindung überprüfen.

Homepage aktualisieren

Ersetzen Sie das Markup zwischen den body-Tags in der Datei index.html durch den folgenden HTML-Code:

<h1>Static Web Apps Database Connections</h1>
<blockquote>
    Open the console in the browser developer tools to see the API responses.
</blockquote>
<div>
    <button id="list" onclick="list()">List</button>
    <button id="get" onclick="get()">Get</button>
    <button id="update" onclick="update()">Update</button>
    <button id="create" onclick="create()">Create</button>
    <button id="delete" onclick="del()">Delete</button>
</div>
<script>
    // add JavaScript here
</script>

Lokales Starten der Anwendung

Jetzt können Sie Ihre Website ausführen und Daten in der Datenbank direkt bearbeiten.

  1. Verwenden Sie npm, um die Static Web Apps-CLI zu installieren oder zu aktualisieren. Wählen Sie aus, welcher Befehl für Ihre Situation am besten geeignet ist.

    Verwenden Sie npm install zum Installieren.

    npm install -g @azure/static-web-apps-cli

    Verwenden Sie npm update zum Aktualisieren.

    npm update

  2. Starten Sie die statische Web-App mit der Datenbankkonfiguration.

    swa start ./src --data-api-location swa-db-connections

Nachdem die CLI gestartet wurde, können Sie über die in der Datei staticwebapp.database.config.json definierten Endpunkte auf Ihre Datenbank zugreifen.

Der Endpunkt http://localhost:4280/data-api/graphql akzeptiert GraphQL-Abfragen und Mutationen.

Bearbeiten von Daten

Die folgenden frameworkunabhängigen Befehle veranschaulichen, wie Sie vollständige CRUD-Vorgänge für Ihre Datenbank ausführen.

Die Ausgabe der einzelnen Funktionen wird im Konsolenfenster des Browsers angezeigt.

Öffnen Sie die Entwicklertools, indem Sie CMD/STRG + UMSCHALT + I drücken, und wählen Sie die Registerkarte Konsole aus.

Auflisten aller Elemente

Fügen Sie den folgenden Code zwischen den script-Tags in index.html hinzu:

async function list() {

  const query = `
      {
        people {
          items {
            id
            Name
          }
        }
      }`;
      
  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query: query })
  });
  const result = await response.json();
  console.table(result.data.people.items);
}

In diesem Beispiel:

  • Die GraphQL-Abfrage wählt die Felder Id und Name aus der Datenbank aus.
  • Die an den Server übergebene Anforderung erfordert eine Nutzlast, bei der die query-Eigenschaft die Abfragedefinition enthält.
  • Daten in der Antwortnutzlast befinden sich in der data.people.items-Eigenschaft.

Aktualisieren Sie die Seite, und wählen Sie die Schaltfläche Auflisten aus.

Im Konsolenfenster des Browsers wird nun eine Tabelle angezeigt, in der alle Datensätze in der Datenbank aufgelistet sind.

id Name
1 Sonnig
2 Dheeraj

Hier sehen Sie einen Screenshot, wie dies in Ihrem Browser aussehen sollte:

Webbrowser mit Ergebnissen einer Datenbankauswahl im Entwicklertools-Konsolenfenster

Abrufen nach ID

Fügen Sie den folgenden Code zwischen den script-Tags in index.html hinzu:

async function get() {

  const id = '1';

  const gql = `
    query getById($id: ID!) {
      person_by_pk(id: $id) {
        id
        Name
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
    },
  };

  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query),
  });
  const result = await response.json();
  console.table(result.data.person_by_pk);
}

In diesem Beispiel:

  • Die GraphQL-Abfrage wählt die Felder id und Name aus der Datenbank aus.
  • Die an den Server übergebene Anforderung erfordert eine Nutzlast, bei der die query-Eigenschaft die Abfragedefinition enthält.
  • Daten in der Antwortnutzlast befinden sich in der data.person_by_pk-Eigenschaft.

Aktualisieren Sie die Seite, und wählen Sie die Schaltfläche Abrufen aus.

Im Konsolenfenster des Browsers wird nun eine Tabelle mit dem einzelnen Datensatz angezeigt, der aus der Datenbank angefordert wurde.

id Name
1 Sonnig

Aktualisieren

Fügen Sie den folgenden Code zwischen den script-Tags in index.html hinzu:

async function update() {

  const id = '1';
  const data = {
    id: id,
    Name: "Molly"
  };

  const gql = `
    mutation update($id: ID!, $_partitionKeyValue: String!, $item: UpdatePersonInput!) {
      updatePerson(id: $id, _partitionKeyValue: $_partitionKeyValue, item: $item) {
        id
        Name
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
      _partitionKeyValue: id,
      item: data
    } 
  };

  const endpoint = "/data-api/graphql";
  const res = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const result = await res.json();
  console.table(result.data.updatePerson);
}

In diesem Beispiel:

  • Die GraphQL-Abfrage wählt die Felder id und Name aus der Datenbank aus.
  • Das query-Objekt enthält die GraphQL-Abfrage in der query-Eigenschaft.
  • Die Argumentwerte für die GraphQL-Funktion werden über die query.variables-Eigenschaft übergeben.
  • Die an den Server übergebene Anforderung erfordert eine Nutzlast, bei der die query-Eigenschaft die Abfragedefinition enthält.
  • Daten in der Antwortnutzlast befinden sich in der data.updatePerson-Eigenschaft.

Aktualisieren Sie die Seite, und wählen Sie die Schaltfläche Aktualisieren aus.

Im Konsolenfenster des Browsers wird nun eine Tabelle mit den aktualisierten Daten angezeigt.

id Name
1 Molly

Erstellen

Fügen Sie den folgenden Code zwischen den script-Tags in index.html hinzu:

async function create() {

  const data = {
    id: "3",
    Name: "Pedro"
  };

  const gql = `
    mutation create($item: CreatePersonInput!) {
      createPerson(item: $item) {
        id
        Name
      }
    }`;
  
  const query = {
    query: gql,
    variables: {
      item: data
    } 
  };
  
  const endpoint = "/data-api/graphql";
  const result = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const response = await result.json();
  console.table(response.data.createPerson);
}

In diesem Beispiel:

  • Die GraphQL-Abfrage wählt die Felder id und Name aus der Datenbank aus.
  • Das query-Objekt enthält die GraphQL-Abfrage in der query-Eigenschaft.
  • Die Argumentwerte für die GraphQL-Funktion werden über die query.variables-Eigenschaft übergeben.
  • Die an den Server übergebene Anforderung erfordert eine Nutzlast, bei der die query-Eigenschaft die Abfragedefinition enthält.
  • Daten in der Antwortnutzlast befinden sich in der data.updatePerson-Eigenschaft.

Aktualisieren Sie die Seite, und wählen Sie die Schaltfläche Erstellen aus.

Im Konsolenfenster des Browsers wird nun eine Tabelle mit dem neuen Datensatz in der Datenbank angezeigt.

id Name
3 Pedro

Löschen

Fügen Sie den folgenden Code zwischen den script-Tags in index.html hinzu:

async function del() {

  const id = '3';

  const gql = `
    mutation del($id: ID!, $_partitionKeyValue: String!) {
      deletePerson(id: $id, _partitionKeyValue: $_partitionKeyValue) {
        id
      }
    }`;

  const query = {
    query: gql,
    variables: {
      id: id,
    _partitionKeyValue: id
    }
  };

  const endpoint = "/data-api/graphql";
  const response = await fetch(endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(query)
  });

  const result = await response.json();
  console.log(`Record deleted: ${ JSON.stringify(result.data) }`);
}

In diesem Beispiel:

  • Die GraphQL-Abfrage wählt das Feld Id aus der Datenbank aus.
  • Das query-Objekt enthält die GraphQL-Abfrage in der query-Eigenschaft.
  • Die Argumentwerte für die GraphQL-Funktion werden über die query.variables-Eigenschaft übergeben.
  • Die an den Server übergebene Anforderung erfordert eine Nutzlast, bei der die query-Eigenschaft die Abfragedefinition enthält.
  • Daten in der Antwortnutzlast befinden sich in der data.deletePerson-Eigenschaft.

Aktualisieren Sie die Seite, und wählen Sie die Schaltfläche Löschen aus.

Im Konsolenfenster des Browsers wird nun eine Tabelle mit der Antwort aus der Löschanforderung angezeigt.

Record deleted: 2

Sie haben Ihre Website lokal verwendet und können Sie nun in Azure bereitstellen.

Bereitstellen Ihrer Website

Zum Bereitstellen dieser Website in der Produktion müssen Sie nur die Konfigurationsdatei committen und Ihre Änderungen per Push an den Server übertragen.

  1. Committen Sie die Konfigurationsänderungen.

    git commit -am "Add database configuration"

  2. Pushen Sie die Änderungen auf den Server.

    git push origin main

  3. Warten Sie, bis Ihre Web-App erstellt wurde.

  4. Wechseln Sie im Browser zu Ihrer statischen Web-App.

  5. Wählen Sie die Schaltfläche Auflisten aus, um alle Elemente aufzulisten.

    Die Ausgabe sollte diesem Screenshot ähneln:

    Webbrowser mit Ergebnissen des Auflistens von Datensätzen aus der Datenbank im Entwickertools-Konsolenfenster

Verbinden der Datenbank mit Ihrer statischen Web-App

Führen Sie die folgenden Schritte aus, um eine Verbindung zwischen der Static Web Apps-Instanz Ihrer Website und Ihrer Datenbank herzustellen.

  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.
    Datenbankname Wählen Sie den Namen der Datenbank aus, die Sie mit Ihrer statischen Web-App verknüpfen möchten.
    Authentifizierungstyp Wählen Sie Verbindungszeichenfolge aus.

  5. Klicken Sie auf OK.

Überprüfen Sie, ob Ihre Datenbank mit Ihrer Static Web Apps-Ressource verbunden ist.

Wenn Sie Ihre Datenbank mit Ihrer statischen Web-App verbunden haben und die Erstellung der Website abgeschlossen ist, führen Sie die folgenden Schritte aus, um die Datenbankverbindung zu überprüfen:

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

  2. Wählen Sie im Abschnitt Grundlagen die URL Ihrer Static Web Apps-Ressource aus, um zu Ihrer statischen Web-App zu navigieren.

  3. Wählen Sie die Schaltfläche Auflisten aus, um alle Elemente aufzulisten.

    Die Ausgabe sollte diesem Screenshot ähneln:

    Webbrowser mit Ergebnissen des Auflistens von Datensätzen aus der Datenbank im Entwickertools-Konsolenfenster

Bereinigen von Ressourcen

Wenn Sie die in diesem Tutorial erstellten Ressourcen entfernen möchten, müssen Sie die Verknüpfung der Datenbank aufheben und die Beispieldaten entfernen.

  1. Aufheben der Verknüpfung der Datenbank: Öffnen Sie Ihre statische Web-App im Azure-Portal. Wählen Sie im Abschnitt Einstellungen die Option Datenbankverbindung aus. Wählen Sie neben der verknüpften Datenbank Details anzeigen aus. Wählen Sie im Fenster Datenbankverbindungsdetails die Schaltfläche Verknüpfung aufheben aus.

  2. Entfernen der Beispieldaten: Löschen Sie in Ihrer Datenbank die Tabelle mit dem Namen MyTestPersonContainer.

Nächste Schritte

Hinzufügen einer API zu Azure Static Web Apps (Vorschauversion) mit Azure Functions