Toegang tot gegevens met De NoSQL-API van Azure Cosmos DB

Artikel
10/23/2023

In dit artikel leest u hoe u de Spring Cloud Azure Starter voor Spring Data voor Azure Cosmos DB toevoegt aan een aangepaste toepassing. Met deze starter kunt u gegevens opslaan in en ophalen uit uw Azure Cosmos DB-database met behulp van Spring Data en Azure Cosmos DB for NoSQL. In het artikel wordt uitgelegd hoe u een Azure Cosmos DB maakt via Azure Portal. Vervolgens ziet u in het artikel hoe u Spring Initializr gebruikt om een aangepaste Spring Boot-toepassing te maken die u kunt gebruiken met de Spring Boot Starter.

Azure Cosmos DB is een wereldwijd gedistribueerde databaseservice waarmee ontwikkelaars met gegevens kunnen werken met behulp van verschillende standaard-API's, zoals SQL, MongoDB, Graph en Table-API's. Met Spring Boot Starter van Microsoft kunnen ontwikkelaars Spring Boot-toepassingen gebruiken die eenvoudig kunnen worden geïntegreerd met Azure Cosmos DB voor NoSQL.

Vereisten

Een Azure-abonnement (u kunt een gratis abonnement maken).
Java Development Kit (JDK), versie 8 of hoger.
Apache Maven.
Azure CLI.

Een Azure Cosmos DB-exemplaar maken via Azure Portal

Gebruik de volgende stappen om een Azure Cosmos DB-exemplaar te maken:

Blader naar Azure Portal en selecteer Een resource maken.
Selecteer Databases en selecteer vervolgens Azure Cosmos DB.
Selecteer Azure Cosmos DB for NoSQL in het scherm Een Azure Cosmos DB-account maken.
Voer op de pagina Azure Cosmos DB de volgende informatie in:
- Kies het abonnement dat u wilt gebruiken voor uw database.
- Geef aan of u een nieuwe resourcegroep voor uw database wilt maken of een bestaande resourcegroep wilt gebruiken.
- Voer een unieke accountnaam in die u als de URI voor uw database gebruikt. Bijvoorbeeld: contosoaccounttest.
- Geef de locatie voor uw database op.
- Selecteer Korting op gratis laag toepassen als u alleen een account wilt maken voor demonstratiedoeleinden.
- Laat de rest van de standaardopties en -instellingen staan.
Selecteer Beoordelen en maken, controleer uw specificaties en selecteer Maken.
Wanneer uw database is gemaakt, wordt deze weergegeven op uw Azure-dashboard en onder de pagina's Alle resources en Azure Cosmos DB. Als u een database en een container voor een zojuist gemaakte Azure Cosmos DB wilt maken, raadpleegt u de sectie Een database en een container toevoegen van quickstart: Een Azure Cosmos DB-account, -database, -container en -items maken vanuit Azure Portal. U kunt uw database selecteren voor een van deze locaties om de eigenschappenpagina voor uw cache te openen.
Wanneer de eigenschappenpagina voor uw database wordt weergegeven, selecteert u Sleutels en kopieert u uw URI en toegangssleutels voor uw database. U gebruikt deze waarden in uw Spring Boot-toepassing.

Belangrijk

Wijs in uw zojuist gemaakte Azure Cosmos DB de Owner rol toe aan het Azure-account dat u momenteel gebruikt. Zie voor meer informatie Azure-rollen toewijzen met behulp van de Azure-portal.

Een Spring Boot-toepassing maken met de Spring Initializr

Voer de volgende stappen uit om een nieuw Spring boot-toepassingsproject te maken met ondersteuning van Azure. Als alternatief kunt u het voorbeeld spring-cloud-azure-data-cosmos-sample gebruiken in de opslagplaats azure-spring-boot-samples . Vervolgens kunt u direct doorgaan naar Uw app bouwen en testen.

Blader naar https://start.spring.io/.
Geef de volgende opties op:
- Genereer een Maven-project met Java.
- Geef uw Spring Boot-versie op naar 2.7.11.
- Geef de namen voor Groep en Artefact voor uw toepassing op.
- Selecteer 17 voor de Java-versie.
- Voeg Azure-ondersteuning toe aan de afhankelijkheden.
Notitie

De Spring Initializr gebruikt de namen van groepen en artefacten om de pakketnaam te maken, bijvoorbeeld com.example.wingtiptoysdata.

De versie van Spring Boot is mogelijk hoger dan de versie die wordt ondersteund door Azure-ondersteuning. Nadat het project automatisch is gegenereerd, kunt u de Spring Boot-versie handmatig wijzigen in de hoogste versie die wordt ondersteund door Azure, die u kunt vinden in Spring-Versions-toewijzing.
Wanneer u de eerder vermelde opties hebt opgegeven, selecteert u GENEREREN.
Wanneer u hierom wordt gevraagd, downloadt u het project naar een pad op uw lokale computer en extraheert u de bestanden.

Uw eenvoudige Spring Boot-toepassing is nu gereed om te worden bewerkt.

Uw Spring Boot-toepassing configureren voor het gebruik van de Azure Spring Boot Starter

Zoek het bestand pom.xml in de map van uw app, bijvoorbeeld:

C:\SpringBoot\wingtiptoysdata\pom.xml

– of –

/users/example/home/wingtiptoysdata/pom.xml
Open het bestand pom.xml in een teksteditor en voeg het volgende toe aan het <dependencies>-element:
```
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>
```
Notitie

Zie de sectie Aan de slag van de Ontwikkelaarshandleiding van Spring Cloud Azure voor meer informatie over het beheren van Versies van Spring Cloud Azure-bibliotheken met een stuk materiaal (BOM).
Sla het bestand pom.xml op en sluit het.

Uw Spring Boot-app configureren voor het gebruik van uw Azure Cosmos DB-exemplaar

Zoek het bestand application.properties in de map Resources van uw app, zoals bijvoorbeeld:

C:\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

– of –

/users/example/home/wingtiptoysdata/src/main/resources/application.properties

Open het bestand application.properties in een teksteditor en voeg de volgende regels aan het bestand toe. Vervang de voorbeeldwaarden door de eerder opgegeven, juiste waarden:

# Specify the DNS URI of your Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint=https://contosoaccounttest.documents.azure.com:443/

# Specify the name of your database.
spring.cloud.azure.cosmos.database=contosoaccounttest
spring.cloud.azure.cosmos.populate-query-metrics=true

Sla het bestand application.properties op en sluit het.

Voorbeeldcode toevoegen om de basisfunctionaliteit van de database te implementeren

In deze sectie maakt u twee Java-klassen voor het opslaan van gebruikersgegevens. Vervolgens wijzigt u uw hoofdtoepassingsklasse om een exemplaar van de User klasse te maken en op te slaan in uw database.

Een basisklasse definiëren voor het opslaan van gebruikersgegevens

Maak een nieuw bestand met de naam User.java in dezelfde map als het Java-bestand van uw hoofdtoepassing.

Open het bestand User.java in een teksteditor en voeg de volgende regels toe aan het bestand om een algemene gebruikersklasse te definiëren waarmee waarden in uw database worden opgeslagen en opgehaald:

package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import org.springframework.data.annotation.Id;

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {

    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

Sla het bestand User.java op en sluit het.

Een interface voor de gegevensopslagplaats definiëren

Maak een nieuw bestand met de naam UserRepository.java in dezelfde map als het Java-bestand van uw hoofdtoepassing.
Open het bestand UserRepository.java in een teksteditor en voeg de volgende regels toe aan het bestand om een interface voor de gebruikersopslagplaats te definiëren die een uitbreiding is op de standaard ReactiveCosmosRepository-interface:
```
package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.repository.ReactiveCosmosRepository;
import org.springframework.stereotype.Repository;
import reactor.core.publisher.Flux;

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}
```
De ReactiveCosmosRepository-interface vervangt de DocumentDbRepository-interface van de vorige versie van de starter. De nieuwe interface biedt synchrone en reactieve API's voor eenvoudige bewerkingen zoals opslaan, verwijderen en zoeken.
Sla het bestand UserRepository.java op en sluit het.

De hoofdklasse van de toepassing wijzigen

Zoek het Java-bestand van de hoofdtoepassing in de pakketmap van uw toepassing, zoals bijvoorbeeld:

C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

– of –

/users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

Open het Java-bestand van de hoofdtoepassing in een teksteditor en voeg de volgende regels toe aan het bestand:

package com.example.wingtiptoysdata;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.util.Assert;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Optional;

@SpringBootApplication
public class WingtiptoysdataApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(WingtiptoysdataApplication.class);

    @Autowired
    private UserRepository repository;

    public static void main(String[] args) {
        SpringApplication.run(WingtiptoysdataApplication.class, args);
    }

    public void run(String... var1) {
        this.repository.deleteAll().block();
        LOGGER.info("Deleted all data in container.");

        final User testUser = new User("testId", "testFirstName", "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()), "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()), "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()), "query result lastName doesn't match!");

        LOGGER.info("findOne in User collection get result: {}", result.toString());
    }
}

Sla het Java-bestand van de hoofdtoepassing op en sluit het af.

Uw app bouwen en testen

Open een opdrachtprompt en ga naar de map waarin uw bestand pom.xml zich bevindt, bijvoorbeeld:

cd C:\SpringBoot\wingtiptoysdata

– of –

cd /users/example/home/wingtiptoysdata
Gebruik de volgende opdracht om uw toepassing te bouwen en uit te voeren:
```
./mvnw clean
```
Met deze opdracht wordt de toepassing automatisch uitgevoerd als onderdeel van de testfase. U kunt ook gebruikmaken van:
```
./mvnw spring-boot:run
```
Na enige build- en testuitvoer wordt in het consolevenster een bericht weergegeven dat lijkt op het volgende voorbeeld:
```
INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : Deleted all data in container.

... (omitting connection and diagnostics output) ...

INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : findOne in User collection get result: testFirstName testLastName, test address line one
```
Deze uitvoerberichten geven aan dat de gegevens zijn opgeslagen in Azure Cosmos DB en vervolgens opnieuw zijn opgehaald.

Resources opschonen

Als u deze toepassing niet gaat blijven gebruiken, moet u de resourcegroep verwijderen die de Azure Cosmos DB bevat die u eerder hebt gemaakt. U kunt de resourcegroep verwijderen uit Azure Portal.

Volgende stappen

Voor meer informatie over Spring en Azure gaat u door naar het documentatiecentrum van Spring op Azure.

Spring in Azure

Meer resources

Zie de volgende artikelen voor meer informatie over het gebruik van Azure Cosmos DB en Java:

Zie de volgende artikelen voor meer informatie over het gebruik van Spring Boot-toepassingen in Azure:

[Spring Cloud Azure Starter voor Spring Data Azure Cosmos DB]
Een Spring Boot-toepassing implementeren in Linux op Azure-app Service
Een Spring Boot-toepassing uitvoeren op een Kubernetes-cluster in Azure Container Service

Voor meer informatie over het gebruik van Azure met Java raadpleegt u de artikelen Azure voor Java-ontwikkelaars en de Werken met Azure DevOps en Java.

Het Spring Framework is een opensource-oplossing waarmee Java-ontwikkelaars toepassingen op ondernemingsniveau kunnen maken. Een van de meest populaire projecten op basis van dat platform is Spring Boot. Dit biedt een vereenvoudigde benadering voor het maken van zelfstandige Java-toepassingen. Er zijn verschillende Spring Boot-voorbeeldpakketten beschikbaar op https://github.com/spring-guides/ om ontwikkelaars te helpen aan de slag te gaan met Spring Boot. Naast de keuze uit de lijst met Spring Boot-basisprojecten biedt de Spring Initializr ontwikkelaars hulp om aan de slag te gaan met het maken van aangepaste Spring Boot-toepassingen.