rychlý start: sestavení webového rozhraní api .net pomocí rozhraní api Azure Cosmos DB pro MongoDB

PLATÍ pro: Azure Cosmos DB API pro MongoDB

Tento rychlý Start ukazuje, jak:

1. vytvoření Azure Cosmos DB API pro účet MongoDB
2. Sestavení 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

• Visual Studio
• .NET 5.0
• Účet Azure s aktivním předplatným. Vytvořte si účet Azure zdarma. můžete také vyzkoušet Azure Cosmos DB bez předplatného Azure, zdarma a závazky.

pokud ještě nemáte Visual Studio, stáhněte Visual Studio 2019 Community edici s úlohou pro ASP.NET a webový vývoj , která je nainstalovaná s instalačním programem.

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.

   

3. na stránce nový vyberte databáze > Azure Cosmos DB.

   

4. na stránce vybrat možnost rozhraní api vyberte Azure Cosmos DB API pro MongoDB > vytvořit.

   Rozhraní API určuje typ účtu, který se má vytvořit. vyberte Azure Cosmos DB API pro MongoDB , protože vytvoříte kolekci, která bude v tomto rychlém startu fungovat s MongoDB. další informace najdete v tématu přehled rozhraní Azure Cosmos DB API pro MongoDB.

   

5. na stránce vytvořit Azure Cosmos DB účet zadejte nastavení pro nový účet 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 nové 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 jedinečnému názvu účtu. Název účtu může obsahovat 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, a poskytněte jim tak nejrychlejší přístup k datům.
   Režim kapacity	Zřízená propustnost nebo bez serveru	Vyberte zřízenou propustnost a vytvořte účet v režimu zřízené propustnosti . Pokud chcete vytvořit účet v režimu bez serveru , vyberte možnost bez serveru . Poznámka: účty bez serveru podporují jenom MongoDB API verze 4 a 3,6. Zvolíte-li možnost 3,2, bude tato verze vynutit účet v režimu zřízené propustnosti.
   použít Azure Cosmos DB slevu úrovně free	Použít nebo nepoužít	u Azure Cosmos DB úrovně free získáte v účtu první 1000 RU/s a 25 GB úložiště zdarma. Přečtěte si další informace o bezplatné úrovni.
   Verze	Vyberte požadovanou verzi serveru.	rozhraní Azure Cosmos DB API pro MongoDB je kompatibilní se serverem verze 4,0, 3,6 a 3,2. Po vytvoření můžete účet aktualizovat nebo downgradovat .

   Poznámka

   v rámci předplatného Azure můžete mít až jednu úroveň bezplatného Azure Cosmos DB účtu a při vytváření účtu musíte souhlasit. Pokud nevidíte možnost použít slevu úrovně Free, znamená to, že v předplatném už je povolený jiný účet s úrovní Free.

   

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

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

   Poznámka

   Pokud jako režim kapacity vyberete možnost bez serveru , nejsou dostupné 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 na následujících kartách nakonfigurovat další podrobnosti:

   • Sítě – konfigurace přístupu z virtuální sítě.
   • Zásady zálohování – nakonfigurujte zásady pravidelného nebo průběžného zálohování.
   • Šifrování – použijte buď klíč spravovaný službou, nebo klíč spravovaný zákazníkem.
   • Značky – značky jsou páry název-hodnota , které umožňují kategorizaci prostředků a zobrazení konsolidované fakturace pomocí stejné značky pro více prostředků a skupin prostředků.

8. Vyberte Zkontrolovat a vytvořit.

9. Vytvoření účtu trvá několik minut. Počkejte, až se na portálu zobrazí blahopřání. stránka Azure Cosmos DB API pro účet MongoDB je připravena .

   

Informace o objektovém modelu

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

• Azure Cosmos DB API pro účet MongoDB
• Databáze
• Kolekce
• dokumenty.

další informace o hierarchii entit najdete v článku Azure Cosmos DB resource model .

Instalace ukázkové šablony aplikace

Tato ukázka je šablonou projektu dotnet, kterou lze nainstalovat pro 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 . Vyberte složku vhodnou pro váš operační systém.
2. Změňte aktuální adresář na složku C:\cosmos-Samples .
3. Nainstalujte šablonu projektu a zpřístupní ji globálně z rozhraní příkazového řádku dotnet.
4. Vytvořte místní ukázkovou aplikaci pomocí šablony projektu.

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

Kontrola kódu

Následující kroky jsou volitelné. Pokud vás zajímá, jak se v kódu vytvářejí prostředky databáze, přečtěte si následující fragmenty kódu. V opačném případě přeskočte dopředu a aktualizujte nastavení aplikace.

Nastavit připojení

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

• Následující třída reprezentuje klienta a je vložena 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 jsou 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 SKU, 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ží jej do kolekce:

  public Task CreateAsync(Product product)
  {
      _products.InsertOneAsync(product);
  }
  

• Následující kód najde 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 odstranit dokumenty pomocí kolekce. DeleteOne () metoda.

Aktualizovat nastavení aplikace

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

1. v Azure Portalvyberte svůj účet Cosmos DB v levém navigačním panelu vyberte připojovací řetězec a pak vyberte klíče pro čtení i zápis. Pomocí tlačítek kopírování na pravé straně obrazovky zkopírujte primární připojovací řetězec do souboru appSettings. JSON v dalším kroku.

2. Otevřete soubor appsettings.json.

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

4. Zkontrolujte hodnotu název databáze ve vlastnosti DatabaseSettings. DatabaseName v souboru appSettings. JSON .

5. Zkontrolujte hodnotu názvu kolekce ve vlastnosti DatabaseSettings. ProductCollectionName v souboru appSettings. JSON .

nyní jste aktualizovali aplikaci o všechny informace, které potřebuje ke komunikaci s Cosmos DB.

Načtení ukázkových dat

Stáhněte si MONGOIMPORT, nástroj CLI, který snadno importuje malé objemy dat JSON, CSV nebo TSV. Použijeme mongoimport k načtení ukázkových dat produktu, která jsou k dispozici 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 Portalvyberte své rozhraní API Azure Cosmos DB pro účet MongoDB, v levém navigačním panelu vyberte připojovací řetězec a pak vyberte klíče pro čtení i zápis.

2. Z portálu Zkopírujte hodnotu hostitel (pomocí tlačítka Kopírovat) a zadejte ji místo <HOST> .

3. Z portálu Zkopírujte hodnotu port (pomocí tlačítka Kopírovat) a zadejte ji místo <PORT> .

4. Z portálu Zkopírujte hodnotu username (pomocí tlačítka Kopírovat) a zadejte ji místo <USERNAME> .

5. Z portálu Zkopírujte hodnotu Password (pomocí tlačítka Kopírovat) a zadejte ji místo <PASSWORD> .

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 .

Spuštění aplikace

z Visual Studio spusťte aplikaci stisknutím CTRL + F5. Výchozí prohlížeč se spustí s aplikací.

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

dotnet run

Po spuštění aplikace přejděte na adresu a https://localhost:5001/swagger/index.html Zobrazte si dokumentaci Swagger pro webové rozhraní API a odešlete ukázkové požadavky.

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

Zadejte potřebné parametry a vyberte Execute (spustit).

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

Až budete s aplikací a Azure Cosmos DB účtem hotovi, můžete odstranit prostředky Azure, které jste vytvořili, abyste se neúčtují 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 tento rychlý Start.

   

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

   

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

Další kroky

V tomto rychlém startu jste se naučili, jak vytvořit rozhraní API pro účet 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.

chcete se pokusit plánování kapacity pro migraci na Azure Cosmos DB? Pro plánování kapacity můžete použít informace o vašem existujícím databázovém clusteru.

• Pokud znáte počet virtuální jádra a serverů v existujícím databázovém clusteru, přečtěte si téma odhadování jednotek žádostí pomocí virtuální jádra nebo vCPU .
• pokud znáte typické míry požadavků pro aktuální databázovou úlohu, přečtěte si téma odhadace jednotek žádostí pomocí Azure Cosmos DB kapacity plánovače .