Snabbstart: Skapa ett .NET-webb-API Azure Cosmos DB med hjälp av API:et för MongoDB

GÄLLER för: Azure Cosmos DB-API för MongoDB

Den här snabbstarten visar hur du:

1. Skapa ett Azure Cosmos DB-API för MongoDB-konto
2. Skapa ett webb-API för produktkatalog med MongoDB .NET-drivrutinen
3. Importera exempeldata

Nödvändiga förutsättningar för att köra exempelappen

• Visual Studio
• .NET 5.0
• Ett Azure-konto med en aktiv prenumeration. Skapa ett Azure-konto utan kostnad. Du kan också prova Azure Cosmos DB utan en Azure-prenumeration, utan kostnad och åtaganden.

Om du inte redan har Visual Studio laddar du ned Visual Studio 2019 Community Edition med arbetsbelastningen ASP.NET och webbutveckling installerad med installationsprogrammet.

Skapa ett databaskonto

1. Logga in på Azure Portal i ett nytt webbläsarfönster.

2. I den vänstra menyn väljer du Skapa en resurs.

   

3. På sidan Nytt väljer du Databaser > Azure Cosmos DB.

   

4. På sidan Välj API-alternativ väljer du Azure Cosmos DB API för MongoDB > Skapa.

   API:et avgör vilken typ av konto som skapas. Välj Azure Cosmos DB API för MongoDB eftersom du ska skapa en samling som fungerar med MongoDB i den här snabbstarten. Mer information finns i Översikt över Azure Cosmos DB API för MongoDB.

   

5. På sidan Azure Cosmos DB konto anger du inställningarna för det nya Azure Cosmos DB konto.

   Inställning	Värde	Beskrivning
   Prenumeration	Prenumerationens namn	Välj den Azure-prenumeration som ska användas för det här Azure Cosmos DB-kontot.
   Resursgrupp	Namn på resursgrupp	Välj en resursgrupp eller välj Skapa ny och ange sedan ett unikt namn för den nya resursgruppen.
   Account Name	Ange ett unikt namn	Ange ett unikt namn som identifierar ditt Azure Cosmos DB-konto. Din konto-URI mongo.cosmos.azure.com till ditt unika kontonamn. Kontonamnet får bara innehålla gemener, siffror och bindestreck (-) och måste vara mellan 3 och 44 tecken långt.
   Location	Den region som är närmast dina användare	Välj en geografisk plats som värd för ditt Azure Cosmos DB-konto. Använd den plats som är närmast dina användare för att ge dem så snabb åtkomst till data som möjligt.
   Kapacitetsläge	Etablerat dataflöde eller serverlöst	Välj Etablerat dataflöde för att skapa ett konto i etablerat dataflödesläge. Välj Serverlös för att skapa ett konto i serverlöst läge. Obs! Endast MongoDB API-versionerna 4 och 3.6 stöds av serverlösa konton. Om du väljer 3.2 som version tvingar du kontot i etablerat dataflödesläge.
   Tillämpa Azure Cosmos DB rabatt på den kostnadsfria nivån	Tillämpa eller Tillämpa inte	Med Azure Cosmos DB kostnadsfri nivå får du de första 1 000 RU/s och 25 GB lagringsutrymme kostnadsfritt i ett konto. Läs mer om den kostnadsfria nivån.
   Version	Välj den serverversion som krävs	Azure Cosmos DB API för MongoDB är kompatibelt med serverversion 4.0, 3.6 och 3.2. Du kan uppgradera eller nedgradera ett konto när det har skapats.

   Anteckning

   Du kan ha upp till en kostnadsfri nivå Azure Cosmos DB per Azure-prenumeration och måste välja när du skapar kontot. Om du inte ser alternativet för att tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

   

6. Konfigurera följande information på fliken Global distribution. Du kan lämna standardvärdena för den här snabbstarten:

   Inställning	Värde	Beskrivning
   Geo-redundans	Inaktivera	Aktivera eller inaktivera global distribution på ditt konto genom att koppla ihop din region med en parregion. Du kan lägga till fler regioner i ditt konto senare.
   Skrivåtgärder för flera regioner	Inaktivera	Med skrivfunktioner för flera regioner kan du dra nytta av det etablerade dataflödet för dina databaser och containrar över hela världen.

   Anteckning

   Följande alternativ är inte tillgängliga om du väljer Serverlös som Kapacitetsläge:

   • Tillämpa rabatt för kostnadsfri nivå
   • Geo-redundans
   • Skrivåtgärder för flera regioner

7. Du kan också konfigurera ytterligare information på följande flikar:

   • Nätverk – Konfigurera åtkomst från ett virtuellt nätverk.
   • Säkerhetskopieringspolicy – Konfigurera antingen periodisk eller kontinuerlig säkerhetskopieringspolicy.
   • Kryptering – Använd antingen en tjänst hanterad nyckel eller en kund hanterad nyckel.
   • Taggar – Taggar är namn/värde-par som gör att du kan kategorisera resurser och visa konsoliderad fakturering genom att tillämpa samma tagg på flera resurser och resursgrupper.

8. Välj Granska + skapa.

9. Det tar några minuter att skapa kontot. Vänta tills portalen visar grattis! Ditt Azure Cosmos DB API för MongoDB-kontot är klart.

   

Lär dig objektmodellen

Innan du fortsätter att skapa programmet ska vi titta närmare på resurshierarkin i API:et för MongoDB och objektmodellen som används för att skapa och komma åt dessa resurser. API:et för MongoDB skapar resurser i följande ordning:

• Azure Cosmos DB API för MongoDB-konto
• Databaser
• Samlingar
• Dokument

Mer information om entitetshierarkin finns i artikeln Azure Cosmos DB om resursmodell.

Installera exempelappmallen

Det här exemplet är en projektmall för dotnet som kan installeras för att skapa en lokal kopia. Kör följande kommandon i ett kommandofönster:

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

Föregående kommandon:

1. Skapa katalogen C:\cosmos-samples för exemplet. Välj en mapp som passar ditt operativsystem.
2. Ändra din aktuella katalog till mappen C:\cosmos-samples.
3. Installera projektmallen så att den blir tillgänglig globalt från dotnet CLI.
4. Skapa en lokal exempelapp med hjälp av projektmallen.

Om du inte vill använda dotnet CLI kan du också ladda ned projektmallarna som en ZIP-fil. Det här exemplet finns i Templates/APIForMongoDBQuickstart-WebAPI mappen .

Granska koden

Följande steg är valfria. Om du vill lära dig hur databasresurserna skapas i koden kan du granska följande kodavsnitt. Annars kan du gå vidare till Uppdatera programinställningarna.

Konfigurera anslutning

Följande kodfragment kommer från filen Services/MongoService.cs.

• Följande klass representerar klienten och matas in av .NET Framework i tjänster som använder den:

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

Konfigurera produktkatalogens datatjänst

Följande kodfragment kommer från filen Services/ProductService.cs.

• Följande kod hämtar databasen och samlingen och skapar dem om de inte redan finns:

  private readonly IMongoCollection<Product> _products;        
  
  public ProductService(MongoService mongo, IDatabaseSettings settings)
  {
      var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
      _products = db.GetCollection<Product>(settings.ProductCollectionName);
  }
  

• Följande kod hämtar ett dokument efter SKU, en unik produktidentifierare:

  public Task<Product> GetBySkuAsync(string sku)
  {
      return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
  }
  

• Följande kod skapar en produkt och infogar den i samlingen:

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

• Följande kod hittar och uppdaterar en 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 });
  }
  

  På samma sätt kan du ta bort dokument med hjälp av samlingen. DeleteOne()-metod.

Uppdatera programinställningarna

Från Azure Portal kopierar du informationen om anslutningssträngen:

1. I Azure Portal väljerdu ditt Cosmos DB-konto. I det vänstra navigeringsfönstret väljer du Anslutningssträng och sedan Läs- och skrivnycklar. Du använder kopieringsknapparna till höger på skärmen för att kopiera den primära anslutningssträngen till filen appsettings.json i nästa steg.

2. Öppna filen appsettings.json.

3. Kopiera värdet för den primära anslutningssträngen från portalen (med kopieringsknappen) och gör det till värdet för egenskapen DatabaseSettings.MongoConnectionString i filen appsettings.json.

4. Granska värdet för databasnamnet i egenskapen DatabaseSettings.DatabaseName i filen appsettings.json.

5. Granska värdet för samlingsnamnet i egenskapen DatabaseSettings.ProductCollectionName i filen appsettings.json.

Du har nu uppdaterat din app med all information den behöver för att kommunicera med Cosmos DB.

Läsa in exempeldata

Ladda ned mongoimport, ett CLI-verktyg som enkelt importerar små mängder JSON-, CSV- eller TSV-data. Vi använder mongoimport för att läsa in exempelproduktdata som finns i Data mappen för det här projektet.

Från Azure Portal kopierar du anslutningsinformationen och anger den i kommandot nedan:

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json

1. I Azure Portalväljer du ditt Azure Cosmos DB API för MongoDB-konto. I det vänstra navigeringsfönstret väljer du Anslutningssträng och sedan Läs-skrivnycklar.

2. Kopiera värdvärdet från portalen (med kopieringsknappen) och ange det i stället för <HOST> .

3. Kopiera VÄRDET PORT från portalen (med kopieringsknappen) och ange det i stället för <PORT> .

4. Kopiera värdet USERNAME (ANVÄNDARNAMN) från portalen (med kopieringsknappen) och ange det i stället för <USERNAME> .

5. Kopiera lösenordsvärdet från portalen (med kopieringsknappen) och ange det i stället för <PASSWORD> .

6. Granska värdet för databasnamnet och uppdatera det om du har skapat något annat än cosmicworks .

7. Granska värdet för samlingsnamnet och uppdatera det om du har skapat något annat än products .

Kör appen

I Visual Studio du CTRL + F5 för att köra appen. Standardwebbläsaren startas med appen.

Om du föredrar CLI kör du följande kommando i ett kommandofönster för att starta exempelappen. Det här kommandot installerar även projektberoenden och skapar projektet, men startar inte webbläsaren automatiskt.

dotnet run

När programmet körs går du till för att https://localhost:5001/swagger/index.html se Swagger-dokumentationen för webb-API:et och för att skicka exempelbegäranden.

Välj det API som du vill testa och välj "Testa".

Ange nödvändiga parametrar och välj "Kör".

Rensa resurser

När du är klar med din app och Azure Cosmos DB-konto kan du ta bort de Azure-resurser som du skapade så att du inte debiteras mer. Ta bort resurser:

1. I sökfältet Azure Portal du efter och väljer Resursgrupper.

2. I listan väljer du den resursgrupp som du skapade för den här snabbstarten.

   

3. På sidan Översikt för resursgruppen väljer du Ta bort resursgrupp.

   

4. I nästa fönster anger du namnet på den resursgrupp som ska tas bort och väljer sedan Ta bort.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett API för MongoDB-konto, skapar en databas och en samling med kod och kör en webb-API-app. Du kan nu importera ytterligare data till databasen.

Försöker du göra kapacitetsplanering för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.

• Om allt du vet är antalet virtuella kärnor och servrar i ditt befintliga databaskluster kan du läsa om att uppskatta enheter för programbegäran med hjälp av virtuella kärnor eller virtuella processorer
• Om du känner till typiska begärandefrekvenser för din aktuella databasarbetsbelastning kan du läsa om att uppskatta enheter för programbegäran Azure Cosmos DB kapacitetsplaneraren