Szybki start: tworzenie internetowego interfejsu API platformy .NET przy użyciu interfejsu API usługi Azure Cosmos DB dla bazy danych MongoDB

DOTYCZY: Azure Cosmos DB API for MongoDB

W tym przewodniku Szybki start pokazano, jak:

  1. Tworzenie interfejsu API usługi Azure Cosmos DB dla konta bazy danych MongoDB
  2. Tworzenie internetowego interfejsu API katalogu produktów przy użyciu sterownika mongoDB dla platformy .NET
  3. Importowanie przykładowych danych

Wymagania wstępne dotyczące uruchamiania przykładowej aplikacji

Jeśli nie masz jeszcze konta usługi Visual Studio, pobierz program Visual Studio 2019 Community Edition z zainstalowanym obciążeniem ASP.NET i tworzeniem aplikacji internetowych z instalatorem.

Tworzenie konta bazy danych

  1. W nowym oknie przeglądarki zaloguj się do witryny Azure Portal.

  2. W menu po lewej stronie wybierz pozycję Utwórz zasób.

    Zrzut ekranu przedstawiający tworzenie zasobu w Azure Portal.

  3. Na stronie Nowy wybierz pozycję Bazy > danych Azure Cosmos DB.

    Zrzut ekranu przedstawiający okienko Azure Portal Bazy danych.

  4. Na stronie opcji Wybierz interfejs API wybierz pozycję Interfejs API usługi Azure Cosmos DB dla bazy danych MongoDB > Utwórz.

    Interfejs API określa typ konta do utworzenia. Wybierz pozycję Interfejs API usługi Azure Cosmos DB dla bazy danych MongoDB, ponieważ w tym przewodniku Szybki start utworzysz kolekcję, która współpracuje z bazą danych MongoDB. Aby dowiedzieć się więcej, zobacz Omówienie interfejsu API usługi Azure Cosmos DB dla bazy danych MongoDB.

    Zrzut ekranu przedstawiający okienko opcji Wybierz interfejs API.

  5. Na stronie Tworzenie konta usługi Azure Cosmos DB wprowadź ustawienia nowego konta usługi Azure Cosmos DB.

    Ustawienie Wartość Opis
    Subskrypcja Nazwa subskrypcji Wybierz subskrypcję platformy Azure, której chcesz użyć dla tego konta usługi Azure Cosmos DB.
    Grupa zasobów Nazwa grupy zasobów Wybierz grupę zasobów lub wybierz pozycję Utwórz nową, a następnie wprowadź unikatową nazwę nowej grupy zasobów.
    Nazwa konta Wprowadź unikatową nazwę Wprowadź unikatową nazwę do identyfikacji konta usługi Azure Cosmos DB. Identyfikator URI twojego konta mongo.cosmos.azure.com dołączony do Twojej unikatowej nazwy konta.

    Nazwa konta może używać tylko małych liter, cyfr i łączników (-) i musi mieć od 3 do 44 znaków.
    Lokalizacja Region najbliżej Twoich użytkowników Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB. Użyj lokalizacji znajdującej się najbliżej Twoich użytkowników, aby zapewnić im najszybszy dostęp do danych.
    Tryb wydajności Aprowizowana przepływność lub bez serwera Wybierz pozycję Aprowizowana przepływność, aby utworzyć konto w trybie aprowizowanej przepływności. Wybierz pozycję Bez serwera, aby utworzyć konto w trybie bez serwera.

    Uwaga: tylko interfejs API usługi MongoDB w wersji 4 i 3.6 jest obsługiwany przez konta bez serwera. Wybranie wersji 3.2 wymusi na koncie aprowizowany tryb przepływności.
    Stosowanie rabatu w warstwie Bezpłatna usługi Azure Cosmos DB Zastosuj lub Nie zastosuj W przypadku usługi Azure Cosmos DB w warstwie Bezpłatna otrzymasz bezpłatnie pierwsze 1000 RU/s i 25 GB miejsca do magazynowania na koncie. Dowiedz się więcej o warstwie Bezpłatna.
    Wersja Wybierz wymaganą wersję serwera Interfejs API usługi Azure Cosmos DB dla bazy danych MongoDB jest zgodny z wersją serwera 4.0, 3.6 i 3.2. Po utworzeniu konta można podwyższyć lub obniżyć jego poziom.

    Uwaga

    W ramach jednej subskrypcji platformy Azure można korzystać z maksymalnie jednego konta usługi Azure Cosmos DB w warstwie Bezpłatna. Tę opcję należy wybrać podczas tworzenia konta. Jeśli opcja zastosowania rabatu na podstawie warstwy Bezpłatna nie jest widoczna, inne konto w subskrypcji już korzysta z warstwy Bezpłatna.

    Zrzut ekranu przedstawiający stronę nowego konta dla usługi Azure Cosmos DB.

  6. Na karcie Dystrybucja globalna skonfiguruj następujące szczegóły. Na potrzeby tego przewodnika Szybki start możesz pozostawić wartości domyślne:

    Ustawienie Wartość Opis
    Nadmiarowość geograficzna Wyłącz Włącz lub wyłącz dystrybucję globalną na swoim koncie, parując region z regionem pary. Później możesz dodać więcej regionów do swojego konta.
    Moduły zapisujące obsługujące wiele regionów Wyłącz Funkcja zapisu w wielu regionach umożliwia korzystanie z aprowizowanej przepływności dla baz danych i kontenerów na całym świecie.

    Uwaga

    Następujące opcje nie są dostępne w przypadku wybrania opcji Bez serwera w trybie pojemności:

    • Zastosuj rabat na podstawie warstwy Bezpłatna
    • Nadmiarowość geograficzna
    • Moduły zapisujące obsługujące wiele regionów
  7. Opcjonalnie możesz skonfigurować dodatkowe szczegóły na następujących kartach:

    • Sieć — skonfiguruj dostęp z sieci wirtualnej.
    • Zasady kopii zapasowych — skonfiguruj zasady okresowych lub ciągłych kopii zapasowych.
    • Szyfrowanie — użyj klucza zarządzanego przez usługę lub klucza zarządzanego przez klienta.
    • Tagi — tagi to pary nazwa/wartość, które umożliwiają kategoryzowanie zasobów i wyświetlanie skonsolidowanych rozliczeń przez zastosowanie tego samego tagu do wielu zasobów i grup zasobów.
  8. Wybierz pozycję Przejrzyj i utwórz.

  9. Tworzenie konta potrwa kilka minut. Poczekaj na wyświetlenie w portalu ekranu Gratulacje! Interfejs API usługi Azure Cosmos DB dla konta bazy danych MongoDB jest gotowy.

    Zrzut ekranu przedstawiający okienko Azure Portal powiadomienia.

Poznasz model obiektów

Przed kontynuowaniem tworzenia aplikacji przyjrzyjmy się hierarchii zasobów w interfejsie API dla bazy danych MongoDB oraz modelowi obiektów używanego do tworzenia tych zasobów i uzyskiwania do nich dostępu. Interfejs API dla bazy danych MongoDB tworzy zasoby w następującej kolejności:

  • Interfejs API usługi Azure Cosmos DB dla konta bazy danych MongoDB
  • Bazy danych
  • Kolekcje
  • Dokumenty

Aby dowiedzieć się więcej na temat hierarchii jednostek, zobacz artykuł Model zasobów usługi Azure Cosmos DB.

Instalowanie przykładowego szablonu aplikacji

Ten przykład to szablon projektu dotnet, który można zainstalować w celu utworzenia kopii lokalnej. Uruchom następujące polecenia w oknie polecenia:

mkdir "C:\cosmos-samples"
cd "C:\cosmos-samples"
dotnet new -i Microsoft.Azure.Cosmos.Templates
dotnet new cosmosmongo-webapi

Powyższe polecenia:

  1. Utwórz katalog C:\cosmos-samples dla przykładu. Wybierz folder odpowiedni dla twojego systemu operacyjnego.
  2. Zmień bieżący katalog na folder C:\cosmos-samples.
  3. Zainstaluj szablon projektu, aby był dostępny globalnie z interfejsu wiersza polecenia dotnet.
  4. Utwórz lokalną przykładową aplikację przy użyciu szablonu projektu.

Jeśli nie chcesz używać interfejsu wiersza polecenia dotnet, możesz również pobrać szablony projektu jako plik ZIP. Ten przykład znajduje się w Templates/APIForMongoDBQuickstart-WebAPI folderze .

Przeglądanie kodu

Poniższe kroki są opcjonalne. Jeśli chcesz dowiedzieć się, jak zasoby bazy danych są tworzone w kodzie, zapoznaj się z poniższymi fragmentami kodu. W przeciwnym razie przejdź do tematu Aktualizowanie ustawień aplikacji.

Konfigurowanie połączenia

Poniższy fragment kodu pochodzi z pliku Services/MongoService.cs.

  • Następująca klasa reprezentuje klienta i jest wstrzykiwana przez platformę .NET do usług, które go zużywają:

        public class MongoService
        {
            private static MongoClient _client;
    
            public MongoService(IDatabaseSettings settings)
            {
                _client = new MongoClient(settings.MongoConnectionString);
            }
    
            public MongoClient GetClient()
            {
                return _client;
            }
        }
    

Konfigurowanie usługi danych katalogu produktów

Poniższe fragmenty kodu znajdują się w pliku Services/ProductService.cs.

  • Poniższy kod pobiera bazę danych i kolekcję i utworzy je, jeśli jeszcze nie istnieją:

    private readonly IMongoCollection<Product> _products;        
    
    public ProductService(MongoService mongo, IDatabaseSettings settings)
    {
        var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
        _products = db.GetCollection<Product>(settings.ProductCollectionName);
    }
    
  • Poniższy kod pobiera dokument według jednostki SKU, unikatowego identyfikatora produktu:

    public Task<Product> GetBySkuAsync(string sku)
    {
        return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
    }
    
  • Poniższy kod tworzy produkt i wstawia go do kolekcji:

    public Task CreateAsync(Product product)
    {
        _products.InsertOneAsync(product);
    }
    
  • Poniższy kod umożliwia znalezienie i aktualizację produktu:

    public Task<Product> UpdateAsync(Product update)
    {
        return _products.FindOneAndReplaceAsync(
            Builders<Product>.Filter.Eq(p => p.Sku, update.Sku), 
            update, 
            new FindOneAndReplaceOptions<Product> { ReturnDocument = ReturnDocument.After });
    }
    

    Podobnie dokumenty można usuwać przy użyciu kolekcji . DeleteOne(), metoda.

Aktualizowanie ustawień aplikacji

Z Azure Portal skopiuj informacje o parametrów połączenia:

  1. W witrynie Azure Portalwybierz konto Cosmos DB, na lewym pasku nawigacyjnym wybierz pozycję Connection String(Ciąg połączenia), a następnie wybierz pozycję Read-write Keys (Klucze odczytu i zapisu). W następnym kroku użyjesz przycisków kopiowania po prawej stronie ekranu, aby skopiować podstawowe ciągi połączenia do pliku appsettings.json.

  2. Otwórz plik appsettings.json.

  3. Skopiuj wartość podstawowych parametrów połączenia z portalu (przy użyciu przycisku kopiowania) i nadaj jej wartość właściwości DatabaseSettings.MongoConnectionString w pliku appsettings.json.

  4. Sprawdź wartość nazwy bazy danych we właściwości DatabaseSettings.DatabaseName w pliku appsettings.json.

  5. Sprawdź wartość nazwy kolekcji we właściwości DatabaseSettings.ProductCollectionName w pliku appsettings.json.

Ostrzeżenie

Nigdy nie sprawdzaj haseł lub innych poufnych danych w kodzie źródłowym.

Aplikacja została zaktualizowana i zawiera teraz wszystkie informacje potrzebne do komunikowania się z usługą Cosmos DB.

Ładowanie przykładowych danych

Pobierz narzędzie mongoimport— narzędzie interfejsu wiersza polecenia, które umożliwia łatwe importowanie małych ilości danych JSON, CSV lub TSV. Użyjemy programu mongoimport do załadowania przykładowych danych produktu podanych Data w folderze tego projektu.

Z Azure Portal skopiuj informacje o połączeniu i wprowadź je w poniższym poleceniu:

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json
  1. W witrynie Azure Portalwybierz konto interfejsu API usługi Azure Cosmos DB dla bazy danych MongoDB, w lewym okienku nawigacji wybierz pozycję Connection String(Ciąg połączenia), a następnie wybierz pozycję Read-write Keys (Klucze odczytu i zapisu).

  2. Skopiuj wartość HOST z portalu (przy użyciu przycisku kopiowania) i wprowadź ją w miejsce wartości <HOST> .

  3. Skopiuj wartość PORT z portalu (przy użyciu przycisku kopiowania) i wprowadź ją w miejsce wartości <PORT> .

  4. Skopiuj wartość USERNAME z portalu (przy użyciu przycisku kopiowania) i wprowadź ją w miejsce <USERNAME> .

  5. Skopiuj wartość PASSWORD z portalu (przy użyciu przycisku kopiowania) i wprowadź ją w miejsce <PASSWORD> .

  6. Przejrzyj wartość nazwy bazy danych i zaktualizuj ją, jeśli utworzono coś innego niż cosmicworks .

  7. Przejrzyj wartość nazwy kolekcji i zaktualizuj ją, jeśli utworzono coś innego niż products .

Uwaga

Jeśli chcesz pominąć ten krok, możesz utworzyć dokumenty z poprawnym schematem przy użyciu punktu końcowego POST dostarczonego w ramach tego projektu internetowego interfejsu API.

Uruchamianie aplikacji

W Visual Studio naciśnij klawisze CTRL + F5, aby uruchomić aplikację. Zostanie uruchomiona domyślna przeglądarka z aplikacją.

Jeśli wolisz interfejs wiersza polecenia, uruchom następujące polecenie w oknie polecenia, aby uruchomić przykładową aplikację. To polecenie spowoduje również zainstalowanie zależności projektu i skompilowanie projektu, ale nie spowoduje automatycznego uruchomienia przeglądarki.

dotnet run

Po uruchomieniu aplikacji przejdź do witryny , aby wyświetlić dokumentację programu Swagger dotyczącą internetowego interfejsu API i https://localhost:5001/swagger/index.html przesłać przykładowe żądania.

Wybierz interfejs API, który chcesz przetestować, a następnie wybierz pozycję "Wypróbuj".

Zrzut ekranu przedstawiający stronę wypróbuj punkty końcowe interfejsu API programu Swagger UI dla internetowego interfejsu API.

Wprowadź wszelkie niezbędne parametry i wybierz pozycję "Wykonaj".

Czyszczenie zasobów

Po utworzeniu aplikacji i konta Azure Cosmos DB możesz usunąć utworzone zasoby platformy Azure, aby nie ponosić dodatkowych opłat. Aby usunąć zasoby:

  1. Na pasku Azure Portal wyszukaj i wybierz pozycję Grupy zasobów.

  2. Z listy wybierz grupę zasobów utworzoną na podstawie tego przewodnika Szybki start.

    Wybierz grupę zasobów do usunięcia

  3. Na stronie Przegląd grupy zasobów wybierz pozycję Usuń grupę zasobów.

    Usuwanie grupy zasobów

  4. W następnym oknie wprowadź nazwę grupy zasobów do usunięcia, a następnie wybierz pozycję Usuń.

Następne kroki

W tym przewodniku Szybki start opisano sposób tworzenia interfejsu API dla konta bazy danych MongoDB, tworzenia bazy danych i kolekcji z kodem oraz uruchamiania aplikacji internetowego interfejsu API. Teraz możesz zaimportować dodatkowe dane do bazy danych.

Próbujesz zaplanować pojemność dla migracji do usługi Azure Cosmos DB? Do planowania pojemności można użyć informacji o istniejącym klastrze bazy danych.

  • Jeśli wiesz tylko, ile rdzeni wirtualnych i serwerów znajduje się w istniejącym klastrze bazy danych, przeczytaj o szacowaniu jednostek żądań przy użyciu rdzeni wirtualnych lub procesorów wirtualnych
  • Jeśli znasz typowe stawki żądań dla bieżącego obciążenia bazy danych, przeczytaj o szacowaniu jednostek żądań przy użyciu planisty wydajności usługi Azure Cosmos DB