Краткое руководство. Библиотека Azure Cosmos DB для NoSQL для Java

Статья
01/10/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

Начало работы с клиентской библиотекой Azure Cosmos DB для NoSQL для Java для запроса данных в контейнерах и выполнения общих операций с отдельными элементами. Выполните следующие действия, чтобы развернуть минимальное решение в вашей среде с помощью Интерфейса командной строки разработчика Azure.

Справочная документация по | API— пакет исходного кода | (Maven) | Azure Developer CLI

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

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Учетная запись GitHub

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Интерфейс командной строки разработчика Azure
Docker Desktop

Установка

Разверните контейнер разработки этого проекта в вашей среде. Затем используйте интерфейс командной строки разработчика Azure (azd) для создания учетной записи Azure Cosmos DB для NoSQL и развертывания контейнерного примера приложения. Пример приложения использует клиентская библиотека для управления, создания, чтения и запроса примеров данных.

Внимание

Учетные записи GitHub включают право на хранение и основные часы без затрат. Дополнительные сведения см . в разделе о хранилище и основных часах для учетных записей GitHub.

Откройте терминал в корневом каталоге проекта.
Проверка подлинности в интерфейсе командной строки разработчика Azure с помощью azd auth login. Выполните действия, указанные средством для проверки подлинности в CLI с помощью предпочитаемых учетных данных Azure.
```
azd auth login
```
Используется azd init для инициализации проекта.
```
azd init
```
Во время инициализации настройте уникальное имя среды.

Совет

Имя среды также будет использоваться в качестве имени целевой группы ресурсов. В этом кратком руководстве рекомендуется использовать msdocs-cosmos-db.
Разверните учетную запись Azure Cosmos DB с помощью azd up. Шаблоны Bicep также развертывают пример веб-приложения.
```
azd up
```
В процессе подготовки выберите подписку и нужное расположение. Дождитесь завершения процесса подготовки. Процесс может занять около пяти минут.

После завершения подготовки ресурсов Azure в выходные данные будет включен URL-адрес работающего веб-приложения.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Используйте URL-адрес консоли для перехода к веб-приложению в браузере. Просмотрите выходные данные запущенного приложения.

Установка клиентской библиотеки

Клиентская библиотека доступна через Maven в качестве azure-spring-data-cosmos пакета.

Перейдите в папку /src/web и откройте файл pom.xml .
Если он еще не существует, добавьте запись для azure-spring-data-cosmos пакета.
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
</dependency>
```
Кроме того, добавьте еще одну зависимость для azure-identity пакета, если она еще не существует.
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>
```

Объектная модель

Имя	Описание
`EnableCosmosRepositories`	Этот тип является декоратором методов, используемым для настройки репозитория для доступа к Azure Cosmos DB для NoSQL.
`CosmosRepository`	Этот класс является основным клиентским классом и используется для управления данными в контейнере.
`CosmosClientBuilder`	Этот класс используется для создания клиента, используемого репозиторием.
`Query`	Этот тип является декоратором методов, используемым для указания запроса, выполняемого репозиторием.

Пример кода в шаблоне использует базу данных с именем cosmicworks и контейнером products. Контейнер products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Контейнер использует /category свойство в качестве ключа логического раздела.

аутентификация клиента;

Запросы приложений к большинству служб Azure должны быть авторизованы. DefaultAzureCredential Используйте тип в качестве предпочтительного способа реализации подключения без пароля между приложениями и Azure Cosmos DB для NoSQL. DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения.

Внимание

Вы также можете авторизовать запросы к службам Azure с помощью паролей, строка подключения или других учетных данных напрямую. Однако этот подход следует использовать с осторожностью. Разработчики должны быть старательными, чтобы никогда не предоставлять эти секреты в небезопасном расположении. Любой, кто получает доступ к паролю или секретному ключу, может пройти проверку подлинности в службе базы данных. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля без риска хранения ключей.

Во-первых, в этом примере создается новый класс, наследующий от AbstractCosmosConfiguration настройки подключения к Azure Cosmos DB для NoSQL.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {

В классе конфигурации этот пример создает новый экземпляр CosmosClientBuilder класса и настраивает проверку подлинности с помощью экземпляра DefaultAzureCredential .

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential azureTokenCredential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint(uri)
        .credential(azureTokenCredential);
}

Получение базы данных

В классе конфигурации пример реализует метод для возврата имени существующей базы данных с именем cosmicworks.

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

Получение контейнера

Container Используйте декоратор метода, чтобы настроить класс для представления элементов в контейнере. Создайте класс, чтобы включить все элементы, которые необходимо сериализовать в JSON. В этом примере тип имеет уникальный идентификатор и поля для категории, имени, количества, цены и разрешения.

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

Создание элемента

Создайте элемент в контейнере с помощью repository.save.

Item item = new Item(
    "70b63682-b93a-4c77-aad2-65501347265f",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Чтение элемента

Выполните операцию чтения точек с помощью полей уникального идентификатора (id) и ключа секции. Используется repository.findById для эффективного извлечения определенного элемента.

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("70b63682-b93a-4c77-aad2-65501347265f", partitionKey);
if (existing_item.isPresent()) {
    // Do something  
}

Элементы запроса

Выполните запрос по нескольким элементам в контейнере, определив запрос в интерфейсе репозитория. В этом примере используется Query декоратор метода для определения метода, выполняющего этот параметризованный запрос:

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {
    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);
}

Получение всех результатов запроса с помощью repository.getItemsByCategory. Прокрутите результаты запроса.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

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

Руководство по созданию веб-приложения Java