Руководство по разработке Azure Cosmos DB

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

В этом руководстве описаны основные понятия пакета SDK Azure Spring Data Azure Cosmos DB, поддерживаемые функции, устранение неполадок и известные проблемы. Дополнительные сведения о приведенных ниже понятиях и примерах кода см. в статье Spring Data for Azure Cosmos DB SDK readme.

Политика поддержки версий

Поддержка версии Spring Boot

Этот проект поддерживает несколько версий Spring Boot. Дополнительные сведения см. в разделе Политика поддержки Spring Boot. Пользователи Maven могут наследовать от проекта spring-boot-starter-parent, чтобы получить раздел управления зависимостями, чтобы разрешить Spring управлять версиями зависимостей. Дополнительные сведения см. в разделе Поддержка версий Spring Boot.

Поддержка версии Spring Data

Этот проект поддерживает разные версии spring-data-commons. Дополнительные сведения см. в разделе Поддержка версий Spring Data.

Какую версию Azure Spring Data Azure Cosmos DB использовать

Библиотека Azure Spring Data Azure Cosmos DB поддерживает несколько версий Spring Boot или Spring Cloud. Дополнительные сведения о том, какую версию Azure Spring Data для Azure Cosmos DB следует выбрать для Spring Boot / Spring Cloud, см. в статье Какую версию Azure Spring Data для Azure Cosmos DB следует использовать?.

Начало работы

Включите пакет

Если вы используете Maven, добавьте следующую зависимость.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

Необходимые условия

• пакет средств разработки Java (JDK)версии 8 или более поздней.
• Активная учетная запись Azure. Если у вас нет учетной записи, вы можете зарегистрироваться для бесплатной учетной записи. Кроме того, можно использовать эмулятор Azure Cosmos DB для разработки и тестирования. Так как сертификат HTTPS эмулятора является самоподписанным, необходимо импортировать его сертификат в хранилище доверенных сертификатов Java, описано здесь
• (Необязательно) SLF4J — это фасад ведения журнала.
• (Необязательно) привязка SLF4J используется для связывания конкретной платформы логгирования с SLF4J.
• (Необязательно) Maven

SLF4J требуется только в том случае, если планируется использовать ведение журнала, а также скачать привязку SLF4J, которая будет связывать API SLF4J с реализацией ведения журнала по вашему выбору. Дополнительные сведения см. в руководстве пользователя SLF4J .

Настройте и кастомизируйте класс конфигурации

Чтобы настроить класс конфигурации, необходимо расширить AbstractCosmosConfiguration. Для получения дополнительной информации см. раздел класса настройки конфигурации.

Вы можете настроить базовые CosmosAsyncClient, используемые пакетом SDK Azure Spring Data Azure Cosmos DB, предоставив DirectConnectionConfig, GatewayConnectionConfig или оба и передав их CosmosClientBuilder. Полный пример см. в разделе настройки конфигурации.

Настройка объектов

Вы можете определить простую сущность как элемент в Azure Cosmos DB. Сущности можно определить, добавив заметку @Container и указав свойства, связанные с контейнером. Дополнительные сведения см. в разделе Определение сущности.

Аннотация контейнера поддерживает указание имени контейнера, единиц запроса (ЕЗ), времени жизни, создания контейнеров с автоматически масштабируемой пропускной способностью, поддержка вложенных ключей разделаи других свойств контейнера.

Настройка репозитория

Azure Spring Data Azure Cosmos DB поддерживает ReactiveCrudRepository (асинхронные API) и CrudRepository (API синхронизации), которые предоставляют следующие основные функции CRUD:

• сохранить
• findAll
• НайтиОдин по идентификатору
• удалить все
• Удалить по идентификатору
• Удалить сущность

Вы можете расширить CosmosRepository (для поддержки API синхронизации) или ReactiveCosmosRepository (для асинхронной поддержки API), чтобы настроить репозитории Spring Data для приложения. Дополнительные сведения см. в разделе Создание репозиториев.

Azure Spring Data Azure Cosmos DB поддерживает указание аннотированных запросов в репозиториях с помощью @Query. Дополнительные сведения см. в разделе QueryAnnotation: использование аннотированных запросов в репозиториях.

Аннотации Spring Data

Аннотация @Id Spring Data

Существует несколько способов сопоставления поля в классе домена с id. Для получения дополнительной информации см. раздел с кодом аннотации идентификатора данных Spring.

Автоматическое создание идентификаторов

Azure Spring Data Azure Cosmos DB поддерживает автоматическое создание идентификаторов с помощью заметки @GeneratedValue. Для получения дополнительной информации см. раздел автогенерации идентификаторов .

Выражение SpEL и пользовательское имя контейнера

По умолчанию имя контейнера будет именем класса пользователя. Чтобы настроить, добавьте аннотацию @Container(containerName="myCustomContainerName") в класс домена. Дополнительные сведения см. в выражении SpEL и разделе пользовательского имени контейнера .

Пользовательская политика индексации

По умолчанию IndexingPolicy будет задана службой Azure. Чтобы настроить, добавьте заметку @CosmosIndexingPolicy в класс домена. Дополнительные сведения см. в разделе политики индексирования .

Уникальная политика ключей

Azure Spring Data Azure Cosmos DB поддерживает настройку UniqueKeyPolicy в контейнере, добавляя аннотацию @CosmosUniqueKeyPolicy в класс домена. Дополнительные сведения см. в разделе политики уникального ключа .

Раздел Azure Cosmos DB

Azure-spring-data-cosmos поддерживает разделы Azure Cosmos DB.

Чтобы указать поле класса домена в качестве ключевого поля секции, просто аннотируйте его, используя @PartitionKey.

При выполнении операции CRUD укажите значение раздела.

Подробнее см. здесь в разделе теста .

Оптимистическая блокировка

Azure-spring-data-cosmos поддерживает оптимистическую блокировку для определенных контейнеров, что означает, что добавление/удаление элементов завершатся ошибкой, если элемент будет изменен другим процессом в то же время. Дополнительные сведения см. в разделе "Оптимистическая блокировка".

Настраиваемый запрос Spring Data, поддержка разбиения на страницы и сортировка

Azure-spring-data-cosmos поддерживает пользовательские запросы Spring Data, например, операцию поиска, такую как findByAFieldAndBField. Она также поддерживает Spring Data Pageable, Срезов и Сортировки. Для получения дополнительной информации см. раздел "Запрос ", а также разделы "Пагинация и сортировка".

Использование пакета SDK Java для Azure Cosmos DB с помощью Spring Data Cosmos

Azure-spring-data-cosmos поддерживает использование Azure Cosmos DB Java SDK. Пользователи могут получать объекты CosmosClient или CosmosAsyncClient через ApplicationContext и выполнять любые операции, поддерживаемые Java SDK для Azure Cosmos DB. Дополнительные сведения вы найдете в разделе , в котором рассматривается использование Azure Cosmos Client через Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos поддерживает REST Spring Data. См. раздел Azure Spring Data Azure Cosmos DB REST APIдля получения дополнительной информации.

Аудит

Azure-spring-data-cosmos поддерживает аудит полей сущностей базы данных с помощью стандартных аннотаций Spring Data. Дополнительные сведения см. в разделе аудита Spring Data Azure Cosmos DB.

Конфигурация с несколькими базами данных

Azure-spring-data-cosmos поддерживает конфигурацию с несколькими базами данных, включая несколько учетных записей базы данных и одну учетную запись с несколькими базами данных. Полный фрагмент кода см. в разделе конфигурации нескольких баз данных.

Устранение неполадок

Общее

Если возникла ошибка, отправьте файл проблемы здесь.

Чтобы предложить новую функцию или изменения, которые могут быть сделаны, отправьте проблему так же, как и для ошибки.

Включение ведения журнала клиентов

Azure-spring-data-cosmos использует SLF4j в качестве фасада ведения журнала, который поддерживает вход в популярные платформы ведения журнала, такие как log4j и logback. Дополнительные сведения см. в разделе включение ведения журнала клиентов.

Примеры

Полный пример проекта см. в проекте-примере .

Учетные записи с несколькими базами данных

Полный пример проекта см. в разделе пример проекта с несколькими базами данных.

Одна учетная запись с несколькими базами данных

Полный пример проекта см. в статье Отдельная учетная запись с примером проекта с несколькими базами данных.

Дальнейшие действия

• Узнайте больше об Azure Spring Data Azure Cosmos DB.
• Дополнительные сведения о службе Azure Cosmos DB
• См. примеры Azure Spring Data Azure Cosmos DB
• Смотрите пример Spring MVC с Azure Cosmos DB

Внесение вклада

Этот проект приветствует взносы и предложения. Большинство вкладов требует, чтобы вы согласились с Соглашением о лицензировании участника (CLA), подтверждающим, что вы имеете право и действительно предоставляете нам права на использование вашего вклада.

При отправке запроса на вытягивание бот CLA автоматически определит, нужно ли предоставлять соглашение о лицензионных условиях, и соответствующим образом обозначит PR — например, меткой или комментарием. Просто следуйте инструкциям, предоставленным ботом. Это нужно сделать только один раз во всех репозиториях, используя наше согласие на лицензионное соглашение (CLA).

Этот проект принял Microsoft Open Source Code of Conduct. Дополнительные сведения см. в часто задаваемых вопросов о кодексе поведения или opencode@microsoft.com с другими вопросами или комментариями.