Доступ к данным с помощью API NoSQL Azure Cosmos DB

Статья
10/23/2023

В этой статье показано, как добавить Spring Cloud Starter для Spring Data для Azure Cosmos DB в пользовательское приложение. Этот начальный способ позволяет хранить данные и извлекать данные из базы данных Azure Cosmos DB с помощью Spring Data и Azure Cosmos DB для NoSQL. В этой статье показано, как создать Azure Cosmos DB с помощью портал Azure. Затем в статье показано, как использовать Spring Initializr для создания пользовательского приложения Spring Boot, которое можно использовать с spring Boot Starter.

Azure Cosmos DB — это глобально распределенная служба баз данных, позволяющая разработчикам работать с данными с помощью разных стандартных API, например SQL, MongoDB, Graph и API таблиц. Microsoft Spring Boot Starter позволяет разработчикам использовать приложения Spring Boot, которые легко интегрируются с Azure Cosmos DB для NoSQL.

Необходимые компоненты

Подписка Azure — создайте бесплатную учетную запись.
Пакет средств разработки Java (JDK) версии 8 или более поздней.
Apache Maven.
Azure CLI.

Создание Azure Cosmos DB с помощью портала Azure

Чтобы создать экземпляр Azure Cosmos DB, выполните следующие действия.

Перейдите к портал Azure и выберите "Создать ресурс".
Выберите Базы данных, а затем — Azure Cosmos DB.
На экране "Создание учетной записи Azure Cosmos DB" выберите Azure Cosmos DB для NoSQL.
На странице Azure Cosmos DB введите следующие сведения.
- Выберите подписку, которую нужно использовать для базы данных.
- Укажите, следует ли создать группу ресурсов для базы данных, или выберите имеющуюся группу ресурсов.
- Введите уникальное имя учетной записи, которое используется в качестве URI для базы данных. Например, contosoaccounttest.
- Укажите расположение для базы данных.
- Выберите "Применить скидку на бесплатный уровень" , если вы хотите создать учетную запись только для демонстрации.
- Оставьте остальные параметры и параметры по умолчанию как есть.
Выберите "Просмотр и создание", "Просмотрите спецификации" и нажмите кнопку "Создать".
После создания базы данных она отображается на панели мониторинга Azure и на страницах "Все ресурсы" и Azure Cosmos DB. Сведения о создании базы данных и контейнера для созданной базы данных Azure Cosmos DB см. в разделе "Добавление базы данных и контейнера" краткого руководства. Создание учетной записи Azure Cosmos DB, базы данных, контейнера и элементов из портал Azure. Вы можете выбрать базу данных в любом из этих расположений, чтобы открыть страницу свойств кэша.
При отображении страницы свойств базы данных выберите ключи и скопируйте URI и ключи доступа для базы данных. Эти значения используются в приложении Spring Boot.

Внимание

В созданном Azure Cosmos DB назначьте Owner роль учетной записи Azure, которую вы используете в настоящее время. Дополнительные сведения см. в разделе Назначение ролей Azure с помощью портала Azure.

Создание приложения Spring Boot с помощью Spring Initializr

Выполните описанные ниже действия, чтобы создать проект приложения Spring Boot с использованием поддержки Azure. В качестве альтернативы можно использовать пример spring-cloud-azure-data-cosmos-sample в репозитории azure-spring-boot-samples . В таком случае вы можете сразу перейти к разделу Создание и тестирование приложения.

Перейдите в https://start.spring.io/.
Укажите следующие параметры.
- Выберите в соответствующих полях Maven Project (Проект Maven) и Java.
- Укажите версию Spring Boot до версии 2.7.11.
- Заполните поля Group (Группа) и Artifact (Артефакт) для приложения.
- Выберите 17 для версии Java.
- Добавьте в зависимости Службу поддержки Azure.
Примечание.

Spring Initializr использует имена группы и артефакта, чтобы создать имя пакета, например com.example.wingtiptoysdata.

Версия Spring Boot может быть выше версии, поддерживаемой Службой поддержки Azure. После автоматического создания проекта можно вручную изменить версию Spring Boot на самую высокую поддерживаемую Azure версию, которую можно найти в Spring-Versions-Mapping.
Если вы указали указанные ранее параметры, выберите GENERATE.
При появлении запроса скачайте проект на локальный компьютер и извлеките файлы.

Теперь вы можете вносить изменения в свое простое приложение Spring Boot.

Настройка приложения Spring Boot для использования начального приложения Azure Spring Boot

Найдите файл pom.xml в каталоге приложения, например:

C:\SpringBoot\wingtiptoysdata\pom.xml

–или–

/users/example/home/wingtiptoysdata/pom.xml
Откройте файл pom.xml в текстовом редакторе и добавьте следующие строки в элемент <dependencies>:
```
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>
```
Примечание.

Дополнительные сведения об управлении версиями библиотеки Azure Spring Cloud с помощью счета за материалы (BOM) см. в разделе "Начало работы" руководства разработчика Azure Spring Cloud.
Сохраните и закройте файл pom.xml.

Настройка приложения Spring Boot для использования с Azure Cosmos DB

Найдите файл application.properties в каталоге resources, например:

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

–или–

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

Откройте файл application.properties в текстовом редакторе, добавьте указанные ниже строки в файл и замените примеры значений на соответствующие свойства для базы данных:

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

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

Сохраните и закройте файл application.properties.

Добавление примера кода для реализации базовых возможностей базы данных

В этом разделе описано, как создать два класса Java для хранения пользовательских данных. Затем вы измените основной класс приложения, чтобы создать экземпляр User класса и сохранить его в базе данных.

Определение базового класса для хранения пользовательских данных

Создайте файл с именем User.java в том же каталоге, что и файл основного приложения Java.

Откройте файл User.java в текстовом редакторе и добавьте в него следующие строки, чтобы определить универсальный класс пользователя, позволяющего сохранять и извлекать значения в базе данных:

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

Сохраните и закройте файл User.java.

Определение интерфейса хранилища данных

Создайте файл с именем UserRepository.java в том же каталоге, что и основной файл приложения Java.
Откройте файл UserRepository.java в текстовом редакторе и добавьте в него следующие строки, чтобы определить интерфейс пользовательского репозитория, дополняющего интерфейс 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);
}
```
Интерфейс ReactiveCosmosRepository заменяет интерфейс DocumentDbRepository из предыдущей версии начального приложения. Новый интерфейс предоставляет синхронные и реактивные API для базовых операций сохранения, удаления и поиска.
Сохраните и закройте файл UserRepository.java.

Изменение класса основного приложения

Найдите файл основного приложения Java в каталоге пакета приложения, например:

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

–или–

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

Откройте файл основного приложения Java в текстовом редакторе и добавьте в него следующие строки:

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

Сохраните и закройте файл основного приложения Java.

Создание и тестирование приложения

Откройте командную строку и перейдите к папке с файлом pom.xml, например:

cd C:\SpringBoot\wingtiptoysdata

–или–

cd /users/example/home/wingtiptoysdata
Выполните сборку приложения и запустите его с помощью следующей команды:
```
./mvnw clean
```
Эта команда позволяет автоматически запустить приложение как часть этапа тестирования. Кроме того, можно использовать следующую команду:
```
./mvnw spring-boot:run
```
После некоторых выходных данных сборки и тестирования окно консоли отображает сообщение, аналогичное следующему примеру:
```
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
```
Эти выходные сообщения указывают на то, что данные были успешно сохранены в Azure Cosmos DB, а затем снова извлечены.

Очистка ресурсов

Если вы не собираетесь продолжать использовать это приложение, обязательно удалите группу ресурсов, содержащую созданную ранее базу данных Azure Cosmos DB. Группу ресурсов можно удалить из портал Azure.

Следующие шаги

Дополнительные сведения о Spring и Azure см. в центре документации об использовании Spring в Azure.

Spring в Azure

Дополнительные ресурсы

Дополнительные сведения об использовании Azure PowerShell и Java см. в следующих статьях:

Дополнительные сведения об использовании приложений Spring Boot в Azure см. в следующих статьях:

[Spring Cloud Starter for Spring Data Azure Cosmos DB]
Развертывание приложения Spring Boot в Службе приложений Azure в Linux
Запуск приложения Spring Boot в кластере Kubernetes в Службе контейнеров Azure

Дополнительные сведения об использовании Java в Azure см. в статьях Azure для разработчиков Java и Working with Azure DevOps and Java (Работа с Azure DevOps и Java).

Spring Framework — это решение с открытым кодом, которое помогает разработчикам Java создавать приложения корпоративного класса. Одним из самых популярных проектов, созданных на этой платформе, является проект Spring Boot. Он упрощает подход к созданию автономных приложений Java. В помощь разработчикам, начинающим работать со Spring Boot, по адресу https://github.com/spring-guides/ доступно несколько примеров пакетов этого приложения. Помимо выбора из списка основных проектов Spring Boot, Spring Initializr помогает разработчикам создавать пользовательские приложения Spring Boot.

Поделиться через

Доступ к данным с помощью API NoSQL Azure Cosmos DB

Необходимые компоненты

Создание Azure Cosmos DB с помощью портала Azure

Создание приложения Spring Boot с помощью Spring Initializr

Настройка приложения Spring Boot для использования начального приложения Azure Spring Boot

Настройка приложения Spring Boot для использования с Azure Cosmos DB

Добавление примера кода для реализации базовых возможностей базы данных

Определение базового класса для хранения пользовательских данных

Определение интерфейса хранилища данных

Изменение класса основного приложения

Создание и тестирование приложения

Очистка ресурсов

Следующие шаги

Дополнительные ресурсы

Обратная связь

Обратная связь

Дополнительные ресурсы