Быстрый старт: библиотека клиента Apache Cassandra в Azure Cosmos DB, предназначенная для Java

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

Справочная документация по | APIИсходный код | библиотекиПакет (Maven)

Предпосылки

• подписка Azure

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

• Последняя версия Azure CLI в Azure Cloud Shell.

  • Если вы предпочитаете локально запускать справочные команды CLI, войдите в Azure CLI с помощью az login команды.

• Java 21 или более поздней версии

Настройка

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

Создать аккаунт

Сначала создайте API для учетной записи Apache Cassandra. После создания учетной записи создайте пространство ключей и ресурсы для таблицы.

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

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

Подготовка среды разработки

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

1. Начните в пустом каталоге.

2. Создайте новый проект консоли Java с помощью Maven.

   mvn archetype:generate -DgroupId=quickstart -DartifactId=console -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   

3. Импортируйте пакет java-driver-core из Maven. Добавьте этот раздел в файл pom.xml .

   <dependency>
     <groupId>org.apache.cassandra</groupId>
     <artifactId>java-driver-core</artifactId>
     <version>[4.,)</version>
   </dependency>
   

4. Откройте файл /console/src/main/java/quickstart/App.java .

5. Обратите внимание на существующий стандартный шаблон приложения Java.

   package quickstart;
   
   /**
    * Hello world!
    *
    */
   public class App 
   {
       public static void main( String[] args )
       {
           System.out.println( "Hello World!" );
       }
   }
   

6. Удалите комментарии и выходные данные консоли из стандартного шаблона. Этот блок кода является отправной точкой для остальной части этого руководства.

   package quickstart;
   
   public class App 
   {
       public static void main(String[] args)
       {
       }
   }
   

7. Импорт пространства java.security.NoSuchAlgorithmException имен.

   import java.security.NoSuchAlgorithmException;
   

8. Обновите сигнатуру main метода, чтобы указать, что это может вызвать NoSuchAlgorithmException исключение.

   public static void main(String[] args) throws NoSuchAlgorithmException
   {    
   }
   

   Это важно

   Остальные шаги в этом руководстве предполагают, что вы добавляете код в метод main.

9. Создайте проект.

   mvn compile
   

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

Примеры кода

• Проверка подлинности клиента
• Обновление и добавление данных
• Чтение данных
• Запрос данных

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

Начните с проверки подлинности клиента с помощью учетных данных, собранных ранее в этом руководстве.

1. Откройте файл /console/src/main/java/quickstart/App.java в интегрированной среде разработки (IDE).

2. Импортируйте следующие типы:

   • java.net.InetSocketAddress
   • javax.net.ssl.SSLContext
   • com.datastax.oss.driver.api.core.CqlIdentifier
   • com.datastax.oss.driver.api.core.CqlSession
   • com.datastax.oss.driver.api.core.cql.BoundStatement
   • com.datastax.oss.driver.api.core.cql.PreparedStatement
   • com.datastax.oss.driver.api.core.cql.ResultSet
   • com.datastax.oss.driver.api.core.cql.Row

   import java.net.InetSocketAddress;    
   
   import javax.net.ssl.SSLContext;
   
   import com.datastax.oss.driver.api.core.CqlIdentifier;
   import com.datastax.oss.driver.api.core.CqlSession;
   import com.datastax.oss.driver.api.core.cql.BoundStatement;
   import com.datastax.oss.driver.api.core.cql.PreparedStatement;
   import com.datastax.oss.driver.api.core.cql.ResultSet;
   import com.datastax.oss.driver.api.core.cql.Row;
   

3. Создайте строковые переменные для учетных данных, собранных ранее в этом руководстве. Присвойте переменным usernamepasswordи contactPoint. Кроме того, создайте строковую переменную с именем region локального центра обработки данных.

   String username = "<username>";
   String password = "<password>";
   String contactPoint = "<contact-point>";
   

4. Создайте другую строковую переменную для региона, в котором вы создали учетную запись Azure Cosmos DB для Apache Cassandra. Присвойте этой переменной regionимя.

   String region = "<region>";
   

5. SSLContext Создайте объект, чтобы убедиться, что вы используете протокол TLS.

   SSLContext sslContext = SSLContext.getDefault();
   

6. Создайте новый CqlSession объект с помощью учетных данных и переменных конфигурации, созданных на предыдущих шагах. Задайте точку контакта, локальный центр обработки данных, учетные данные проверки подлинности, пространство ключей и контекст TLS.

   CqlSession session = CqlSession.builder()
       .addContactPoint(new InetSocketAddress(contactPoint, 10350))
       .withLocalDatacenter(region)
       .withAuthCredentials(username, password)
       .withKeyspace(CqlIdentifier.fromCql("cosmicworks"))
       .withSslContext(sslContext)
       .build();
   

Обновление-вставка данных

Затем переведите новые данные в таблицу. Upserting гарантирует, что данные создаются или заменяются соответствующим образом в зависимости от того, существуют ли те же данные в таблице.

1. Определите новый класс Product с полями, соответствующими таблице, созданной ранее в этом руководстве.

   class Product {
       public String id;
       public String name;
       public String category;
       public int quantity;
       public boolean clearance;
   
       public Product(String id, String name, String category, int quantity, boolean clearance) {
           this.id = id;
           this.name = name;
           this.category = category;
           this.quantity = quantity;
           this.clearance = clearance;
       }
   
       @Override
       public String toString() {
           return String.format("Product{id='%s', name='%s', category='%s', quantity=%d, clearance=%b}",
                   id, name, category, quantity, clearance);
       }
   }
   

   Подсказка

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

2. Создайте новый объект типа Product. Сохраните объект в переменной с именем product.

   Product product = new Product(
       "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
       "Yamba Surfboard",
       "gear-surf-surfboards",
       12,
       false
   );
   

3. Создайте новую строковую переменную insertQuery с языковым запросом Cassandra (CQL) для вставки новой строки данных.

   String insertQuery = "INSERT INTO product (id, name, category, quantity, clearance) VALUES (?, ?, ?, ?, ?)";
   

4. Подготовьте инструкцию insert и привязите свойства продукта в качестве параметров.

   PreparedStatement insertStmt = session.prepare(insertQuery);
   BoundStatement boundInsert = insertStmt.bind(
       product.id,
       product.name,
       product.category,
       product.quantity,
       product.clearance
   );
   

5. Upsert продукт путем выполнения привязанной инструкции.

   session.execute(boundInsert);
   

Чтение данных

Затем считывайте данные, которые ранее были добавлены в таблицу.

1. Создайте новую строковую переменную с именем readQuery, содержащую CQL-запрос, который выбирает элементы с тем же полем id.

   String readQuery = "SELECT * FROM product WHERE id = ? LIMIT 1";
   

2. Создайте строковую переменную id с тем же значением, что и продукт, созданный ранее в этом руководстве.

   String id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
   

3. Подготовьте инструкцию и привязите поле продукта id в качестве параметра.

   PreparedStatement readStmt = session.prepare(readQuery);
   BoundStatement boundRead = readStmt.bind(id);
   

4. Выполните привязанную инструкцию и сохраните результат в переменной с именем readResult.

   ResultSet readResult = session.execute(boundRead);
   

5. Извлеките первую строку из результирующего набора и сопоставьте ее с объектом Product, если он будет найден.

   Row row = readResult.one();
   Product matchedProduct = new Product(
       row.getString("id"),
       row.getString("name"),
       row.getString("category"),
       row.getInt("quantity"),
       row.getBoolean("clearance")
   );
   

Запрос данных

Теперь используйте запрос, чтобы найти все данные, соответствующие определенному фильтру в таблице.

1. Создайте новую строковую переменную с именем findQuery, содержащую CQL-запрос, который выбирает элементы с тем же полем category.

   String findQuery = "SELECT * FROM product WHERE category = ? ALLOW FILTERING";
   

2. Создайте строковую переменную id с тем же значением, что и продукт, созданный ранее в этом руководстве.

   String category = "gear-surf-surfboards";
   

3. Подготовьте инструкцию и привязите категорию продукта в качестве параметра.

   PreparedStatement findStmt = session.prepare(findQuery);
   BoundStatement boundFind = findStmt.bind(category);
   

4. Выполните привязанную инструкцию и сохраните результат в переменной с именем findResults.

   ResultSet results = session.execute(boundFind);
   

5. Выполните итерацию по результатам запроса и сопоставите каждую Product строку с объектом.

   for (Row result : results) {
       Product queriedProduct = new Product(
           result.getString("id"),
           result.getString("name"),
           result.getString("category"),
           result.getInt("quantity"),
           result.getBoolean("clearance")
       );
       // Do something here with each result
   }
   

Закрытие сеанса

В Java необходимо закрыть сеанс после завершения любых запросов и операций.

session.close();

Запустите код

Запустите созданное приложение с помощью терминала в каталоге приложения.

mvn compile
mvn exec:java -Dexec.mainClass="quickstart.App"

Очистите ресурсы

Теперь получите пароль для клиентской библиотеки для создания подключения к недавно созданной учетной записи.

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