Snelstart: een Voorjaarsgegevens Azure Cosmos DB v3-app maken om Azure Cosmos DB-SQL API-gegevens te beheren

VAN TOEPASSING OP: SQL API

In deze quickstart maakt en beheert u een Azure Cosmos DB SQL API-account vanuit de Azure-portal en gebruikt u een Azure Cosmos DB v3-app lentegegevens die is gekloond vanuit GitHub. Eerst maakt u een Azure Cosmos DB SQL API-account met de Azure-portal en maakt u vervolgens een Spring Boot-app met de Spring Data Azure Cosmos DB v3-connector en voegt u vervolgens resources toe aan uw Cosmos DB-account met de spring boot-toepassing. Azure Cosmos DB is een databaseservice met meerdere modellen waarmee u snel document-, tabel-, sleutel-waarde- en grafiekdatabases kunt maken en query's kunt maken met globale distributie- en horizontale schaalmogelijkheden.

Belangrijk

Deze releasenotities zijn voor versie 3 van Spring Data Azure Cosmos DB. Hier vindt u releasenotities voor versie 2.

Spring Data Azure Cosmos DB ondersteunt alleen de SQL API.

Zie deze artikelen voor informatie over lentegegevens over andere AZURE Cosmos DB API's:

Vereisten

Inleidende notities

De structuur van een Cosmos DB-account. Ongeacht api of programmeertaal bevat een Db-account van De Kosmos nul of meer databases,een database (DB) bevat nul of meer containersen een container bevat nul of meer items, zoals wordt weergegeven in het onderstaande diagram:

Azure Cosmos-accountentiteiten

Hier vindt u meer informatie over databases, containers en items. Een paar belangrijke eigenschappen worden gedefinieerd op het niveau van de container, waaronder de inrichtende doorvoer- en partitiesleutel.

De inrichtende doorvoer wordt gemeten in aanvraageenheden(RUs)die een geldprijs hebben en een aanzienlijke bepalende factor zijn voor de bedrijfskosten van de rekening. De inrichtende doorvoer kan worden geselecteerd op basis van granulariteit per container of per database granulariteit, maar de doorvoerspecificatie op containerniveau heeft meestal de voorkeur. Hier vindt u meer informatie over het inrichten van doorvoer.

Wanneer items worden ingevoegd in een Db-container van De Kosmos, wordt de database horizontaal groter door meer opslagruimte en berekeningen toe te voegen om aanvragen te verwerken. Storage en rekencapaciteit worden toegevoegd in afzonderlijke eenheden, ook wel partities genoemd,en u moet één veld in uw documenten kiezen om de partitiesleutel te zijn waarmee elk document aan een partitie wordt toegevoegd. De manier waarop partities worden beheerd, is dat aan elke partitie een ongeveer gelijk segment wordt toegewezen buiten het bereik van partitiesleutelwaarden. daarom wordt u aangeraden een partitiesleutel te kiezen die relatief willekeurig of gelijkmatig is verdeeld. Anders zien sommige partities aanzienlijk meer aanvragen(hot partition)terwijl andere partities aanzienlijk minder aanvragen(koudepartitie) zien en dit moet worden vermeden. Hier vindt u meer informatie over partitionering.

Een databaseaccount maken

Voordat u een documentdatabase kunt maken, moet u een SQL API-account maken met Azure Cosmos DB.

  1. Selecteer in het menu Azure Portal of de startpaginade optie Een resource maken.

  2. Zoek op de pagina Nieuw naar Azure Cosmos DBen selecteer deze.

  3. Selecteer op de pagina Azure Cosmos DB de optie Maken.

  4. Voer op de pagina Azure Cosmos DB-account maken de basisinstellingen in voor het nieuwe Azure Cosmos-account.

    Instelling Waarde Beschrijving
    Abonnement Abonnementsnaam Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos-account.
    Resourcegroep Naam van resourcegroep Selecteer een resourcegroep of selecteer Nieuw makenen voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Accountnaam Een unieke naam Voer een naam in om uw Azure Cosmos-account te identificeren. Omdat documents.azure.com wordt toegevoegd aan de naam die u op geeft om uw URI te maken, gebruikt u een unieke naam.

    De naam kan alleen kleine letters, cijfers en het afbreekstreester (-) bevatten. De lengte moet tussen de 3 en 44 tekens zijn.
    API Het type account dat u wilt maken Selecteer Kern (SQL) om een documentdatabase en query te maken met behulp van SQL syntaxis.

    De API bepaalt het type account dat u wilt maken. Azure Cosmos DB biedt vijf API's: Core (SQL) en MongoDB voor documentgegevens, Gremlin voor grafiekgegevens, Azure Table en Cassandra. Op dit moment moet u voor elke API een afzonderlijk account maken.

    Meer informatie over de SQL API.
    Locatie De regio die het dichtst bij uw gebruikers staat Selecteer een geografische locatie om uw Azure Cosmos DB-account te hosten. Gebruik de locatie die het dichtst bij uw gebruikers staat om ze de snelste toegang tot de gegevens te geven.
    Capaciteitsmodus Inrichtende doorvoer of Serverless Selecteer Inrichtende doorvoer om een account te maken in de inrichtende doorvoermodus. Selecteer Serverloos om een account te maken in de serverloze modus.
    Azure Cosmos DB free tier discount toepassen Toepassen of Niet toepassen Met de gratis Azure Cosmos DB-laag krijgt u de eerste 1000 RU/s en 25 GB opslagruimte gratis in een account. Meer informatie over de gratis laag.

    Opmerking

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

    De nieuwe accountpagina voor Azure Cosmos DB

  5. Configureer de volgende details op het tabblad Globale distributie. U kunt de standaardwaarden laten voor het doel van deze snelstart:

    Instelling Waarde Beschrijving
    Geo-Redundancy Uitschakelen Schakel de globale distributie van uw account in of uit door uw regio te koppelen aan een paarregio. U kunt later meer regio's aan uw account toevoegen.
    Schrijft in meerdere regio's Uitschakelen Met de functie voor schrijven in meerdere regio's kunt u profiteren van de inrichtende doorvoer voor uw databases en containers over de hele wereld.

    Opmerking

    De volgende opties zijn niet beschikbaar als u Serverless selecteert als de capaciteitsmodus:

    • Gratis laagkorting toepassen
    • Geo-redundantie
    • Schrijft in meerdere regio's
  6. Desgewenst kunt u aanvullende details configureren op de volgende tabbladen:

  7. Selecteer Controleren + maken.

  8. Controleer de accountinstellingen en selecteer vervolgens Maken. Het maken van het account duurt enkele minuten. Wacht totdat de portalpagina wordt weergegeven Uw implementatie is voltooid.

    Het deelvenster Meldingen van Azure Portal

  9. Selecteer Ga naar resource om naar de accountpagina van Azure Cosmos DB te gaan.

    De pagina Azure Cosmos DB-account

Een container toevoegen

U kunt nu het hulpprogramma Gegevensverkenner in de Azure-portal gebruiken om een database en container te maken.

  1. Selecteer Nieuwe container voor Gegevensverkenner.

    Het gebied Container toevoegen wordt rechts weergegeven, mogelijk moet u naar rechts schuiven om het te zien.

    Het deelvenster Container toevoegen in de Azure Portal Data Explorer

  2. Voer op de pagina Container toevoegen de instellingen in voor de nieuwe container.

    Instelling Voorgestelde waarde Beschrijving
    Database-id ToDoList Voer Taken in als de naam voor de nieuwe database. Databasenamen moeten 1 tot 255 tekens bevatten en mogen geen /, \\, #, ? achterruimte bevatten. Controleer de optie Doorvoer tussen containers delen, zodat u de doorvoer in de database kunt delen in alle containers in de database. Deze optie helpt ook bij het besparen van kosten.
    Databasedoorvoer U kunt autoschaal of handmatige doorvoer inrichten. Met handmatige doorvoer kunt u ru/s zelf schalen, terwijl met de autoscale-doorvoer het systeem ru/s kan schalen op basis van gebruik. Selecteer Handmatig voor dit voorbeeld.

    Laat de doorvoer bij 400 aanvraageenheden per seconde (RU/s) achter. Als u de latentie wilt verminderen, kunt u de doorvoer later opschalen door de vereiste RU/s te schatten met de capaciteitscalculator.

    Opmerking:Deze instelling is niet beschikbaar bij het maken van een nieuwe container in een serverloos account.
    Container-id Items Voer Items in als de naam voor uw nieuwe container. Container-ID's hebben dezelfde tekenvereisten als databasenamen.
    Partitietoets /categorie In het voorbeeld dat in dit artikel wordt beschreven, wordt /categorie als partitiesleutel gebruikt.

    Voeg voor dit voorbeeld geen unieke sleutels toe of schakel Analytisch winkel in. Met unieke sleutels kunt u een laag gegevensintegriteit toevoegen aan de database door ervoor te zorgen dat een of meer waarden per partitiesleutel uniek zijn. Zie Unieke sleutels in Azure Cosmos DB voor meer informatie. Analytical Store wordt gebruikt om grootschalige analyses in te stellen tegen operationele gegevens zonder dat dit gevolgen heeft voor uw transactionele werkbelastingen.

    Selecteer OK. In de Gegevensverkenner worden de nieuwe database en container weergegeven.

Voorbeeldgegevens toevoegen

U kunt nu gegevens toevoegen aan uw nieuwe container met Data Explorer.

  1. Vouw in de Gegevensverkennerde database Taken uit en vouw de container Items uit. Selecteer Itemsen selecteer vervolgens Nieuw item.

    Nieuwe documenten maken in Data Explorer in de Azure-portal

  2. Voeg nu een document toe aan de container met de volgende structuur.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Nadat u het json hebt toegevoegd aan het tabblad Documenten, selecteert u Opslaan.

    Kopieer in json-gegevens en selecteer Opslaan in Gegevensverkenner in de Azure-portal

  4. Maak en sla nog een document op waar u een unieke waarde voor de eigenschap invoegt en wijzig de andere eigenschappen naar eigen id goedheid. Uw nieuwe documenten kunnen elke structuur hebben die u wilt, omdat Azure Cosmos DB geen schema voor uw gegevens oplegt.

Query's uitvoeren op uw gegevens

U kunt query's in Gegevensverkenner gebruiken om uw gegevens op te halen en te filteren.

  1. Controleer de standaardquery boven aan het tabblad Items in Gegevensverkenner. Met deze query worden alle documenten opgehaald en weergegeven uit de container die op id is besteld.

    Standaardquery in Gegevensverkenner is SELECT * VAN c

  2. Als u de query wilt wijzigen, selecteert u Filter bewerken,vervangt u de standaardquery door en selecteert u Filter toepassen.

    De standaardquery wijzigen door ORDER BY toe te voegen c._ts DESC en op Filter toepassen te klikken

    Met de gewijzigde query worden de documenten in aflopende volgorde weergegeven op basis van hun tijdstempel, zodat uw tweede document nu eerst wordt weergegeven.

    Query gewijzigd in ORDER BY c._ts DESC en klik op Filter toepassen

Als u bekend bent met SQL syntaxis, kunt u ondersteunde SQL query's in het vak querypredicaat invoeren. U kunt Gegevensverkenner ook gebruiken om opgeslagen procedures, UDF's en triggers te maken voor bedrijfslogica aan de serverzijde.

Data Explorer biedt eenvoudige toegang tot de Azure-portal tot alle ingebouwde programmatische functies voor gegevenstoegang die beschikbaar zijn in de API's. U gebruikt de portal ook om de doorvoer te schalen, sleutels en verbindingsreeksen op te halen en meetgegevens en SLA's voor uw Azure Cosmos DB-account te bekijken.

De voorbeeldtoepassing kloonen

Laten we nu overstappen op het werken met code. Laten we een api-app SQL vanuit GitHub, de verbindingsreeks instellen en uitvoeren. U ziet hoe eenvoudig het is om programmatisch met gegevens te werken.

Voer de volgende opdracht uit om de voorbeeldopslagplaats te kloonen. Met deze opdracht maakt u een kopie van de voorbeeld-app op uw computer.

git clone https://github.com/Azure-Samples/azure-spring-data-cosmos-java-sql-api-getting-started.git

De code controleren

Deze stap is optioneel. Als u wilt weten hoe de databasebronnen in de code worden gemaakt, kunt u de volgende fragmenten bekijken. Anders kunt u doorgaan naar De app uitvoeren.

Toepassingsconfiguratiebestand

Hier laten we zien hoe Spring Boot en Spring Data de gebruikerservaring verbeteren: het proces van het tot stand brengen van een Cosmos-client en het maken van verbinding met De bronnen van Cosmos is nu config in plaats van code. Bij het opstarten van toepassingen verwerkt Spring Boot dit alles met behulp van de instellingen in application.properties:

cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

Nadat u een Azure Cosmos DB-account, -database en -container hebt gemaakt, worden alleen invul-in-the-blanks in het config-bestand en Spring Boot/Spring Data automatisch als volgt uitgevoerd: (1) maakt u een onderliggend Java SDK-exemplaar met de URI en de sleutel en (2) verbinding met de database en CosmosClient container. U bent helemaal klaar: geen resourcebeheercode meer!

Java-bron

De spring data value-add is ook afkomstig van de eenvoudige, schone, gestandaardiseerde en platformafhankelijke interface voor het werken in gegevensstores. Voortbouwend op de bovenstaande GitHub brongegevens, hieronder vindt u CRUD- en queryvoorbeelden voor het manipuleren van Azure Cosmos DB-documenten met Spring Data Azure Cosmos DB.

  • Het maken van items en updates met behulp van de save methode.

    
    logger.info("Saving user : {}", testUser1);
    userRepository.save(testUser1);
    
    
  • Point-reads met behulp van de afgeleide querymethode die is gedefinieerd in de opslagplaats. De findByIdAndLastName punten worden gelezen voor UserRepository . De velden die in de naam van de methode worden vermeld, zorgen ervoor dat voorjaarsgegevens een door de en velden gedefinieerde punt-lezen idlastName uitvoeren:

    
    // to find by Id, please specify partition key value if collection is partitioned
    final User result = userRepository.findByIdAndLastName(testUser1.getId(), testUser1.getLastName());
    logger.info("Found user : {}", result);
    
    
  • Item wordt verwijderd met deleteAll behulp van:

    
    userRepository.deleteAll();
    
    
  • Afgeleide query op basis van de naam van de bewaarmethode. Spring Data implementeert de methode als UserRepository een Java SDK-SQL query in het veld (deze query kan niet worden geïmplementeerd als findByFirstNamefirstName een point-read):

    
    Flux<User> users = reactiveUserRepository.findByFirstName("testFirstName");
    users.map(u -> {
        logger.info("user is : {}", u);
        return u;
    }).subscribe();
    
    

De app uitvoeren

Ga nu terug naar de Azure-portal om de verbindingsreeksgegevens op te halen en de app te starten met uw eindpuntgegevens. Hierdoor kan uw app communiceren met uw gehoste database.

  1. In het git terminal-venster cd naar de voorbeeldcodemap.

    cd azure-spring-data-cosmos-java-sql-api-getting-started/azure-spring-data-cosmos-java-getting-started/
    
  2. Gebruik in het git terminal-venster de volgende opdracht om de vereiste Spring Data Azure Cosmos DB-pakketten te installeren.

    mvn clean package
    
  3. Gebruik in het git terminal-venster de volgende opdracht om de Voorjaarsgegevens Azure Cosmos DB-toepassing te starten:

    mvn spring-boot:run
    
  4. De app laadt application.properties en verbindt de resources in uw Azure Cosmos DB-account.

  5. De app voert kruis kruispuntbewerkingen uit die hierboven worden beschreven.

  6. De app voert een afgeleide query uit.

  7. De app verwijdert uw resources niet. Ga terug naar de portal om de resources uit uw account op te schonen als u kosten wilt voorkomen.

SLA's controleren in de Azure-portal

De Azure-portal controleert de doorvoer, opslag, beschikbaarheid, latentie en consistentie van uw Cosmos DB-account. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) geven de SLA-waarde weer ten opzichte van de werkelijke prestaties. Deze suite met metrische gegevens maakt het bewaken van uw SLA's transparant.

Metrische gegevens en SLA's bekijken:

  1. Selecteer Metrische gegevens in het navigatiemenu van uw Cosmos DB-account.

  2. Selecteer een tabblad, zoals Latentie,en selecteer een tijdsbestek aan de rechterkant. Vergelijk de regels Werkelijke en SLA in de grafieken.

    Azure Cosmos DB metrics suite

  3. Bekijk de metrische gegevens op de andere tabbladen.

Resources ops schonen

Wanneer u klaar bent met uw app en Azure Cosmos DB-account, kunt u de Azure-resources verwijderen die u hebt gemaakt, zodat u niet meer kosten hoeft te maken. De resources verwijderen:

  1. Zoek in de zoekbalk van de Azure Portal naar Resourcegroepen en selecteer deze.

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

    Selecteer de resourcegroep die u wilt verwijderen

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

    De resourcegroep verwijderen

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

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB SQL API-account kunt maken, een documentdatabase en container kunt maken met de Gegevensverkenner en een Lentegegevens-app kunt uitvoeren om hetzelfde programmatisch uit te voeren. U kunt nu extra gegevens importeren in uw Azure Cosmos DB-account.

Wilt u capaciteitsplanning uitvoeren voor een migratie naar 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 vCores of vCPUs
  • Als u de gebruikelijke aanvraagtarieven voor uw huidige databasewerkbelasting kent, leest u meer over het schatten van aanvraageenheden met behulp van De capaciteitsplanner van Azure Cosmos DB