Esercitazione: Aggiungere una connessione al database Azure Cosmos DB in App Web statiche di Azure (anteprima)

Questa esercitazione descrive come connettere un database Azure Cosmos DB per NoSQL all'app Web statica. Dopo la configurazione, è possibile effettuare richieste GraphQL all'endpoint predefinito /data-api per modificare i dati senza dover scrivere codice back-end.

Per semplicità, questa esercitazione illustra come usare un database di Azure a scopo di sviluppo locale, ma è anche possibile usare un server di database locale per le esigenze di sviluppo locali.

Questa esercitazione apprendi come:

Prerequisiti

Per completare questa esercitazione, è necessario avere un database Azure Cosmos DB per NoSQL esistente e un'app Web statica.

Per iniziare, configurare il database in modo che funzioni con la funzionalità di connessione al database App Web statiche di Azure.

Configurare la connettività del database

App Web statiche di Azure deve 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.

1. Passare all'account Azure Cosmos DB per NoSQL nel portale di Azure.

2. Nella sezione Impostazioni, selezionare Rete.

3. Nella sezione Accesso pubblico selezionare Tutte le reti. Questa azione consente di usare il database cloud per lo sviluppo locale, che la risorsa App Web statiche distribuita può accedere al database e che è possibile eseguire query sul database dal portale.

4. Seleziona Salva.

Ottenere stringa di connessione di database per lo sviluppo locale

Per usare il database di Azure per lo sviluppo locale, è necessario recuperare il stringa di connessione del database. È possibile ignorare questo passaggio se si prevede di usare un database locale a scopo di sviluppo.

1. Passare all'account Azure Cosmos DB per NoSQL nel portale di Azure.

2. Nella sezione Impostazioni selezionare Chiavi.

3. Nella casella STRINGA DI CONNESSIONE PRIMARIA copiare il stringa di connessione e salvarlo in un editor di testo.

Creare dati di esempio

Creare una tabella di esempio e eseguire il seeding con i dati di esempio in modo che corrispondano all'esercitazione.

1. Nella finestra di spostamento a sinistra selezionare Esplora dati.

2. Selezionare Nuovo contenitore. Immettere l'ID database come Create newe immettere MyTestPersonDatabase come valore.

3. Immettere l'ID contenitore di MyTestPersonContainer.

4. Immettere una chiave di partizione di id (questo valore è preceduto da /).

5. Seleziona OK.

6. Selezionare il contenitore MyTestPersonContainer .

7. Selezionare i relativi elementi.

8. Selezionare Nuovo elemento e immettere il valore seguente:

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

Configurare l'app Web statica

La parte restante di questa esercitazione è incentrata sulla modifica del codice sorgente dell'app Web statica per l'uso delle connessioni di database in locale.

1. Passare al ramo main.

   git checkout main
   

2. Sincronizzare la versione locale con gli elementi in GitHub usando git pull.

   git pull origin main
   

Creare il file di configurazione del database

Creare quindi il file di configurazione usato dall'app Web statica per interfacciarsi con il database.

1. Aprire il terminale e creare una nuova variabile per contenere il stringa di connessione. La sintassi specifica può variare a seconda del tipo di shell in uso.

   • Bash
   • PowerShell

   export DATABASE_CONNECTION_STRING='<YOUR_CONNECTION_STRING>'
   

   Assicurarsi di sostituire <YOUR_CONNECTION_STRING> con il valore della stringa di connessione impostato in un editor di testo.

2. Usare npm per installare o aggiornare l'interfaccia della riga di comando di App Web statiche. Selezionare il comando migliore per la situazione.

   Per eseguire l'installazione, usare npm install.

   • Bash
   • PowerShell

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

   Per eseguire l'aggiornamento, usare npm update.

   • Bash
   • PowerShell

   npm update
   

3. Usare il swa db init comando per generare un file di configurazione del database.

   • Bash
   • PowerShell

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

   Il init comando crea il file staticwebapp.database.config.json nella cartella swa-db-connections .

4. Incollare questo schema di esempio nel file staticwebapp.database.schema.gql generato.

   Poiché Cosmos DB per NoSQL è un database indipendente dallo schema, App Web statiche di Azure le connessioni di database non possono estrarre lo schema del database. Il file staticwebapp.database.schema.gql consente di specificare lo schema del database Cosmos DB per NoSQL per App Web statiche.

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

5. Incollare questa configurazione di esempio nel file staticwebapp.database.config.json generato. Si noti che Cosmos DB per NoSQL include altre opzioni nell'oggetto data-source per indicare il database Cosmos DB e il file di schema necessario per le connessioni di database per comprendere lo schema del database.

{
  "$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"
        }
      ]
    }
  }
}

Prima di passare al passaggio successivo, esaminare la tabella seguente che illustra i diversi aspetti del file di configurazione. Per la documentazione completa sul file di configurazione e sulle funzionalità, ad esempio relazioni e criteri per la sicurezza a livello di elemento, vedere la documentazione di Generatore API dati.

Dopo aver configurato l'app Web statica per connettersi al database, è ora possibile verificare la connessione.

Aggiornare la home page

Sostituire il markup tra i body tag nel file index.html con il codice HTML seguente.

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

Avviare l'applicazione in locale

È ora possibile eseguire il sito Web e modificare direttamente i dati nel database.

1. Usare npm per installare o aggiornare l'interfaccia della riga di comando di App Web statiche. Selezionare il comando migliore per la situazione.

   Per eseguire l'installazione, usare npm install.

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

   Per eseguire l'aggiornamento, usare npm update.

   npm update
   

2. Avviare l'app Web statica con la configurazione del database.

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

Ora che l'interfaccia della riga di comando è stata avviata, è possibile accedere al database tramite gli endpoint definiti nel file staticwebapp.database.config.json .

L'endpoint http://localhost:4280/data-api/graphql accetta query e mutazioni GraphQL.

Manipolare i dati

I comandi indipendenti dal framework seguenti illustrano come eseguire operazioni CRUD complete nel database.

L'output per ogni funzione viene visualizzato nella finestra della console del browser.

Aprire gli strumenti di sviluppo premendo CMD/CTRL + MAIUSC + I e selezionare la scheda Console.

Elencare tutti gli elementi

Aggiungere il codice seguente tra i script tag in index.html.

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 questo esempio:

• La query GraphQL seleziona i Id campi e Name dal database.
• La richiesta passata al server richiede un payload in cui la query proprietà contiene la definizione della query.
• I dati nel payload della data.people.items risposta si trovano nella proprietà .

Aggiornare la pagina e selezionare il pulsante Elenco .

La finestra della console del browser visualizza ora una tabella che elenca tutti i record nel database.

Di seguito è riportato uno screenshot dell'aspetto che dovrebbe essere visualizzato nel browser.

Recuperare per ID

Aggiungere il codice seguente tra i script tag in index.html.

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 questo esempio:

• La query GraphQL seleziona i id campi e Name dal database.
• La richiesta passata al server richiede un payload in cui la query proprietà contiene la definizione della query.
• I dati nel payload della data.person_by_pk risposta si trovano nella proprietà .

Aggiornare la pagina e selezionare il pulsante Recupera .

La finestra della console del browser visualizza ora una tabella che elenca il singolo record richiesto dal database.

Update

Aggiungere il codice seguente tra i script tag in index.html.

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 questo esempio:

• La query GraphQL seleziona i id campi e Name dal database.
• L'oggetto query contiene la query GraphQL nella query proprietà .
• I valori dell'argomento per la funzione GraphQL vengono passati tramite la query.variables proprietà .
• La richiesta passata al server richiede un payload in cui la query proprietà contiene la definizione della query.
• I dati nel payload della data.updatePerson risposta si trovano nella proprietà .

Aggiornare la pagina e selezionare il pulsante Aggiorna .

La finestra della console del browser visualizza ora una tabella che mostra i dati aggiornati.

Creazione

Aggiungere il codice seguente tra i script tag in index.html.

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 questo esempio:

• La query GraphQL seleziona i id campi e Name dal database.
• L'oggetto query contiene la query GraphQL nella query proprietà .
• I valori dell'argomento per la funzione GraphQL vengono passati tramite la query.variables proprietà .
• La richiesta passata al server richiede un payload in cui la query proprietà contiene la definizione della query.
• I dati nel payload della data.updatePerson risposta si trovano nella proprietà .

Aggiornare la pagina e selezionare il pulsante Crea .

La finestra della console del browser visualizza ora una tabella che mostra il nuovo record nel database.

Elimina

Aggiungere il codice seguente tra i script tag in index.html.

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 questo esempio:

• La query GraphQL seleziona il Id campo dal database.
• L'oggetto query contiene la query GraphQL nella query proprietà .
• I valori dell'argomento per la funzione GraphQL vengono passati tramite la query.variables proprietà .
• La richiesta passata al server richiede un payload in cui la query proprietà contiene la definizione della query.
• I dati nel payload della data.deletePerson risposta si trovano nella proprietà .

Aggiornare la pagina e selezionare il pulsante Elimina .

La finestra della console del browser visualizza ora una tabella che mostra la risposta dalla richiesta di eliminazione.

Record eliminato: 2

Ora che si è lavorato con il sito in locale, è ora possibile distribuirlo in Azure.

Distribuire il sito

Per distribuire questo sito nell'ambiente di produzione, è sufficiente eseguire il commit del file di configurazione ed eseguire il push delle modifiche nel server.

1. Eseguire il commit delle modifiche di configurazione.

   git commit -am "Add database configuration"
   

2. Eseguire il push delle modifiche nel server.

   git push origin main
   

3. Attendere la compilazione dell'app Web.

4. Passare all'app Web statica nel browser.

5. Selezionare il pulsante Elenco per elencare tutti gli elementi.

   L'output dovrebbe essere simile a quello mostrato in questo screenshot.

   

Connettere il database all'app Web statica

Usare la procedura seguente per creare una connessione tra l'istanza di App Web statiche del sito e il database.

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 database	Selezionare il nome del database da collegare all'app Web statica.
   Tipo di autenticazione	Selezionare Stringa di connessione.

5. Seleziona OK.

Verificare che il database sia connesso alla risorsa App Web statiche

Dopo aver connesso il database all'app Web statica e aver completato la compilazione del sito, seguire questa procedura per verificare la connessione al database.

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

2. Nella sezione Informazioni di base selezionare l'URL della risorsa App Web statiche per passare all'app Web statica.

3. Selezionare il pulsante Elenco per elencare tutti gli elementi.

   L'output dovrebbe essere simile a quello mostrato in questo screenshot.

   

Pulire le risorse

Per rimuovere le risorse create durante questa esercitazione, è necessario scollegare il database e rimuovere i dati di esempio.

1. Scollega database: aprire l'app Web statica nel portale di Azure. Nella sezione Impostazioni selezionare Connessione database. Accanto al database collegato selezionare Visualizza dettagli. Nella finestra Dettagli connessione database selezionare il pulsante Scollega.

2. Rimuovere i dati di esempio: nel database eliminare la tabella denominata MyTestPersonContainer.

Passaggi successivi