Partager via

Tutoriel : Ajouter une connexion de base de données PostgreSQL dans Azure Static Web Apps (préversion)

  • Article

Dans ce tutoriel, vous allez apprendre à connecter une base de données Azure Database pour PostgreSQL serveur unique ou serveur flexible à votre application web statique. Une fois configuré, vous pouvez effectuer des requêtes REST ou GraphQL sur le point de terminaison /data-api intégré pour manipuler des données sans avoir à écrire de code back-end.

Par souci de simplicité, ce tutoriel vous montre comment utiliser une base de données Azure à des fins de développement local, mais vous pouvez également utiliser un serveur de base de données local pour vos besoins de développement local.

Notes

Ce tutoriel montre comment utiliser Azure Database pour PostgreSQL serveur flexible ou serveur unique. Si vous souhaitez utiliser une autre base de données, reportez-vous aux tutorielsAzure Cosmos DB, Azure SQL ou MySQL.

Navigateur web montrant les résultats de la sélection de PostgreSQL dans la fenêtre de la console outils de développement.

Ce didacticiel vous apprend à effectuer les opérations suivantes :

  • Liez une base de données serveur flexible ou serveur unique Azure Database pour PostgreSQL à votre application web statique
  • Créer, lire, mettre à jour et supprimer des données

Prérequis

Pour réaliser ce tutoriel, vous devez disposer d’une base de données Azure Database pour PostgreSQL Serveur Flexible ou Serveur Unique et d’une application web statique. En outre, vous devez installer Azure Data Studio.

Ressource Description
Azure Database pour PostgreSQL serveur flexible ou Base de données Azure Database pour PostgreSQL Serveur Unique Si vous n’en avez pas encore, suivez les étapes décrites dans le guide créer une base de données Azure Database pour PostgreSQL Serveur flexible ou dans le guide créer une base de données Azure Database pour PostgreSQL Serveur unique. Si vous envisagez d’utiliser une authentification par chaîne de connexion pour les connexions de base de données de Static Web Apps, veillez à créer votre serveur Azure Database pour PostgreSQL avec l’authentification PostgreSQL. Vous pouvez modifier cette valeur si vous souhaitez utiliser l’identité managée ultérieurement.
Application web statique existante Si vous n’en avez pas encore, suivez les étapes du guide de prise en main pour créer une application web statique No Framework.
Azure Data Studio, avec l’extension PostgreSQL Si Azure Data Studio n’est pas déjà installé, suivez le guide pour installer Azure Data Studio avec l’extension PostgreSQL. Vous pouvez également utiliser n’importe quel autre outil pour interroger votre base de données PostgreSQL, par exemple PgAdmin.

Commencez par configurer votre base de données pour qu’elle fonctionne avec la fonctionnalité de connexion de base de données Azure Static Web Apps.

Configurez la connectivité de base de données

Azure Static Web Apps doit disposer d’un accès réseau à votre base de données pour que les connexions à la base de données fonctionnent. En outre, pour utiliser une base de données Azure pour le développement local, vous devez configurer votre base de données pour autoriser les requêtes provenant de votre propre adresse IP.

  1. Accédez à votre serveur Azure Database pour PostgreSQL dans le Portail Azure.

  2. Si vous utilisez Azure Database pour PostgreSQL serveur flexible, sous la section Paramètres, sélectionnez Mise en réseau. Si vous utilisez Azure Database pour PostgreSQL serveur unique, sous la section Paramètres, sélectionnez Sécurité de la connexion.

  3. Sous la section Règles de pare-feu, sélectionnez le bouton Ajouter l’adresse IP de votre client actuel. Cette étape garantit que vous pouvez utiliser cette base de données pour votre développement local.

  4. Dans la section Règles de pare-feu, cochez la case Autoriser l’accès public à ce serveur depuis n’importe quel service Azure au sein d’Azure. Si vous utilisez Azure Database pour PostgreSQL serveur unique, ce bouton est intitulé Autoriser l’accès aux services Azure. Cette étape garantit que votre ressource de Static Web Apps déployée peut accéder à votre base de données.

  5. Sélectionnez Enregistrer.

Obtenez la chaîne de connexion de base de données pour le développement local

Pour utiliser votre base de données Azure pour le développement local, vous devez récupérer la chaîne de connexion de votre base de données. Vous pouvez ignorer cette étape si vous envisagez d’utiliser une base de données locale à des fins de développement.

  1. Accédez à votre serveur Azure Database pour PostgreSQL dans le Portail Azure.

  2. Dans la section Paramètres, sélectionnez Chaînes de connexion.

  3. Dans la zone ADO.NET, copiez la chaîne de connexion et mettez-la de côté dans un éditeur de texte.

  4. Remplacez l’espace réservé {your_password} dans la chaîne de connexion par votre mot de passe.

  5. Remplacez l’espace réservé {your_database} par le nom de la base de données MyTestPersonDatabase. Vous allez créer le MyTestPersonDatabase dans les étapes à venir.

  6. Ajoutez Trust Server Certificate=True; à la chaîne de connexion pour utiliser cette chaîne de connexion pour le développement local.

Créer des exemples de données

Créez un tableau d’échantillons et alimentez-le avec des données d’échantillons correspondant à ceux du tutoriel. Ce tutoriel utilise Azure Data Studio, mais vous pouvez utiliser PgAdmin ou tout autre outil.

  1. Dans Azure Data Studio, créez une connexion à votre serveur Azure Database pour PostgreSQL

  2. Faites un clic droit sur votre serveur et sélectionnez Nouvelle requête. Exécutez la requête suivante pour créer une base de données nommée MyTestPersonDatabase.

    CREATE DATABASE "MyTestPersonDatabase";

  3. Faites un clic droit sur votre serveur, puis sélectionnez Actualiser.

  4. Faites un clic droit sur votre MyTestPersonDatabase et sélectionnez Nouvelle requête. Exécutez la requête suivante pour créer un nouveau tableau nommé MyTestPersonTable.

    CREATE TABLE "MyTestPersonTable" (
    "Id" SERIAL PRIMARY KEY,
    "Name" VARCHAR(25) NULL
);

  5. Exécutez la requête suivante pour ajouter des données dans le tableau MyTestPersonTable.

    INSERT INTO "MyTestPersonTable" ("Name")
VALUES ('Sunny');

INSERT INTO "MyTestPersonTable" ("Name")
VALUES ('Dheeraj');

Configurez l’application web statique

Le reste de ce tutoriel se concentre sur la modification du code source de votre application web statique pour utiliser les connexions de base de données localement.

Important

Les étapes suivantes supposent que vous travaillez avec l’application web statique créée dans le guide de prise en main. Si vous utilisez un autre projet, veillez à ajuster les commandes git suivantes pour qu’elles correspondent aux noms de vos branches.

  1. Basculez vers la branche main.

    git checkout main

  2. Synchronisez votre version locale avec ce qui se trouve sur GitHub à l’aide de git pull.

    git pull origin main

Créez le fichier de configuration de la base de données

Ensuite, créez le fichier de configuration que votre application web statique utilise pour s’interfacer avec la base de données.

  1. Ouvrez votre terminal et créez une nouvelle variable pour contenir votre chaîne de connexion. La syntaxe spécifique peut varier en fonction du type d’interpréteur de commandes que vous utilisez.

    export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'

    Veillez à remplacer par <YOUR_CONNECTION_STRING> la valeur de chaîne de connexions que vous avez mise de côté dans un éditeur de texte.

  2. Utilisez npm pour installer ou mettre à jour l’interface CLI Static Web Apps. Choisissez la commande qui convient le mieux à votre situation.

    Pour installer, utilisez npm install.

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

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

    Pour mettre à jour, utilisez npm update.

    npm update

    npm update

  3. Utilisez la commande swa db init pour générer un fichier de configuration de la base de données.

    swa db init --database-type postgresql

    La commande init crée le fichier staticwebapp.database.config.json dans le dossier swa-db-connections.

  4. Collez cet échantillon dans le fichier staticwebapp.database.config.json que vous avez généré.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "postgresql",
    "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": "MyTestPersonTable",
      "permissions": [
        {
          "actions": ["*"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Avant de passer à l’étape suivante, passez en revue le tableau suivant qui explique les différents aspects du fichier de configuration. Pour obtenir une documentation complète sur le fichier de configuration et les fonctionnalités telles que les relations et les stratégies de sécurité au niveau de l’élément, reportez-vous à la documentation Data API Builder.

Fonctionnalité Explication
Connexion de base de données Dans le développement, le runtime lit la chaîne de connexion à partir de la valeur de la chaîne de connexion dans le fichier de configuration. Bien que vous puissiez spécifier votre chaîne de connexion directement dans le fichier de configuration, il est recommandé de stocker les chaînes de connexion dans une variable d’environnement locale. Vous pouvez faire référence aux valeurs de variable d’environnement dans le fichier de configuration via la notation @env('DATABASE_CONNECTION_STRING'). La valeur de la chaîne de connexion est remplacée par Static Web Apps pour le site déployé avec les informations collectées lorsque vous connectez votre base de données.
Point de terminaison d’API Le point de terminaison REST est disponible via /data-api/rest tandis que le point de terminaison GraphQL est disponible via /data-api/graphql comme configuré dans ce fichier de configuration. Vous pouvez configurer les chemins REST et GraphQL, mais le préfixe /data-api n’est pas configurable.
Sécurité API Les paramètres runtime.host.cors vous permettent de définir des origines autorisées qui peuvent effectuer des requêtes à l’API. Dans ce cas, la configuration reflète un environnement de développement et autorise l’emplacement http://localhost:4280.
Modèle d’entité Définit les entités exposées via des routes dans l’API REST ou en tant que types dans le schéma GraphQL. Dans ce cas, le nom Person est le nom exposé au point de terminaison, tandis que entities.<NAME>.source est le schéma de base de données et le mappage de tableau. Notez que le nom du point de terminaison d’API n’a pas besoin d’être identique au nom du tableau.
Sécurité d'une entité Les règles d’autorisations répertoriées dans le tableau entity.<NAME>.permissions contrôlent les paramètres d’autorisation d’une entité. Vous pouvez sécuriser une entité avec des rôles de la même façon que vous sécurisez les itinéraires avec des rôles.

Notes

Les propriétés connection-string, host.mode, et graphql.allow-introspection du fichier de configuration sont remplacées lorsque vous déployez votre site. Votre chaîne de connexion est remplacée par les détails d’authentification collectés lorsque vous connectez votre base de données à votre ressource Static Web Apps. La propriété host.mode a la valeur production et graphql.allow-introspection a la valeur false. Ces remplacements fournissent une cohérence dans vos fichiers de configuration dans vos charges de travail de développement et de production, tout en garantissant que votre ressource Static Web Apps avec les connexions de base de données activées est sécurisée et prête pour la production.

Une fois l’application web statique configurée pour se connecter à la base de données, vous pouvez maintenant vérifier la connexion.

Page d'accueil Update

Remplacez le balisage entre les balises body dans le fichier index.html par le code HTML suivant.

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

Démarrer l’application localement

Vous pouvez maintenant exécuter votre site web et manipuler directement les données de la base de données.

  1. Démarrez l’application web statique avec la configuration de la base de données.

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

Maintenant que l’interface CLI est démarrée, vous pouvez accéder à votre base de données via les points de terminaison définis dans le fichier staticwebapp.database.config.json.

Le point de terminaison http://localhost:4280/data-api/rest/<ENTITY_NAME> accepte GET, PUT, POST et DELETE demande à manipuler des données dans la base de données.

Le point de terminaison http://localhost:4280/data-api/graphql accepte les requêtes et mutations GraphQL.

Manipuler des données

Les commandes indépendantes de l’infrastructure suivantes montrent comment effectuer des opérations CRUD complètes sur votre base de données.

La sortie de chaque fonction s’affiche dans la fenêtre de console du navigateur.

Ouvrez les outils de développement en appuyant sur CMD/CTRL + MAJ + I, puis sélectionnez l’onglet Console.

Répertoriez tous les éléments

Ajoutez le code suivant entre les balises script dans index.html.

async function list() {
  const endpoint = '/data-api/rest/Person';
  const response = await fetch(endpoint);
  const data = await response.json();
  console.table(data.value);
}

Dans cet exemple :

  • La requête par défaut pour l’API fetch utilise le verbe GET.
  • Les données de la charge utile de réponse se trouvent dans la propriété value.
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);
}

Dans cet exemple :

  • La requête GraphQL sélectionne les champs Id et Name dans la base de données.
  • La requête passée au serveur nécessite une charge utile où la propriété query contient la définition de requête.
  • Les données de la charge utile de réponse se trouvent dans la propriété data.people.items.

Actualisez la page et sélectionnez le bouton Liste.

La fenêtre de console du navigateur affiche désormais un tableau qui répertorie tous les enregistrements de la base de données.

id Nom
1 Ensoleillé
2 Dheeraj

Voici une capture d’écran de ce à quoi cela devrait ressembler dans votre navigateur.

Navigateur web affichant les résultats d’une sélection de base de données dans la fenêtre de la console des outils de développement.

Obtenez par ID

Ajoutez le code suivant entre les balises script dans index.html.

async function get() {
  const id = 1;
  const endpoint = `/data-api/rest/Person/Id`;
  const response = await fetch(`${endpoint}/${id}`);
  const result = await response.json();
  console.table(result.value);
}

Dans cet exemple :

  • Le point de terminaison est suffixe avec /person/Id.
  • La valeur d’ID est ajoutée à la fin de l’emplacement du point de terminaison.
  • Les données de la charge utile de réponse se trouvent dans la propriété value.
async function get() {

  const id = 1;

  const gql = `
    query getById($id: Int!) {
      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);
}

Dans cet exemple :

  • La requête GraphQL sélectionne les champs Id et Name dans la base de données.
  • La requête passée au serveur nécessite une charge utile où la propriété query contient la définition de requête.
  • Les données de la charge utile de réponse se trouvent dans la propriété data.person_by_pk.

Actualisez la page et sélectionnez le bouton Obtenir.

La fenêtre de console du navigateur affiche désormais un tableau répertoriant l’enregistrement unique demandé à partir de la base de données.

id Nom
1 Ensoleillé

Update

Ajoutez le code suivant entre les balises script dans index.html.

Static Web Apps prend en charge les verbes PUT et PATCH. Une requête PUT met à jour l’enregistrement entier, tandis que PATCH effectue une mise à jour partielle.

async function update() {

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

  const endpoint = '/data-api/rest/Person/Id';
  const response = await fetch(`${endpoint}/${id}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data)
  });
  const result = await response.json();
  console.table(result.value);
}

Dans cet exemple :

  • Le point de terminaison est suffixe avec /person/Id/.
  • La valeur d’ID est ajoutée à la fin de l’emplacement du point de terminaison.
  • Le verbe REST est PUT pour mettre à jour l’enregistrement de la base de données.
  • Les données de la charge utile de réponse se trouvent dans la propriété value.
async function update() {

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

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

  const query = {
    query: gql,
    variables: {
      id: 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);
}

Dans cet exemple :

  • La requête GraphQL sélectionne les champs Id et Name dans la base de données.
  • L’objet query contient la requête GraphQL dans la propriété query.
  • Les valeurs d’argument à la fonction GraphQL sont passées via la propriété query.variables.
  • La requête passée au serveur nécessite une charge utile où la propriété query contient la définition de requête.
  • Les données de la charge utile de réponse se trouvent dans la propriété data.updatePerson.

Actualisez la page et sélectionnez le bouton Mettre à jour.

La fenêtre de console du navigateur affiche désormais un tableau montrant les données mises à jour.

id Nom
1 Molly

Créer

Ajoutez le code suivant entre les balises script dans index.html.

async function create() {

  const data = {
    Name: "Pedro"
  };

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

Dans cet exemple :

  • Le point de terminaison est suffixe avec /person/.
  • Le verbe REST est POST pour ajouter un enregistrement de base de données.
  • Les données de la charge utile de réponse se trouvent dans la propriété value.
async function create() {

  const data = {
    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);
}

Dans cet exemple :

  • La requête GraphQL sélectionne les champs Id et Name dans la base de données.
  • L’objet query contient la requête GraphQL dans la propriété query.
  • Les valeurs d’argument à la fonction GraphQL sont passées via la propriété query.variables.
  • La requête passée au serveur nécessite une charge utile où la propriété query contient la définition de requête.
  • Les données de la charge utile de réponse se trouvent dans la propriété data.updatePerson.

Actualisez la page et sélectionnez le bouton Créer.

La fenêtre de console du navigateur affiche maintenant un tableau montrant le nouvel enregistrement dans la base de données.

id Nom
3 Pedro

DELETE

Ajoutez le code suivant entre les balises script dans index.html.

async function del() {
  const id = 3;
  const endpoint = '/data-api/rest/Person/Id';
  const response = await fetch(`${endpoint}/${id}`, {
    method: "DELETE"
  });
  if(response.ok) {
    console.log(`Record deleted: ${ id }`)
  } else {
    console.log(response);
  }
}

Dans cet exemple :

  • Le point de terminaison est suffixe avec /person/Id/.
  • La valeur d’ID est ajoutée à la fin de l’emplacement du point de terminaison.
  • Le verbe REST est DELETE pour supprimer l’enregistrement de base de données.
  • Si la suppression réussit, la propriété de charge utile ok de la réponse est true.
async function del() {

  const id = 3;

  const gql = `
    mutation del($id: Int!) {
      deletePerson(Id: $id) {
        Id
      }
    }`;

  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.log(`Record deleted: ${ result.data.deletePerson.Id }`);
}

Dans cet exemple :

  • La requête GraphQL sélectionne le champ Id dans la base de données.
  • L’objet query contient la requête GraphQL dans la propriété query.
  • Les valeurs d’argument à la fonction GraphQL sont passées via la propriété query.variables.
  • La requête passée au serveur nécessite une charge utile où la propriété query contient la définition de requête.
  • Les données de la charge utile de réponse se trouvent dans la propriété data.deletePerson.

Actualisez la page et sélectionnez le bouton Supprimer.

La fenêtre de console du navigateur affiche désormais un tableau montrant la réponse de la demande de suppression.

Enregistrement supprimé : 3

Maintenant que vous avez travaillé avec votre site localement, vous pouvez maintenant le déployer sur Azure.

Déploiement de votre site

Pour déployer ce site en production, il vous suffit de valider le fichier de configuration et d’envoyer vos modifications au serveur.

  1. Ajoutez les modifications de fichier à suivre.

    git add .

  2. Validez les modifications de configuration.

    git commit -am "Add database configuration"

  3. Envoyez vos modifications au serveur.

    git push origin main

Connectez la base de données à votre application web statique

Procédez comme suit pour créer une connexion entre l’instance Static Web Apps de votre site et votre base de données.

  1. Sur le portail Azure, ouvrez votre application web statique.

  2. Dans la section Paramètres, sélectionnez Connexion de base de données.

  3. Dans la section Production, sélectionnez le lien Lier une base de données existante.

  4. Dans la fenêtre Lier une base de données existante, entrez les valeurs suivantes :

    Propriété Valeur
    Type de base de données Sélectionnez votre type de base de données dans la liste déroulante.
    Abonnement Sélectionnez votre abonnement Azure dans la liste déroulante.
    Nom de la ressource Sélectionnez le nom du serveur de base de données contenant la base de données souhaitée.
    Nom de la base de données Sélectionnez le nom de la base de données que vous souhaitez lier à votre application web statique.
    Type d’authentification Sélectionnez Chaîne de connexion, puis entrez le nom d’utilisateur et le mot de passe PostgreSQL. Pour PostgreSQL Single Server, n’incluez pas le suffixe @servername.

  5. Sélectionnez OK.

Vérifiez que votre base de données est connectée à votre ressource Static Web Apps

Une fois que vous avez connecté votre base de données à votre application web statique et que la génération du site est terminée, procédez comme suit pour vérifier la connexion à la base de données.

  1. Sur le portail Azure, ouvrez votre application web statique.

  2. Dans la section Essentials, sélectionnez URL de votre ressource Static Web Apps pour accéder à votre application web statique.

  3. Sélectionnez le bouton Liste pour répertorier tous les éléments.

    La sortie doit ressembler à ce qui est illustré dans cette capture d’écran.

    Navigateur web affichant les résultats de la liste des enregistrements de la base de données dans la fenêtre de la console Outils de développement.

Nettoyer les ressources

Si vous souhaitez supprimer les ressources créées au cours de ce tutoriel, vous devez dissocier la base de données et supprimer les données échantillons.

  1. Dissocier la base de données : Ouvrez votre application web statique dans le portail Azure. Dans la section Paramètres, sélectionnez Connexion de base de données. En regard de la base de données liée, sélectionnez Afficher les détails. Dans la fenêtre Détails de la connexion à la base de données, sélectionnez le bouton Dissocier.

  2. Supprimer les données de l’échantillon : dans votre base de données, supprimez la table nommée MyTestPersonTable.

Étapes suivantes

Ajouter une API