Quickstart: Een .NET-web-API bouwen met Azure Cosmos DB API voor MongoDB

VAN TOEPASSING OP: Azure Cosmos DB-API voor MongoDB

In deze snelstart wordt het volgende gedemonstreerd:

  1. Een Azure Cosmos DB-API voor MongoDB-account maken
  2. Een web-API voor een productcatalogus bouwen met behulp van het MongoDB .NET-stuurprogramma
  3. Voorbeeldgegevens importeren

Vereisten voor het uitvoeren van de voorbeeld-app

Als u Visual Studio nog niet hebt, downloadt u Visual Studio 2019 Community Edition waarbij de workload ASP.NET-ontwikkeling en webontwikkeling tijdens het instellen wordt geïnstalleerd.

Een databaseaccount maken

  1. Meld u in een nieuw browservenster aan bij Azure Portal.

  2. Selecteer Een resource maken in het menu aan de linkerkant.

    Schermopname van het maken van een resource in Azure Portal.

  3. Selecteer op de pagina Nieuw Databases > Azure Cosmos DB.

    Schermopname van het Azure Portal Databases.

  4. Selecteer op de pagina API-optie selecteren Azure Cosmos DB API voor MongoDB > Maken.

    De API bepaalt het type te maken account. Selecteer Azure Cosmos DB API voor MongoDB omdat u in deze quickstart een verzameling maakt die werkt met MongoDB. Zie Overview of Azure Cosmos DB API for MongoDB (Overzicht van Azure Cosmos DB API voor MongoDB) voor meer informatie.

    Schermopname van het deelvenster API-optie selecteren.

  5. Voer op de pagina Azure Cosmos DB-account maken de instellingen in voor het nieuwe Azure Cosmos DB-account.

    Instelling Waarde Beschrijving
    Abonnement Abonnementsnaam Selecteer het Azure-abonnement dat u voor dit Azure Cosmos DB-account wilt gebruiken.
    Resourcegroep Naam van de resourcegroep Selecteer een resourcegroep of selecteer Nieuwe maken en voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Accountnaam Voer een unieke naam in Voer een unieke naam in om uw Azure Cosmos DB-account te identificeren. Uw account-URI wordt mongo.cosmos.azure.com dat aan uw unieke accountnaam wordt toegevoegd.

    De accountnaam mag alleen kleine letters, cijfers en afbreekstreeken (-) gebruiken en moet tussen de 3 en 44 tekens lang zijn.
    Locatie De regio het dichtst bij uw gebruikers Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
    Capaciteitsmodus Ingerichte doorvoer of serverloos Selecteer Ingerichte doorvoer om een account te maken in de modus Ingerichte doorvoer. Selecteer Serverloos om een account te maken in de modus serverloos.

    Opmerking: alleen MongoDB API-versies 4 en 3.6 worden ondersteund door serverloze accounts. Als u 3.2 als versie kiest, wordt het account in de ingerichte doorvoermodus gedwongen.
    Niveaukorting op gratis laag van Azure Cosmos DB toepassen Toepassen of niet toepassen Met Azure Cosmos DB gratis laag krijgt u de eerste 1000 RU/s en 25 GB aan opslagruimte gratis in een account. Meer informatie over de gratis laag.
    Versie De vereiste serverversie kiezen Azure Cosmos DB API voor MongoDB is compatibel met serverversie 4.0, 3.6 en 3.2. U kunt een account upgraden of downgraden nadat het is gemaakt.

    Notitie

    U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als u de optie voor het toepassen van de korting voor gratis lagen niet ziet, betekent dit dat er al een ander account in het abonnement is ingeschakeld met een gratis laag.

    Schermopname van de nieuwe accountpagina voor Azure Cosmos DB.

  6. Configureer de volgende gegevens op het tabblad Globale distributie. U kunt de standaardwaarden behouden voor deze quickstart:

    Instelling Waarde Beschrijving
    Georedundantie Uitschakelen Schakel globale distributie voor uw account in of uit door uw regio te koppelen met een koppelingsregio. U kunt later meer regio's aan uw account toevoegen.
    Schrijven voor meerdere regio's Uitschakelen Dankzij de mogelijkheid voor schrijfbewerkingen in meerdere regio's kunt over de hele wereld profiteren van de ingerichte doorvoer voor uw databases en containers.

    Notitie

    De volgende opties zijn niet beschikbaar als u Serverloos als Capaciteitsmodus selecteert:

    • Korting voor gratis lagen toepassen
    • Geografische redundantie
    • Schrijven voor meerdere regio's
  7. Optioneel kunt u aanvullende details configureren op de volgende tabbladen:

  8. Selecteer Controleren + maken.

  9. Het duurt enkele minuten om het account te maken. Wacht tot in de portal gefeliciteerd! wordt weergegeven De Azure Cosmos DB API voor MongoDB-account is gereed.

    Schermopname van Azure Portal deelvenster Meldingen.

Meer informatie over het objectmodel

Voordat u verder gaat met het bouwen van de toepassing, kijken we naar de hiërarchie van resources in de API voor MongoDB en het objectmodel dat wordt gebruikt om deze resources te maken en te openen. De API voor MongoDB maakt resources in de volgende volgorde:

  • Azure Cosmos DB-API voor MongoDB-account
  • Databases
  • Verzamelingen
  • Documenten

Zie het artikel Azure Cosmos DB resourcemodel voor meer informatie over de hiërarchie van entiteiten.

De voorbeeld-app-sjabloon installeren

Dit voorbeeld is een dotnet-projectsjabloon, die kan worden geïnstalleerd om een lokale kopie te maken. Voer de volgende opdrachten uit in een opdrachtvenster:

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

De voorgaande opdrachten:

  1. Maak de map C:\cosmos-samples voor het voorbeeld. Kies een map die geschikt is voor uw besturingssysteem.
  2. Wijzig uw huidige map in de map C:\cosmos-samples.
  3. Installeer de projectsjabloon, zodat deze wereldwijd beschikbaar is via de dotnet CLI.
  4. Maak een lokale voorbeeld-app met behulp van de projectsjabloon.

Als u de dotnet-CLI niet wilt gebruiken, kunt u de projectsjablonen ook downloaden als zip-bestand. Dit voorbeeld staat in de Templates/APIForMongoDBQuickstart-WebAPI map .

De code bekijken

De volgende stappen zijn optioneel. Als u wilt weten hoe de databasebronnen in de code worden gemaakt, bekijkt u de volgende codefragmenten. Ga anders verder met De toepassingsinstellingen bijwerken.

Verbinding instellen

Het volgende codefragment is afkomstig uit het bestand Services/MongoService.cs.

  • De volgende klasse vertegenwoordigt de client en wordt door het .NET Framework geïnjecteerd in services die deze gebruiken:

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

Gegevensservice voor productcatalogus instellen

De volgende codefragmenten zijn afkomstig uit het bestand Services/ProductService.cs.

  • Met de volgende code worden de database en de verzameling opgehaald en gemaakt als deze nog niet bestaan:

    private readonly IMongoCollection<Product> _products;        
    
    public ProductService(MongoService mongo, IDatabaseSettings settings)
    {
        var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
        _products = db.GetCollection<Product>(settings.ProductCollectionName);
    }
    
  • Met de volgende code wordt een document opgehaald op sku, een unieke product-id:

    public Task<Product> GetBySkuAsync(string sku)
    {
        return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
    }
    
  • Met de volgende code maakt u een product en voegt u dit in de verzameling in:

    public Task CreateAsync(Product product)
    {
        _products.InsertOneAsync(product);
    }
    
  • Met de volgende code wordt een product gevonden en bijgewerkt:

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

    Op dezelfde manier kunt u documenten verwijderen met behulp van de verzameling . Methode DeleteOne().

De toepassingsinstellingen bijwerken

Kopieer vanuit Azure Portal de volgende connection string gegevens:

  1. Selecteer in Azure Portaluw Cosmos DB account, selecteer in het linkernavigatievenster Verbindingsreeks en selecteer vervolgens Sleutels voor lezen/schrijven. In de volgende stap gebruikt u de kopieerknoppen aan de rechterkant van het scherm om de primaire connection string in het bestand appsettings.json te kopiëren.

  2. Open het bestand appsettings.json.

  3. Kopieer de primaire connection string-waarde van de portal (met behulp van de kopieerknop) en maak er de waarde van de eigenschap DatabaseSettings.MongoConnectionString van in het bestand appsettings.json.

  4. Controleer de waarde van de databasenaam in de eigenschap DatabaseSettings.DatabaseName in het bestand appsettings.json.

  5. Controleer de waarde van de verzamelingsnaam in de eigenschap DatabaseSettings.ProductCollectionName in het bestand appsettings.json.

Waarschuwing

Controleer wachtwoorden of andere gevoelige gegevens nooit in de broncode.

U hebt uw app nu bijgewerkt met alle informatie die nodig is voor de communicatie met Cosmos DB.

Voorbeeldgegevens laden

Download mongoimport,een CLI-hulpprogramma waarmee eenvoudig kleine hoeveelheden JSON-, CSV- of TSV-gegevens kunnen worden geïmporteerd. We gebruiken mongoimport om de voorbeeldproductgegevens in de map van dit Data project te laden.

Kopieer vanuit Azure Portal verbindingsgegevens en voer deze in de onderstaande opdracht in:

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json
  1. Selecteer in Azure Portaluw Azure Cosmos DB-API voor MongoDB-account, selecteer in het linkernavigatievenster Verbindingsreeks en selecteer vervolgens Sleutels voor lezen/schrijven.

  2. Kopieer de waarde host van de portal (met behulp van de kopieerknop) en voer deze in plaats van <HOST> in.

  3. Kopieer de waarde port van de portal (met behulp van de kopieerknop) en voer deze in plaats van <PORT> in.

  4. Kopieer de waarde van USERNAME uit de portal (met behulp van de kopieerknop) en voer deze in plaats van <USERNAME> in.

  5. Kopieer de waarde van PASSWORD uit de portal (met behulp van de kopieerknop) en voer deze in plaats van <PASSWORD> in.

  6. Controleer de waarde van de databasenaam en werk deze bij als u iets anders dan hebt cosmicworks gemaakt.

  7. Controleer de waarde van de verzamelingsnaam en werk deze bij als u iets anders dan hebt products gemaakt.

Notitie

Als u deze stap wilt overslaan, kunt u documenten met het juiste schema maken met behulp van het POST-eindpunt dat is opgegeven als onderdeel van dit web-API-project.

De app uitvoeren

Selecteer Visual Studio CTRL + F5 om de app uit te voeren. De standaardbrowser wordt gestart met de app.

Als u de voorkeur geeft aan de CLI, moet u de volgende opdracht uitvoeren in een opdrachtvenster om de voorbeeld-app te starten. Met deze opdracht worden ook projectafhankelijkheden geïnstalleerd en wordt het project gebouwd, maar wordt de browser niet automatisch geopend.

dotnet run

Nadat de toepassing wordt uitgevoerd, gaat u naar om https://localhost:5001/swagger/index.html de Swagger-documentatie voor de web-API te bekijken en voorbeeldaanvragen in te dienen.

Selecteer de API die u wilt testen en selecteer Uitproberen.

Schermopname van de pagina API Swagger UI PROBEREN API-eindpunten.

Voer de benodigde parameters in en selecteer 'Uitvoeren'.

Resources opschonen

Wanneer u uw app en Azure Cosmos DB-account niet meer nodig hebt, kunt u de Azure-resources die u hebt gemaakt, verwijderen zodat er geen kosten meer voor in rekening worden gebracht. Om de resources te verwijderen:

  1. Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.

  2. Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.

    Resourcegroep selecteren die moet worden verwijderd

  3. Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.

    De resourcegroep verwijderen

  4. Selecteer in het volgende venster de naam van de resourcegroep die u wilt verwijderen en selecteer vervolgens Verwijderen.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een API voor Een MongoDB-account maakt, een database en een verzameling met code maakt en een web-API-app kunt uitvoeren. U kunt nu aanvullende gegevens importeren in uw database.

Probeert u capaciteitsplanning uit te Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

  • Als u alleen het aantal vcores en servers in uw bestaande databasecluster weet, leest u over het schatten van aanvraageenheden met behulp van vCores of vCCPUs
  • Als u de gebruikelijke aanvraagsnelheden voor uw huidige databaseworkload kent, leest u over het schatten van aanvraageenheden met behulp Azure Cosmos DB capacity planner