Создание приложения Java для управления данными API Cassandra в Azure Cosmos DB (драйвер версии 4)

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

В этом кратком руководстве рассказывается, как создать учетную запись API Cassandra Azure Cosmos DB и использовать приложение Java Cassandra, клонированное из GitHub, чтобы создать базу данных и контейнер Cassandra с помощью драйверов Apache Cassandra версии 4.x для Java. Azure Cosmos DB — это служба многомодельной базы данных, позволяющая быстро создавать и запрашивать документы, таблицы, пары "ключ-значение" и графовые базы данных, используя возможности глобального распределения и горизонтального масштабирования.

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

Примечание

Это простое краткое руководство, в котором используется версия 4 драйвера Apache Cassandra для Java с открытым кодом. В большинстве случаев вы сможете подключить существующее приложение Java, зависимое от Apache Cassandra, к API Cassandra для Azure Cosmos DB без изменений в существующем коде. Однако рекомендуется добавить наше пользовательское расширение Java, которое включает в себя пользовательские политики повтора и балансировки нагрузки, а также рекомендуемые настройки подключения для обеспечения более качественной работы. Это необходимо в определенных случаях для ограничения скорости и отработки отказа на уровне приложения в Azure Cosmos DB. Подробный пример реализации расширения можно найти здесь.

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

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

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

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

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

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

    Параметр Значение Описание
    Подписка Ваша подписка Вы подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos DB.
    Группа ресурсов Создание

    Затем введите имя, использованное для учетной записи
    Выберите Создать. Затем введите новое имя группы ресурсов для учетной записи. Для удобства можно использовать то же имя, которое присвоено учетной записи Azure Cosmos.
    Имя учетной записи Введите уникальное имя. Введите уникальное имя для идентификации вашей учетной записи Azure Cosmos DB. URI вашей учетной записи cassandra.cosmos.azure.com будет добавлен к уникальному имени учетной записи.

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

    Выберите Cassandra, так как в рамках этого краткого руководства вы создадите таблицу, которая работает с API Cassandra.

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

    Примечание

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

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

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

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

    Примечание

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

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

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

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

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

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

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

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

  1. Откройте командную строку. Создайте папку с именем git-samples. Затем закройте командную строку.

    md "C:\git-samples"
    
  2. Откройте окно терминала git, например git bash, и выполните команду cd, чтобы перейти в новую папку для установки примера приложения.

    cd "C:\git-samples"
    
  3. Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
    

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

Это необязательный шаг. Если вы хотите узнать, как создавать ресурсы базы данных в коде, изучите приведенные ниже фрагменты кода. Если вас это не интересует, можете сразу переходить к разделу Обновление строки подключения. Эти фрагменты кода взяты из файла src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

  • CqlSession подключается к API Cassandra для Azure Cosmos DB и возвращает сеанс для доступа (объект Cluster из драйвера версии 3 уже устарел). Имя пользователя, пароль, порт и узел Cassandra задаются с помощью страницы строки подключения на портале Azure.

        this.session = CqlSession.builder().withSslContext(sc)
                .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
                .withAuthCredentials(cassandraUsername, cassandraPassword).build();
    

Следующие фрагменты кода взяты из файла src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

  • Если при предыдущем запуске было создано ключевое пространство, его нужно удалить.

    public void dropKeyspace() {
        String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
        session.execute(query);
        LOGGER.info("dropped keyspace '"+keyspace+"'");
    } 
    
  • Создается пространство ключей.

    public void createKeyspace() {
        String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
        session.execute(query);
        LOGGER.info("Created keyspace '"+keyspace+"'");
    }
    
  • Создается таблица.

      public void createTable() {
          String query = "CREATE TABLE "+keyspace+"."+table+" (user_id int PRIMARY KEY, user_name text, user_bcity text)";
          session.execute(query);
          LOGGER.info("Created table '"+table+"'");
      }
    
  • Пользовательские сущности вставляются с использованием подготовленного объекта инструкций.

    public String prepareInsertStatement() {
        final String insertStatement = "INSERT INTO  "+keyspace+"."+table+" (user_id, user_name , user_bcity) VALUES (?,?,?)";
        return insertStatement;
    }
    
    public void insertUser(String preparedStatement, int id, String name, String city) {
        PreparedStatement prepared = session.prepare(preparedStatement);
        BoundStatement bound = prepared.bind(id, city, name).setIdempotent(true);
        session.execute(bound);
    }
    
  • Выполняется запрос на получение информации обо всех пользователях.

    public void selectAllUsers() {
        final String query = "SELECT * FROM "+keyspace+"."+table+"";
        List<Row> rows = session.execute(query).all();
    
        for (Row row : rows) {
            LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
        }
    }
    
  • Выполняется запрос на получение информации об одном пользователе.

    public void selectUser(int id) {
        final String query = "SELECT * FROM "+keyspace+"."+table+" where user_id = 3";
        Row row = session.execute(query).one();
    
        LOGGER.info("Obtained row: {} | {} | {} ", row.getInt("user_id"), row.getString("user_name"), row.getString("user_bcity"));
    }
    

Обновление строки подключения

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

  1. Выберите элемент Строка подключения в своей учетной записи Azure Cosmos DB на портале Azure.

    Просмотр и копирование имени пользователя на странице &quot;Строка подключения&quot; на портале Azure

  2. Используйте кнопку в правой части экрана, чтобы скопировать значение параметра CONTACT POINT.

  3. Откройте файл config.properties из папки C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.

  4. Вставьте полученное на портале значение параметра CONTACT POINT вместо элемента <Cassandra endpoint host> в строке 2.

    Теперь строка 2 в файле config.properties будет выглядеть примерно так:

    cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com

  5. Вернитесь на портал и скопируйте значение USERNAME. Вставьте полученное на портале значение USERNAME вместо элемента <cassandra endpoint username> в строке 4.

    Теперь строка 4 в файле config.properties будет выглядеть примерно так:

    cassandra_username=cosmos-db-quickstart

  6. Вернитесь на портал и скопируйте значение PASSWORD. Вставьте полученное на портале значение PASSWORD вместо элемента <cassandra endpoint password> в строке 5.

    Теперь строка 5 в файле config.properties будет выглядеть примерно так:

    cassandra_password=2Ggkr662ifxz2Mg...==

  7. Если вы хотите использовать определенный TLS/SSL-сертификат, замените элемент <SSL key store file location> в строке 6 расположением своего TLS/SSL-сертификата. Если не указать это значение, будет использоваться сертификат JDK, установленный в папке <JAVA_HOME>/jre/lib/security/cacerts.

  8. Если вы изменили строку 6, чтобы использовать свой TLS/SSL-сертификат, укажите пароль для этого сертификата в строке 7.

  9. Обратите внимание, что для точки контакта требуется указать регион по умолчанию (например, West US):

    region=West US

    Это нужно, потому что драйвер версии 4.x не поддерживает связь нескольких локальных контроллеров домена с точкой контакта. Чтобы указать другой регион, помимо заданного по умолчанию (т. е. при создании учетной записи Cosmos DB), при добавлении точки контакта необходимо использовать региональный суффикс, например host-westus.cassandra.cosmos.azure.com.

  10. Сохраните файл config.properties.

Запуск приложения Java

  1. В окне терминала git с помощью команды cd перейдите к папке azure-cosmosdb-cassandra-java-getting-started-v4.

    cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
    
  2. В окне терминала Git используйте приведенную ниже команду, чтобы создать файл cosmosdb-cassandra-examples.jar.

    mvn clean install
    
  3. В окне терминала Git выполните следующие команды, чтобы запустить приложение Java.

    java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
    

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

    Нажмите клавиши CTRL+C, чтобы остановить выполнение программы и закрыть окно консоли.

  4. На портале Azure откройте обозреватель данных, чтобы запросить, изменить и обработать новые данные.

    Просмотр данных в обозревателе данных — Azure Cosmos DB

Просмотр соглашений об уровне обслуживания на портале 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. В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

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

Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB с помощью API Cassandra и запустить приложение Cassandra Java, которое создает базу данных и контейнер Cassandra. Теперь вы можете импортировать дополнительные данные в учетную запись Azure Cosmos DB.