Szybki start: korzystanie z konstruktora API danych z NoSQL

W tym szybkim starcie utworzysz endpointy GraphQL dla lokalnego emulatora usługi Azure Cosmos DB dla NoSQL przy użyciu konstruktora API danych (DAB).

Wymagania wstępne

• Docker
• .NET 8

Zainstaluj narzędzie linii poleceń do budowy API danych

Zainstaluj pakiet Microsoft.DataApiBuilder z narzędzia NuGet jako narzędzie .NET.

1. Użyj dotnet tool install, aby zainstalować najnowszą wersję Microsoft.DataApiBuilder za pomocą argumentu --global.

   dotnet tool install --global Microsoft.DataApiBuilder
   

   Uwaga / Notatka

   Jeśli pakiet jest już zainstalowany, zaktualizuj pakiet przy użyciu polecenia dotnet tool update.

   dotnet tool update --global Microsoft.DataApiBuilder
   

2. Sprawdź, czy narzędzie jest zainstalowane za pomocą dotnet tool list z użyciem argumentu --global.

   dotnet tool list --global
   

Ściąganie obrazu emulatora

Pobierz obraz emulatora usługi Azure Cosmos DB for NoSQL. Pobieranie może potrwać kilka minut, ponieważ obraz emulatora jest duży.

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

Uruchamianie emulatora

Uruchom emulator usługi Cosmos DB na platformie Docker. To ustawienie AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE jest wymagane, aby emulator ogłaszał swoje punkty końcowe sieci 127.0.0.1, co pozwala na dołączenie z maszyny hosta.

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

Instalowanie certyfikatu emulatora

Emulator usługi Cosmos DB używa certyfikatu SSL z podpisem własnym. Pobierz i ufaj temu certyfikatowi, aby konstruktor interfejsu API danych mógł nawiązać połączenie z emulatorem.

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"

Tworzenie bazy danych i danych początkowych

Użyj wbudowanego Eksploratora danych emulatora, aby utworzyć bazę danych, kontener i przykładowe elementy. Nie są potrzebne żadne dodatkowe narzędzia — Eksplorator danych działa w przeglądarce w ramach emulatora.

1. Otwórz Eksploratora danych pod adresem https://localhost:8081/_explorer/index.html.

2. Wybierz pozycję Nowa baza danych. Wprowadź todos jako identyfikator bazy danych i wybierz OK.

3. Rozwiń bazę danych todos , wybierz menu wielokropka (...), a następnie wybierz pozycję Nowy kontener. Wprowadź todos jako identyfikator kontenera i /id jako klucz partycji, a następnie wybierz OK.

4. Rozwiń kontener todos i wybierz pozycję Elementy. Następnie wybierz pozycję Nowy element, zastąp domyślny kod JSON następującą zawartością, a następnie wybierz pozycję Zapisz. Powtórz dla każdego elementu.

   Element 1:

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

   Element 2:

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

   Element 3:

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

Tworzenie pliku schematu GraphQL

Usługa Azure Cosmos DB for NoSQL wymaga pliku schematu GraphQL. Utwórz plik o nazwie schema.gql z następującą zawartością.

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

Konfigurowanie konstruktora interfejsu API danych

1. Zainicjuj konfigurację przy użyciu domyślnych parametrów połączenia emulatora.

   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. Dodaj jednostkę Todo .

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

Plik dab-config.json powinien teraz wyglądać podobnie do poniższego przykładu:

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

Uruchamianie interfejsu API

Użyj dab start, aby uruchomić narzędzie i utworzyć punkty końcowe interfejsu API dla jednostki.

dab start

Dane wyjściowe powinny zawierać adres uruchomionego interfejsu API.

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

Testowanie interfejsu API

1. Otwórz przeglądarkę i przejdź do punktu końcowego GraphQL.

   http://localhost:5000/graphql
   

   W trybie programowania ten adres URL otwiera środowisko IDE Nitro GraphQL.

2. Utwórz nowy dokument i uruchom następujące zapytanie, aby pobrać wszystkie elementy zadań do wykonania.

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

3. Odpowiedź powinna zawierać wszystkie trzy zadania do wykonania.

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

Czyszczenie

Zatrzymaj i usuń kontener Docker po zakończeniu.

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

Następne kroki

Treści powiązane

• Konfigurowanie konstruktora interfejsu API danych dla usługi Azure Cosmos DB dla noSQL
• Dostępność funkcji dla konstruktora interfejsu API danych