Szybki start: użycie narzędzia API danych do obsługi NoSQL

2025-06-11

W tym szybkim starcie utworzysz zestaw plików konfiguracji Data API przeznaczonych do emulatora usługi Azure Cosmos DB for NoSQL.

Wymagania wstępne

Doker
.NET 8
Klient zarządzania danymi
- Jeśli nie masz zainstalowanego klienta, zainstaluj program Azure Data Studio

Wskazówka

Alternatywnie otwórz Szybki start w usłudze GitHub Codespaces ze wszystkimi wymaganiami wstępnymi dla programistów już zainstalowanymi. Po prostu przynieś własną subskrypcję platformy Azure. Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.

Zainstaluj narzędzie wiersza polecenia Data API builder

Zainstaluj pakiet z NuGet jako narzędzie .NET.

Użyj dotnet tool install do zainstalowania najnowszej wersji Microsoft.DataApiBuilder z argumentem --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
```
Sprawdź, czy narzędzie jest zainstalowane za pomocą dotnet tool list przy użyciu argumentu --global.
```
dotnet tool list --global
```

Konfigurowanie lokalnej bazy danych

Rozpocznij od uruchomienia lokalnego emulatora. Następnie możesz wypełnić nowy kontener przykładowymi danymi.

Pobierz najnowszą kopię obrazu kontenera mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest z usługi Docker Hub.
```
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
```

Uruchom kontener platformy Docker, publikując port 8081 i zakres portów 10250-10255.

docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Pobieranie certyfikatu z podpisem własnym dla emulatora

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

Zainstaluj samopodpisany certyfikat, korzystając z kroków powłoki Bash dla systemu Linux lub kroków programu PowerShell dla systemu Windows.
```
sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```
```
certutil -f -addstore "Root" emulatorcert.crt
```
Połącz się z lokalną bazą danych przy użyciu preferowanego środowiska zarządzania danymi. Przykłady obejmują, ale nie są ograniczone do: Azure Data Studio i rozszerzenia Azure Databases dla programu Visual Studio Code.

Wskazówka

Domyślne parametry połączenia emulatora to AccountEndpoint=https://localhost:8081;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;.
Utwórz nową bookshelf bazę danych i authors kontener.

Zaimekuj kontener przy użyciu tych podstawowych danych JSON.

[
  {
    "id": "01",
    "firstName": "Henry",
    "lastName": "Ross"
  },
  {
    "id": "02",
    "firstName": "Jacob",
    "middleName": "A.",
    "lastName": "Hancock"
  },
  {
    "id": "03",
    "firstName": "Sydney",
    "lastName": "Mattos"
  },
  {
    "id": "04",
    "firstName": "Jordan",
    "lastName": "Mitchell"
  },
  {
    "id": "05",
    "firstName": "Victoria",
    "lastName": "Burke"
  },
  {
    "id": "06",
    "firstName": "Vance",
    "lastName": "DeLeon"
  },
  {
    "id": "07",
    "firstName": "Reed",
    "lastName": "Flores"
  },
  {
    "id": "08",
    "firstName": "Felix",
    "lastName": "Henderson"
  },
  {
    "id": "09",
    "firstName": "Avery",
    "lastName": "Howard"
  },
  {
    "id": "10",
    "firstName": "Violet",
    "lastName": "Martinez"
  }
]

Wskazówka

Metoda używana do rozmieszczania danych będzie w dużej mierze zależeć od narzędzia do zarządzania danymi. W przypadku narzędzia Azure Data Studio można zapisać tę tablicę JSON jako plik .json , a następnie użyć funkcji Importuj .

Tworzenie plików konfiguracji

Utwórz plik konfiguracji bazowej przy użyciu interfejsu wiersza polecenia DAB. Następnie dodaj plik konfiguracji programowania przy użyciu bieżących poświadczeń.

Utwórz nowy plik o nazwie schema.graphql z tą zawartością schematu.

type Author @model {
  id: ID!
  firstName: String!
  middleName: String
  lastName: String!
}

Utwórz typowy plik konfiguracji przy użyciu polecenia dab init. --connection-string Dodaj argument z domyślnymi parametrami połączenia emulatora.

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

Dodaj jednostkę Author przy użyciu polecenia dab add.

dab add Author --source "authors" --permissions "anonymous:*"

Testowanie interfejsu API przy użyciu lokalnej bazy danych

Teraz uruchom narzędzie konstruktora interfejsu API danych, aby sprawdzić, czy pliki konfiguracji są scalane podczas opracowywania.

Użyj dab start, aby uruchomić narzędzie i utworzyć punkty końcowe API dla swojej jednostki.
```
dab start
```
Dane wyjściowe narzędzia powinny zawierać adres używany do przechodzenia do uruchomionego interfejsu API.
```
      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>
info: Microsoft.Hosting.Lifetime[0]
```
Wskazówka

W tym przykładzie aplikacja działa na localhost porcie 5000. Uruchomiona aplikacja może mieć inny adres i port.
Przejdź do punktu końcowego GraphQL, przechodząc do /graphql i uruchamiając tę operację.
```
query {
  authors {
    items {
      id
      firstName
      lastName
    }
  }
}
```
Wskazówka

W tym przykładzie adres URL będzie https://localhost:5000/graphql. Możesz przejść do tego adresu URL przy użyciu przeglądarki internetowej.

Następny krok

Szybki start: wdrażanie konstruktora interfejsu API danych na platformie Azure