Краткое руководство. Создание приложения Spring Data Azure Cosmos DB версии 3 для управления данными API SQL Azure Cosmos DB

ПРИМЕНИМО К: API SQL

В этом кратком руководстве вы научитесь создавать учетную запись API SQL Azure Cosmos DB и управлять ею на портале Azure, а также с помощью приложения Spring Data Azure Cosmos DB версии 3, клонированного с GitHub. Сначала создайте учетную запись API SQL Azure Cosmos DB с помощью портала Azure, а затем создайте приложение Spring Boot с помощью соединителя Spring Data Azure Cosmos DB версии 3, а затем добавьте ресурсы в учетную запись Cosmos DB с помощью приложения Spring Boot. Azure Cosmos DB — это служба многомодельной базы данных, позволяющая быстро создать и запрашивать документы, таблицы, пары "ключ-значение", а также графовые базы данных, используя возможности глобального распределения и горизонтального масштабирования.

Важно!

Эти заметки о выпуске применимы к Spring Data Azure Cosmos DB версии 3. Заметки о выпуске для версии 2 см. здесь.

Spring Data Azure Cosmos DB поддерживает только API SQL.

Сведения о Spring Data в других API-интерфейсах Azure Cosmos DB см. в этих статьях:

Предварительные требования

Вступительные примечания

Структура учетной записи Cosmos DB. Независимо от API или языка программирования, учетная запись Cosmos DB содержит несколько баз данных или не содержит их вовсе. База данных содержит несколько контейнеров или не содержит их вовсе, а контейнер содержит несколько элементов или не содержит их вовсе, как показано на схеме ниже:

Сущности учетной записи Azure Cosmos

Дополнительные сведения о базах данных, контейнерах и элементах см. здесь. На уровне контейнера определены несколько важных свойств, среди которых подготовленная пропускная способность и ключ секции.

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

Когда элементы вставляются в контейнер Cosmos DB, база данных увеличивается горизонтально, добавляя больше ресурсов хранения и вычисления для обработки запросов. Емкость хранилища и вычислительных ресурсов добавляется в дискретные единицы, известные как секции. Вам необходимо выбрать одно поле в документах в качестве ключа секции, который сопоставляет каждый документ с секцией. Способ управления секциями заключается в том, что каждой секции присваивается примерно равный срез из диапазона значений ключа секции. Таким образом рекомендуется выбирать ключ секции, который является относительно случайным или равномерно распределенным. В противном случае для одних секций будет значительно больше запросов (секции с высокой нагрузкой), в то время как для других секций будет значительно меньше запросов (секции с низкой нагрузкой), и этого следует избегать. Дополнительные сведения о секционировании см. здесь.

Создание учетной записи базы данных

Перед созданием базы данных документов необходимо создать в Azure Cosmos DB учетную запись API SQL.

  1. На домашней странице или в меню портала Azure выберите Создать ресурс.

  2. На странице Создание найдите и выберите Azure Cosmos DB.

  3. На странице Azure Cosmos DB выберите Создать.

  4. На странице создания учетной записи Azure Cosmos DB введите основные параметры для новой учетной записи Azure Cosmos.

    Параметр Значение Описание
    Подписка имя подписки; Выберите подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos.
    Группа ресурсов Имя группы ресурсов Выберите группу ресурсов или Создать, затем введите уникальное имя для новой группы ресурсов.
    Имя учетной записи Уникальное имя Введите имя для идентификации учетной записи Azure Cosmos. Так как элемент documents.azure.com добавляется к указанному вами имени для создания URI, используйте уникальное имя.

    Имя может содержать только строчные буквы, цифры и знак дефиса (-). Длина — от 3 до 44 знаков.
    API Тип учетной записи, которую нужно создать. Выберите Core (SQL) для создания базы данных документов и запроса с использованием синтаксиса SQL.

    API определяет тип учетной записи, которую нужно создать. Azure Cosmos DB предоставляет пять API: Core (SQL) и MongoDB для данных документа, Gremlin для данных графа, таблица Azure и Cassandra. Сейчас для каждого API требуется создавать отдельную учетную запись.

    Дополнительные сведения об API SQL
    Расположение Ближайший к пользователям регион Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.
    Режим емкости "Подготовленная пропускная способность" или "Бессерверный" Выберите Подготовленная пропускная способность, чтобы создать учетную запись в режиме подготовленной пропускной способности. Выберите Бессерверный, чтобы создать учетную запись в режиме Бессерверный.
    Применение скидки на основе категории "Бесплатный" для Azure Cosmos DB Применить или не применять В категории "Бесплатный" Azure Cosmos DB для учетной записи бесплатно предоставляются первые 1000 единиц запросов в секунду и 25 ГБ свободного места. Ознакомьтесь с дополнительными сведениями о категории "Бесплатный".

    Примечание

    Вы можете использовать не более одной учетной записи Azure Cosmos DB категории "Бесплатный" на подписку Azure. При создании учетной записи нужно зарегистрироваться. Если параметр подачи заявки на скидку на основе категории "Бесплатный" не отображается, это означает, что в подписке уже включена другая учетная запись категории "Бесплатный".

    Страница Новая учетная запись для Azure Cosmos DB

  5. На вкладке Глобальное распределение настройте следующие сведения. При работе с этим кратким руководством можно оставить значения по умолчанию.

    Параметр Значение Описание
    Геоизбыточность Отключить Включает или отключает глобальное распределение в вашей учетной записи, связывая ваш регион с парным регионом. В дальнейшем в учетную запись можно добавить дополнительные регионы.
    Операции записи с поддержкой нескольких регионов Отключить Поддержка записи в несколько регионов позволяет использовать подготовленную пропускную способность для баз данных и контейнеров по всему миру.

    Примечание

    Следующие параметры недоступны, если вы выбрали значение Бессерверный для параметра Режим емкости:

    • Применение скидки на основе категории "Бесплатный"
    • Геоизбыточность
    • Выполнение операций записи в нескольких регионах
  6. При необходимости можно настроить дополнительные сведения на следующих вкладках.

  7. Выберите Review + create (Просмотреть и создать).

  8. Проверьте параметры учетной записи, а затем нажмите кнопку Создать. Создание учетной записи занимает несколько минут. Дождитесь, пока на странице портала появится сообщение Развертывание выполнено.

    Область Уведомления на портале Azure

  9. Выберите Перейти к ресурсу, чтобы перейти на страницу учетной записи Azure Cosmos DB.

    Страница учетной записи Azure Cosmos DB

Добавление контейнера

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

  1. Щелкните Обозреватель данных > Создать контейнер.

    Справа отобразится область Добавить контейнер. Возможно, вам придется прокрутить экран вправо, чтобы увидеть ее.

    Панель Добавить контейнер в обозревателе данных на портале Azure

  2. На странице Добавить контейнер введите параметры для нового контейнера.

    Параметр Рекомендуемое значение Описание
    Идентификатор базы данных ToDoList Введите Задача в качестве имени новой базы данных. Имена баз данных должны быть длиной от 1 до 255 символов и не могут содержать символы /, \\, #, ? или пробел в конце. Установите флажок для параметра Общий доступ к пропускной способности в контейнерах, который позволяет предоставить общий доступ к пропускной способности, подготовленной для базы данных, для всех контейнеров в пределах базы данных. Этот параметр также способствует экономии денежных средств.
    Пропускная способность базы данных Для пропускной способности можно настроить автомасштабирование или задавать ее вручную. При настраиваемой вручную пропускной способности вы можете самостоятельно задавать значения ЕЗ/с, а при автомасштабировании система изменяет ЕЗ/с с учетом использования. Для этого примера выберите вариант с масштабируемой вручную пропускной способностью.

    Для пропускной способности сохраните значение в 400 единиц запроса в секунду. Если вы хотите сократить задержку, можно позже увеличить пропускную способность, оценив требуемый объем ЕЗ/с помощью калькулятора производительности.

    Примечание. Этот параметр недоступен при создании контейнера в бессерверной учетной записи.
    Идентификатор контейнера Items Введите Items в качестве имени нового контейнера. Для идентификаторов контейнеров предусмотрены те же требования к символам, что и для имен баз данных.
    Ключ секции /category В примере, описанном в этой статье, используется ключ секции /category.

    Не добавляйте уникальные ключи и не включайте аналитическое хранилище для этого примера. Уникальные ключи позволяют создать в базе данных дополнительный слой целостности данных, отслеживая уникальность одного или нескольких значений по каждому ключу секции. Дополнительные сведения см. в статье об уникальных ключах в Azure Cosmos DB. Аналитическое хранилище используется для поддержки крупномасштабной аналитики операционных данных и не влияет на транзакционные рабочие нагрузки.

    Щелкните ОК. В обозревателе данных отобразится новая база данных и контейнер.

Добавление демонстрационных данных

Теперь вы можете добавить данные в новый контейнер с помощью Data Explorer.

  1. В Data Explorer разверните базу данных Tasks, а затем контейнер Элементы. Выберите Элементы, а потом — Новый элемент.

    Создание документов в обозревателе данных на портале Azure

  2. Теперь можно добавить документ в контейнер со следующей структурой.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Добавив данные JSON на вкладке Документы, щелкните Сохранить.

    Копирование данных в формате JSON и нажатие кнопки "Сохранить" в обозревателе данных на портале Azure

  4. Создайте и сохраните один или несколько документов, задав уникальное значение для свойства id, и измените другие свойства по своему усмотрению. Новые документы могут иметь любую структуру, так как Azure Cosmos DB не устанавливает определенные схемы данных.

Обращение к данным

Вы можете применить запросы в обозревателе данных для получения и фильтрации данных.

  1. В верхней части вкладки Элементы в обозревателе данных просмотрите запрос по умолчанию SELECT * FROM c. Этот запрос позволяет извлечь и отобразить все документы из контейнера, упорядоченные по идентификаторам.

    Стандартный запрос SELECT * FROM c в обозревателе данных

  2. Чтобы изменить запрос, выберите Изменить фильтр, замените запрос по умолчанию на ORDER BY c._ts DESC, а затем выберите Применить фильтр.

    Изменение запроса по умолчанию с добавлением предиката ORDER BY c._ts DESC и применение фильтра

    Измененный запрос отображает все документы в порядке убывания метки времени, поэтому теперь первым в списке будет второй документ.

    Изменение запроса на предикат ORDER BY c._ts DESC и применение фильтра

Если вы знакомы с синтаксисом SQL, используйте в этом поле предиката запроса любой поддерживаемый SQL-запрос. Вы также можете использовать обозреватель данных для создания хранимых процедур, определяемых пользователем функций и триггеров для бизнес-логики на стороне сервера.

Это средство предоставляет легкий доступ на портале Azure ко всем встроенным возможностям программного доступа к данным, доступным в API-интерфейсах. Вы можете также воспользоваться порталом, чтобы масштабировать пропускную способность, получить ключи и строки подключения и просмотреть метрики и Соглашения об уровне обслуживания для своей учетной записи Azure Cosmos DB.

Клонирование примера приложения

Теперь перейдем к работе с кодом. Давайте клонируем приложение API SQL из GitHub. Задайте строку подключения и выполните ее. Вы узнаете, как можно упростить работу с данными программным способом.

Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.

git clone https://github.com/Azure-Samples/azure-spring-data-cosmos-java-sql-api-getting-started.git

Просмотр кода

Это необязательный шаг. Если вы хотите узнать, как создать в коде ресурсы базы данных, изучите приведенные ниже фрагменты кода. Вы можете сразу перейти к запуску приложения.

Файл конфигурации приложения

В этой статье показано, как Spring Boot и Spring Data улучшают взаимодействие с пользователем: в процессе установки клиента Cosmos и подключения к ресурсам Cosmos теперь быстрее использовать конфигурацию, а не писать код. Во время стартовой загрузки приложения Spring Boot обрабатывает все эти стандартные параметры используя настройки из application.properties:

cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

После создания учетной записи, базы данных и контейнера Azure Cosmos DB просто заполните пустое значение в файле конфигурации, и Spring Boot/Spring Data автоматически будут выполнять следующие действия: (1) создавать базовый экземпляр Java SDK CosmosClient с URI и ключом и (2) подключаться к базе данных и контейнеру. Все готово — и не нужно писать никакого кода для управления ресурсами!

Источник Java

Ценность Spring Data также заключается в простом, удобном, стандартизированном и независимом от платформы интерфейсе для работы с хранилищами. На основе образца Spring Data из GitHub, приведенного выше, ниже приведены примеры CRUD и запросов для управления документами Azure Cosmos DB с помощью Spring Data Azure Cosmos DB.

  • Создание и обновление элементов с помощью метода save.

    
    logger.info("Saving user : {}", testUser1);
    userRepository.save(testUser1);
    
    
  • Чтение с помощью метода производного запроса, определенного в репозитории. findByIdAndLastName выполняет операцию чтения для UserRepository. Поля, упомянутые в имени метода, вынуждают Spring Data выполнить чтение, определяемое полями id и lastName:

    
    // to find by Id, please specify partition key value if collection is partitioned
    final User result = userRepository.findByIdAndLastName(testUser1.getId(), testUser1.getLastName());
    logger.info("Found user : {}", result);
    
    
  • Удаление элементов с помощью deleteAll:

    
    userRepository.deleteAll();
    
    
  • Производный запрос на основе имени метода из репозитория. Spring Data реализует метод UserRepository findByFirstName как SQL-запрос пакета SDK для Java в поле firstName (этот запрос не может быть реализован как чтение):

    
    Flux<User> users = reactiveUserRepository.findByFirstName("testFirstName");
    users.map(u -> {
        logger.info("user is : {}", u);
        return u;
    }).subscribe();
    
    

Запустите приложение

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

  1. В окне терминала Git выполните команду cd, чтобы перейти к папке с примером кода.

    cd azure-spring-data-cosmos-java-sql-api-getting-started/azure-spring-data-cosmos-java-getting-started/
    
  2. В окне терминала Git используйте следующую команду, чтобы установить необходимые пакеты Spring Data Azure Cosmos DB.

    mvn clean package
    
  3. В окне терминала Git используйте следующую команду, чтобы запустить приложение Spring Data Azure Cosmos DB:

    mvn spring-boot:run
    
  4. Приложение загружает application.properties и подключает ресурсы в учетной записи Azure Cosmos DB.

  5. Приложение выполнит операции CRUD с точкой, описанные выше.

  6. Приложение выполнит производный запрос.

  7. Приложение не удаляет ресурсы. Вернитесь на портал, чтобы очистить ресурсы в своей учетной записи, если хотите избежать расходов.

Просмотр соглашений об уровне обслуживания на портале Azure

На портале Azure можно отслеживать пропускную способность, объем хранилища, доступность, задержку и согласованность учетной записи Cosmos DB. На диаграммах метрик, связанных с соглашением об уровне обслуживания для Azure Cosmos DB, отображается значение, указанное в соглашении об уровне обслуживания, в сравнении с фактической производительностью. Этот набор метрик обеспечивает прозрачный мониторинг выполнения соглашения об уровне обслуживания.

Чтобы просмотреть метрики и соглашения об уровне обслуживания, сделайте следующее:

  1. Выберите Метрики в меню навигации учетной записи Cosmos DB.

  2. Выберите вкладку, например Задержка, и укажите временной интервал справа. Сравните на диаграмме строки Actual (Фактическое значение) и SLA (Соглашение об уровне обслуживания).

    Набор метрик Azure Cosmos DB

  3. Просмотрите метрики на других вкладках.

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

После завершения работы с приложением и учетной записью Azure Cosmos DB можно удалить созданные ресурсы Azure, чтобы избежать дополнительных расходов. Удаление ресурсов:

  1. На панели поиска портала Azure найдите и выберите Группы ресурсов.

  2. Выберите из списка группу ресурсов, созданную для этого краткого руководства.

    Выбор удаляемой группы ресурсов

  3. На странице обзора группы ресурсов выберите Удалить группу ресурсов.

    удаление группы ресурсов.

  4. В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

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

В этом кратком руководстве было показано, как создать учетную запись API SQL Azure Cosmos DB, базу данных документов и контейнер с помощью обозревателя данных и как запустить приложение Spring Data, чтобы эти операции выполнялись программно. Теперь вы можете импортировать дополнительные данные в учетную запись Azure Cosmos DB.

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