Inizio rapido: Usare Data API Builder con NoSQL

In questa guida introduttiva si creano endpoint GraphQL per un emulatore locale di Azure Cosmos DB per NoSQL usando Il generatore di API dati (DAB).

Prerequisiti

• Docker
• .NET 8

Installare il CLI di Data API Builder

Installare il pacchetto Microsoft.DataApiBuilder da NuGet come strumento di .NET.

1. Usa dotnet tool install per installare la versione più recente di Microsoft.DataApiBuilder con l'argomento --global.

   dotnet tool install --global Microsoft.DataApiBuilder
   

   Annotazioni

   Se il pacchetto è già installato, aggiornare invece il pacchetto usando dotnet tool update.

   dotnet tool update --global Microsoft.DataApiBuilder
   

2. Verifica che lo strumento sia installato usando dotnet tool list con l'argomento --global.

   dotnet tool list --global
   

Scaricare l'immagine dell'emulatore

Scaricare l'immagine dell'emulatore Azure Cosmos DB per NoSQL. Questo download può richiedere alcuni minuti perché l'immagine dell'emulatore è grande.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Avviare l'emulatore

Eseguire l'emulatore Cosmos DB su Docker. L'impostazione AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE è necessaria in modo che l'emulatore annunci 127.0.0.1 i suoi endpoint di rete, rendendo questi ultimi raggiungibili dal computer host.

docker run --name dab-cosmos --publish 8081:8081 --publish 10250-10255:10250-10255 --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 --detach mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Installare il certificato dell'emulatore

L'emulatore di Cosmos DB usa un certificato SSL autofirmato. Scaricare e considerare attendibile questo certificato in modo che il generatore di API dati possa connettersi all'emulatore.

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/emulatorcert.crt

curl.exe -k https://localhost:8081/_explorer/emulator.pem -o "$env:USERPROFILE\emulatorcert.crt"
Import-Certificate -CertStoreLocation "Cert:\CurrentUser\Root" -FilePath "$env:USERPROFILE\emulatorcert.crt"

Creare il database e i dati di inizializzazione

Usare l'Esplora dati integrato dell'emulatore per creare un database, un contenitore e gli elementi di esempio. Non sono necessari strumenti aggiuntivi: Esplora dati viene eseguito nel browser come parte dell'emulatore.

1. Apri l'Esplora dati su https://localhost:8081/_explorer/index.html.

2. Selezionare Nuovo database. Immettere todos come ID database e selezionare OK.

3. Espandi il database todos, seleziona il menu con i puntini di sospensione (...) e scegli Nuovo Contenitore. Immettere todos come ID contenitore e /id come chiave di partizione, quindi selezionare OK.

4. Espandere il contenitore todos e selezionare Elementi. Selezionare quindi Nuovo elemento, sostituire il codice JSON predefinito con il contenuto seguente e selezionare Salva. Ripetere per ogni elemento.

   Elemento 1:

   {
     "id": "1",
     "title": "Walk the dog",
     "completed": false
   }
   

   Elemento 2:

   {
     "id": "2",
     "title": "Feed the fish",
     "completed": false
   }
   

   Elemento 3:

   {
     "id": "3",
     "title": "Comb the cat",
     "completed": true
   }
   

Creare un file di schema GraphQL

Azure Cosmos DB per NoSQL richiede un file di schema GraphQL. Creare un file denominato schema.gql con il contenuto seguente.

type Todo @model {
  id: ID!
  title: String!
  completed: Boolean!
}

Configurare il generatore di API dati

1. Inizializzare la configurazione con la stringa di connessione predefinita dell'emulatore.

   dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database todos --graphql-schema schema.gql --connection-string "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
   

2. Aggiungere l'entità Todo .

   dab add Todo --source "todos" --permissions "anonymous:*"
   

Il dab-config.json file dovrebbe ora essere simile all'esempio seguente:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
    "options": {
      "database": "todos",
      "schema": "schema.gql"
    }
  },
  "runtime": {
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development"
    }
  },
  "entities": {
    "Todo": {
      "source": {
        "object": "todos",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

Avviare l'API

Usare dab start per eseguire lo strumento e creare endpoint API per l'entità.

dab start

L'output deve includere l'indirizzo dell'API in esecuzione.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

Testare l'API

1. Aprire il browser e passare all'endpoint GraphQL.

   http://localhost:5000/graphql
   

   In modalità di sviluppo, questo URL apre l'IDE Nitro GraphQL.

2. Creare un nuovo documento ed eseguire la query seguente per recuperare tutti gli elementi todo.

   query {
     todos {
       items {
         id
         title
         completed
       }
     }
   }
   

3. La risposta deve includere tutti e tre i todo items.

   {
     "data": {
       "todos": {
         "items": [
           { "id": "1", "title": "Walk the dog", "completed": false },
           { "id": "2", "title": "Feed the fish", "completed": false },
           { "id": "3", "title": "Comb the cat", "completed": true }
         ]
       }
     }
   }
   

Pulizia

Ferma e rimuovi il container Docker al termine.

docker stop dab-cosmos && docker rm dab-cosmos

Passo successivo

Contenuti correlati

• Configura il Data API Builder per Azure Cosmos DB per NoSQL
• Disponibilità delle funzionalità per Il generatore di API dati