Uzyskiwanie dostępu do danych za pomocą interfejsu API NoSQL usługi Azure Cosmos DB

Artykuł
10/23/2023

W tym artykule przedstawiono sposób dodawania szablonu startowego Spring Cloud Azure Starter for Spring Data for Azure Cosmos DB do aplikacji niestandardowej. Ten szablon startowy umożliwia przechowywanie danych w bazie danych Usługi Azure Cosmos DB i pobieranie ich z bazy danych usługi Azure Cosmos DB przy użyciu rozwiązań Spring Data i Azure Cosmos DB for NoSQL. W artykule pokazano, jak utworzyć usługę Azure Cosmos DB za pośrednictwem witryny Azure Portal. Następnie w artykule pokazano, jak za pomocą narzędzia Spring Initializr utworzyć niestandardową aplikację Spring Boot, której można użyć z szablonem startowym Spring Boot.

Azure Cosmos DB to globalnie rozproszona usługa bazy danych, która umożliwia deweloperom pracę z danymi przy użyciu różnych standardowych interfejsów API, takich jak SQL, MongoDB, Graph i Interfejsy API tabel. Szablon startowy Spring Boot firmy Microsoft umożliwia deweloperom korzystanie z aplikacji Spring Boot, które łatwo integrują się z usługą Azure Cosmos DB for NoSQL.

Wymagania wstępne

Subskrypcja platformy Azure — utwórz bezpłatnie.
Zestaw Java Development Kit (JDK) w wersji 8 lub nowszej.
Apache Maven.
Interfejs wiersza polecenia platformy Azure.

Tworzenie bazy danych usługi Azure Cosmos DB przy użyciu witryny Azure Portal

Aby utworzyć wystąpienie usługi Azure Cosmos DB, wykonaj następujące czynności:

Przejdź do witryny Azure Portal i wybierz pozycję Utwórz zasób.
Wybierz pozycję Bazy danych, a następnie wybierz pozycję Azure Cosmos DB.
Na ekranie Tworzenie konta usługi Azure Cosmos DB wybierz pozycję Azure Cosmos DB for NoSQL.
Na stronie Azure Cosmos DB wprowadź następujące informacje:
- W polu Subskrypcja wybierz subskrypcję, której chcesz użyć dla bazy danych.
- W polu Grupa zasobów określ, czy dla bazy danych chcesz utworzyć nową grupę zasobów, czy wybrać istniejącą grupę zasobów.
- Wprowadź unikatową nazwę konta, która jest używana jako identyfikator URI bazy danych. Na przykład: contosoaccounttest.
- W polu Lokalizacja określ lokalizację bazy danych.
- Wybierz pozycję Zastosuj rabat w warstwie Bezpłatna, jeśli chcesz utworzyć konto tylko do celów demonstracyjnych.
- Pozostaw pozostałe opcje domyślne i ustawienia, tak jak to jest.
Wybierz pozycję Przejrzyj i utwórz, przejrzyj specyfikacje i wybierz pozycję Utwórz.
Po utworzeniu bazy danych jest ona wyświetlana na pulpicie nawigacyjnym platformy Azure i na stronach Wszystkie zasoby i usługa Azure Cosmos DB. Aby utworzyć bazę danych i kontener dla nowo utworzonej usługi Azure Cosmos DB, zobacz sekcję Dodawanie bazy danych i kontenera w przewodniku Szybki start: tworzenie konta, bazy danych, kontenera i elementów usługi Azure Cosmos DB w witrynie Azure Portal. Możesz wybrać bazę danych dla dowolnej z tych lokalizacji, aby otworzyć stronę właściwości pamięci podręcznej.
Po wyświetleniu strony właściwości bazy danych wybierz pozycję Klucze i skopiuj identyfikator URI i klucze dostępu dla bazy danych. Te wartości są używane w aplikacji Spring Boot.

Ważne

W nowo utworzonej usłudze Azure Cosmos DB przypisz Owner rolę do aktualnie używanego konta platformy Azure. Aby uzyskać więcej informacji, zobacz przypisywanie ról Azure za pomocą portalu Azure.

Tworzenie aplikacji Spring Boot za pomocą narzędzia Spring Initializr

Wykonaj następujące czynności, aby utworzyć nowy projekt aplikacji Spring Boot, korzystając z obsługi platformy Azure. Alternatywnie możesz użyć przykładu spring-cloud-azure-data-cosmos-sample w repozytorium azure-spring-boot-samples . Następnie możesz przejść bezpośrednio do sekcji Kompilowanie i testowanie aplikacji.

Przejdź do https://start.spring.io/.
Podaj następujące opcje:
- Wygeneruj projekt Maven z użyciem języka Java.
- Określ wersję platformy Spring Boot na 2.7.11.
- Określ nazwy Grupa i Artefakt dla swojej aplikacji.
- Wybierz 17 dla wersji języka Java.
- Dodaj pomoc techniczną platformy Azure w zależnościach.
Uwaga

Narzędzie Spring Initializr używa nazw Group (Grupa) i Artifact (Artefakt) do utworzenia nazwy pakietu, na przykład com.example.wingtiptoysdata.

Wersja platformy Spring Boot może być wyższa niż wersja obsługiwana przez pomoc techniczną platformy Azure. Po automatycznym wygenerowaniu projektu można ręcznie zmienić wersję platformy Spring Boot na najwyższą obsługiwaną przez platformę Azure, którą można znaleźć w temacie Spring-Versions-Mapping.
Po określeniu opcji wymienionych wcześniej wybierz pozycję GENERUJ.
Po wyświetleniu monitu pobierz projekt do ścieżki na komputerze lokalnym i wyodrębnij pliki.

Prosta aplikacja Spring Boot jest teraz gotowa do edycji.

Konfigurowanie aplikacji Spring Boot do korzystania z szablonu startowego Azure Spring Boot

W katalogu aplikacji znajdź plik pom.xml, na przykład:

C:\SpringBoot\wingtiptoysdata\pom.xml

— lub —

/users/example/home/wingtiptoysdata/pom.xml
Otwórz plik pom.xml w edytorze tekstów i dodaj do elementu <dependencies> następujące pozycje:
```
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>
```
Uwaga

Aby uzyskać więcej informacji na temat zarządzania wersjami bibliotek platformy Azure spring Cloud przy użyciu rachunku materiałów (BOM), zobacz sekcję Wprowadzenie w przewodniku deweloperów platformy Azure Spring Cloud.
Zapisz i zamknij plik pom.xml.

Konfigurowanie aplikacji Spring Boot do korzystania z usługi Azure Cosmos DB

Znajdź plik application.properties w katalogu resources aplikacji, na przykład:

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

— lub —

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

Otwórz plik application.properties w edytorze tekstów, a następnie dodaj w pliku następujące wiersze i zastąp przykładowe wartości odpowiednimi właściwościami dla bazy danych:

# 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

Zapisz i zamknij plik application.properties.

Dodawanie przykładowego kodu w celu zaimplementowania podstawowej funkcjonalności bazy danych

W tej sekcji utworzysz dwie klasy języka Java do przechowywania danych użytkownika. Następnie zmodyfikujesz główną klasę aplikacji, aby utworzyć wystąpienie User klasy i zapisać ją w bazie danych.

Definiowanie klasy bazowej do przechowywania danych użytkownika

Utwórz nowy plik o nazwie User.java w tym samym katalogu, w którym znajduje się główny plik Java aplikacji.

Otwórz plik User.java w edytorze tekstów i dodaj w nim następujące wiersze, aby zdefiniować ogólną klasę użytkownika, która będzie przechowywać wartości w bazie danych oraz je z niej pobierać:

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

Zapisz i zamknij plik User.java.

Definiowanie interfejsu repozytorium danych

Utwórz nowy plik o nazwie UserRepository.java w tym samym katalogu, w którym znajduje się główny plik Java aplikacji.
Otwórz plik UserRepository.java w edytorze tekstów i dodaj w pliku następujące wiersze, aby zdefiniować interfejs repozytorium użytkownika, który będzie poszerzać domyślny interfejs ReactiveCosmosRepository:
```
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);
}
```
Interfejs ReactiveCosmosRepository zastępuje interfejs DocumentDbRepository z poprzedniej wersji szablonu startowego. Nowy interfejs zapewnia synchroniczne i reaktywne interfejsy API dla podstawowych operacji zapisywania, usuwania i znajdowania.
Zapisz i zamknij plik UserRepository.java.

Modyfikowanie głównej klasy aplikacji

Znajdź główny plik Java aplikacji w katalogu pakietu aplikacji, na przykład:

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

— lub —

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

Otwórz główny plik Java aplikacji w edytorze tekstów, a następnie dodaj w nim następujące wiersze:

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

Zapisz i zamknij główny plik Java aplikacji.

Tworzenie i testowanie aplikacji

Otwórz wiersz polecenia i przejdź do folderu, w którym znajduje się plik pom.xml, na przykład:

cd C:\SpringBoot\wingtiptoysdata

— lub —

cd /users/example/home/wingtiptoysdata
Użyj następującego polecenia, aby skompilować i uruchomić aplikację:
```
./mvnw clean
```
To polecenie uruchamia aplikację automatycznie w ramach fazy testowej. Możesz również użyć polecenia:
```
./mvnw spring-boot:run
```
Po wykonaniu niektórych danych wyjściowych kompilacji i testowania w oknie konsoli zostanie wyświetlony komunikat podobny do następującego przykładu:
```
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
```
Te komunikaty wyjściowe wskazują, że dane zostały pomyślnie zapisane w usłudze Azure Cosmos DB, a następnie pobrane ponownie.

Czyszczenie zasobów

Jeśli nie zamierzasz nadal używać tej aplikacji, pamiętaj, aby usunąć grupę zasobów zawierającą utworzoną wcześniej usługę Azure Cosmos DB. Grupę zasobów można usunąć z witryny Azure Portal.

Następne kroki

Aby dowiedzieć się więcej na temat oprogramowania Spring i platformy Azure, przejdź do centrum dokumentacji dotyczącej oprogramowania Spring na platformie Azure.

Oprogramowanie Spring na platformie Azure

Więcej zasobów

Aby uzyskać więcej informacji o korzystaniu z usługi Azure Cosmos DB i języka Java, zobacz następujące artykuły:

Aby uzyskać więcej informacji o korzystaniu z aplikacji Spring Boot na platformie Azure, zobacz następujące artykuły:

[Spring Cloud Azure Starter for Spring Data Azure Cosmos DB]
Wdrażanie aplikacji Spring Boot w systemie Linux w usłudze aplikacja systemu Azure Service
Running a Spring Boot Application on a Kubernetes Cluster in the Azure Container Service (Uruchamianie aplikacji Spring Boot w klastrze Kubernetes w usłudze Azure Container Service)

Aby uzyskać więcej informacji na temat korzystania z platformy Azure przy użyciu języka Java, zapoznaj się z tematami Platforma Azure dla deweloperów języka Java oraz Praca z narzędziami Azure DevOps i językiem Java.

Platforma Spring jest rozwiązaniem open-source, które pomaga deweloperom języka Java tworzyć aplikacje na poziomie przedsiębiorstwa. Jednym z bardziej popularnych projektów opartych na tej platformie jest Spring Boot, który oferuje uproszczoną metodę tworzenia autonomicznych aplikacji Java. Aby ułatwić deweloperom rozpoczęcie pracy z aplikacją Spring Boot, pod adresem https://github.com/spring-guides/ udostępniono przykładowe pakiety aplikacji Spring Boot. Oprócz możliwości wyboru z listy podstawowych projektów Spring Boot narzędzie Spring Initializr pomaga deweloperom rozpocząć tworzenie niestandardowych aplikacji Spring Boot.