Руководство для разработчиков 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, поддерживаемые функции, устранение неполадок и известные проблемы. Дополнительные сведения о приведенных ниже понятиях и примерах кода см. в описании средств чтения пакета SDK Spring Data для Azure Cosmos DB.

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

Поддержка версии 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 (поиск всех)
• findOne by ID (поиск одного по идентификатору)
• deleteAll (удаление всех)
• delete by ID (удаление по идентификатору)
• delete entity (удаление объекта)

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

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

Заметки Spring Data

Заметка @Id Spring Data

Существует несколько способов сопоставления поля в классе idдомена. Дополнительные сведения см. в разделе кода заметки с идентификатором spring data id.

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

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

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

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

Custom IndexingPolicy

По умолчанию 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 поддерживает оптимистическую блокировку для определенных контейнеров, что означает, что upserts/deletes by item завершится ошибкой, если элемент изменяется другим процессом в то же время. Дополнительные сведения см. в разделе оптимистичной блокировки.

Пользовательский запрос 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. Пользователи могут получать или CosmosAsyncClient выполнять CosmosClient ApplicationContext любые операции, поддерживаемые пакетом SDK Java для Azure Cosmos DB. Дополнительные сведения см. в разделе об использовании клиента Azure Cosmos через Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos поддерживает Spring Data REST. Дополнительные сведения см. в разделе REST API Azure Spring Data Azure Cosmos DB.

Аудит

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.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в статье Вопросы и ответы, связанные с правилами поведения. Чтобы задать вопрос или получить комментарии, обратитесь по адресу opencode@microsoft.com.