Rychlý start: Vytvoření webového rozhraní API .NET pomocí rozhraní API služby Azure Cosmos DB pro MongoDB

PLATÍ PRO: Rozhraní API služby Azure Cosmos DB pro MongoDB

Tento rychlý start ukazuje, jak:

  1. Vytvoření účtu rozhraní API služby Azure Cosmos DB pro MongoDB
  2. Vytvoření webového rozhraní API katalogu produktů pomocí ovladače MongoDB .NET
  3. Import ukázkových dat

Požadavky na spuštění ukázkové aplikace

Vytvoření účtu databáze

  1. V novém okně prohlížeče se přihlaste k webu Azure Portal.

  2. V nabídce vlevo vyberte Vytvořit prostředek.

    Screenshot of creating a resource in the Azure portal.

  3. Na stránce Nový vyberte DatabasesAzure>Cosmos DB.

    Screenshot of the Azure portal Databases pane.

  4. Na stránce vybrat rozhraní API vyberte rozhraní API služby Azure Cosmos DB pro MongoDBCreate>.

    Rozhraní API určuje typ účtu, který se má vytvořit. Vyberte rozhraní API služby Azure Cosmos DB pro MongoDB, protože v tomto rychlém startu vytvoříte kolekci, která funguje s MongoDB. Další informace najdete v tématu Přehled rozhraní API služby Azure Cosmos DB pro MongoDB.

    Screenshot of the Select API option pane.

  5. Na stránce Vytvořit účet služby Azure Cosmos DB zadejte nastavení nového účtu Azure Cosmos DB.

    Nastavení Hodnota Popis
    Předplatné Název předplatného Vyberte předplatné Azure, které chcete pro tento účet služby Azure Cosmos DB použít.
    Skupina prostředků Název skupiny prostředků Vyberte skupinu prostředků nebo vyberte Vytvořit novou a zadejte jedinečný název nové skupiny prostředků.
    Account Name Zadejte jedinečný název. Zadejte jedinečný název, který identifikuje váš účet služby Azure Cosmos DB. Identifikátor URI vašeho účtu se mongo.cosmos.azure.com připojí k vašemu jedinečnému názvu účtu.

    Název účtu může používat jenom malá písmena, číslice a spojovníky (-) a musí mít délku 3 až 44 znaků.
    Umístění Oblast nejbližší vašim uživatelům Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat. Použijte umístění, které je nejblíže vašim uživatelům, abyste jim poskytli nejrychlejší přístup k datům.
    Režim kapacity Zřízená propustnost nebo bezserverová Výběrem zřízené propustnosti vytvořte účet v režimu zřízené propustnosti . Výběrem možnosti Bezserverový účet vytvoříte v bezserverovém režimu.

    Poznámka: Účty bez serveru podporují pouze rozhraní MongoDB API verze 4.2, 4.0 a 3.6. Volba 3.2 jako verze vynutí účet ve zřízeném režimu propustnosti.
    Použití slevy na úroveň Free služby Azure Cosmos DB Použít nebo neaplikovat S úrovní Free služby Azure Cosmos DB získáte prvních 1000 RU/s a 25 GB úložiště zdarma v účtu. Přečtěte si další informace o úrovni Free.
    Verze Zvolte požadovanou verzi serveru. Rozhraní API služby Azure Cosmos DB pro MongoDB je kompatibilní se serverem verze 4.2, 4.0, 3.6 a 3.2. Po vytvoření můžete upgradovat nebo downgradovat účet.

    Poznámka

    Můžete mít až jeden bezplatný účet Azure Cosmos DB na předplatné Azure a při vytváření účtu se musíte přihlásit. Pokud nevidíte možnost použít slevu na úroveň Free, znamená to, že u bezplatné úrovně už byl povolený jiný účet v předplatném.

    Screenshot of the new account page for Azure Cosmos DB.

  6. Na kartě Globální distribuce nakonfigurujte následující podrobnosti. Výchozí hodnoty můžete ponechat pro účely tohoto rychlého startu:

    Nastavení Hodnota Popis
    Geografická redundance Zakázat Povolte nebo zakažte globální distribuci vašeho účtu spárováním oblasti s párovou oblastí. Do svého účtu můžete později přidat další oblasti.
    Zápisy do více oblastí Zakázat Funkce zápisů ve více oblastech umožňuje využívat zřízenou propustnost pro databáze a kontejnery po celém světě.

    Poznámka

    Pokud jako režim kapacity vyberete bezserverový režim, nejsou k dispozici následující možnosti:

    • Použít slevu založenou na bezplatné úrovni
    • Geografická redundance
    • Zápisy do více oblastí
  7. Volitelně můžete nakonfigurovat další podrobnosti na následujících kartách:

  8. Vyberte Zkontrolovat a vytvořit.

  9. Vytvoření účtu trvá několik minut. Počkejte na zobrazení blahopřejeme na portálu! Stránka s rozhraním API služby Azure Cosmos DB pro MongoDB je připravená.

    Screenshot of the Azure portal Notifications pane.

Informace o objektovém modelu

Než budete pokračovat v sestavování aplikace, pojďme se podívat na hierarchii prostředků v rozhraní API pro MongoDB a na objektový model, který se používá k vytvoření a přístupu k těmto prostředkům. Rozhraní API pro MongoDB vytvoří prostředky v následujícím pořadí:

  • Účet rozhraní API služby Azure Cosmos DB pro MongoDB
  • Databáze
  • Kolekce
  • dokumenty.

Další informace o hierarchii entit najdete v článku o modelu prostředků Azure Cosmos DB.

Instalace ukázkové šablony aplikace

Tato ukázka je šablona projektu dotnet, která se dá nainstalovat k vytvoření místní kopie. V příkazovém okně spusťte následující příkazy:

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

Předchozí příkazy:

  1. Vytvořte pro ukázku adresář C:\cosmos-samples . Zvolte složku, která je vhodná pro váš operační systém.
  2. Změňte aktuální adresář do složky C:\cosmos-samples .
  3. Nainstalujte šablonu projektu a zpřístupňuje ji globálně z rozhraní příkazového řádku dotnet.
  4. Vytvořte místní ukázkovou aplikaci pomocí šablony projektu.

Pokud nechcete používat rozhraní příkazového řádku dotnet, můžete si také stáhnout šablony projektů jako soubor ZIP. Tato ukázka je ve Templates/APIForMongoDBQuickstart-WebAPI složce.

Kontrola kódu

Následující kroky jsou volitelné. Pokud se chcete dozvědět, jak se v kódu vytvářejí databázové prostředky, projděte si následující fragmenty kódu. V opačném případě přeskočte k aktualizaci nastavení aplikace.

Nastavení připojení

Následující fragment kódu je ze souboru Services/MongoService.cs .

  • Následující třída představuje klienta a je vložen rozhraním .NET Framework do služeb, které ho využívají:

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

Nastavení datové služby katalogu produktů

Následující fragmenty kódu pocházejí ze souboru Services/ProductService.cs .

  • Následující kód načte databázi a kolekci a vytvoří je, pokud ještě neexistují:

    private readonly IMongoCollection<Product> _products;        
    
    public ProductService(MongoService mongo, IDatabaseSettings settings)
    {
        var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
        _products = db.GetCollection<Product>(settings.ProductCollectionName);
    }
    
  • Následující kód načte dokument podle skladové položky, jedinečného identifikátoru produktu:

    public Task<Product> GetBySkuAsync(string sku)
    {
        return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
    }
    
  • Následující kód vytvoří produkt a vloží ho do kolekce:

    public Task CreateAsync(Product product)
    {
        _products.InsertOneAsync(product);
    }
    
  • Následující kód vyhledá a aktualizuje produkt:

    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 });
    }
    

    Podobně můžete dokumenty odstranit pomocí kolekce. Metoda DeleteOne()

Aktualizace nastavení aplikace

Z Azure Portal zkopírujte informace o připojovacím řetězci:

  1. V Azure Portal vyberte účet Cosmos DB, v levém navigačním panelu vyberte Připojovací řetězec a pak vyberte Klíče pro čtení a zápis. Pomocí tlačítek kopírování na pravé straně obrazovky zkopírujete primární připojovací řetězec do souboru appsettings.json v dalším kroku.

  2. Otevřete soubor appsettings.json.

  3. Zkopírujte hodnotu primárního připojovacího řetězce z portálu (pomocí tlačítka pro kopírování) a nastavte ji jako hodnotu vlastnosti DatabaseSettings.MongoConnectionString v souboru appsettings.json .

  4. Zkontrolujte hodnotu názvu databáze ve vlastnosti DatabaseSettings.DatabaseName v souboru appsettings.json .

  5. Zkontrolujte hodnotu názvu kolekce ve vlastnosti DatabaseSettings.ProductCollectionName v souboru appsettings.json .

Upozornění

Nikdy nekontrolujte hesla ani jiná citlivá data do zdrojového kódu.

Teď jste aplikaci aktualizovali o všechny informace, které potřebuje ke komunikaci se službou Cosmos DB.

Načtení ukázkových dat

Downloadmongoimport, nástroj rozhraní příkazového řádku, který snadno importuje malé objemy dat JSON, CSV nebo TSV. Pomocí nástroje mongoimport načteme ukázková data produktu zadaná ve Data složce tohoto projektu.

Z Azure Portal zkopírujte informace o připojení a zadejte je do následujícího příkazu:

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json
  1. V Azure Portal vyberte účet rozhraní API služby Azure Cosmos DB pro MongoDB, v levém navigačním panelu vyberte Připojovací řetězec a pak vyberte Klíče pro čtení a zápis.

  2. Zkopírujte hodnotu HOSTITELE z portálu (pomocí tlačítka pro kopírování) a zadejte ji místo <HOSTITELE>.

  3. Zkopírujte hodnotu PORT z portálu (pomocí tlačítka pro kopírování) a zadejte ji místo <PORTU>.

  4. Zkopírujte hodnotu USERNAME z portálu (pomocí tlačítka pro kopírování) a zadejte ji místo <UŽIVATELSKÉHO JMÉNA>.

  5. Zkopírujte hodnotu PASSWORD z portálu (pomocí tlačítka pro kopírování) a zadejte ji místo <HESLA>.

  6. Zkontrolujte hodnotu názvu databáze a aktualizujte ji, pokud jste vytvořili něco jiného než cosmicworks.

  7. Zkontrolujte hodnotu názvu kolekce a aktualizujte ji, pokud jste vytvořili něco jiného než products.

Poznámka

Pokud chcete tento krok přeskočit, můžete vytvořit dokumenty se správným schématem pomocí koncového bodu POST poskytnutého v rámci tohoto projektu webového rozhraní API.

Spuštění aplikace

V Visual Studio spusťte aplikaci stisknutím kombinace kláves CTRL+F5. Ve výchozím prohlížeči se spustí aplikace.

Pokud dáváte přednost rozhraní příkazového řádku, spusťte v příkazovém okně následující příkaz a spusťte ukázkovou aplikaci. Tento příkaz také nainstaluje závislosti projektu a sestaví projekt, ale automaticky nespustí prohlížeč.

dotnet run

Po spuštění aplikace přejděte do https://localhost:5001/swagger/index.htmldokumentace swaggeru pro webové rozhraní API a odešlete ukázkové žádosti.

Vyberte rozhraní API, které chcete otestovat, a vyberte Vyzkoušet.

Screenshot of the web API Swagger UI Try API endpoints page.

Zadejte všechny potřebné parametry a vyberte Provést.

Vyčištění prostředků

Až skončíte s aplikací a účtem Azure Cosmos DB, můžete prostředky Azure, které jste vytvořili, odstranit, takže vám nebudou účtovány další poplatky. Odstranění prostředků:

  1. Na panelu hledání Azure Portal vyhledejte a vyberte skupiny prostředků.

  2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro účely tohoto rychlého startu.

    Select the resource group to delete

  3. Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.

    Delete the resource group

  4. V dalším okně zadejte název skupiny prostředků, která chcete odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet API pro MongoDB, vytvořit databázi a kolekci s kódem a spustit aplikaci webového rozhraní API. Teď můžete do databáze importovat další data.

Pokoušíte se naplánovat kapacitu migrace do azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.