Rychlý start: Klientská knihovna Azure Cosmos DB pro Apache Cassandra pro Javu

• Python
• Node.js
• C#
• Java
• Pokračovat

Začínáme s klientskou knihovnou Azure Cosmos DB for Apache Cassandra pro Javu pro ukládání, správu a dotazování nestrukturovaných dat Postupujte podle kroků v tomto průvodci a vytvořte nový účet, nainstalujte klientskou knihovnu Java, připojte se k účtu, proveďte běžné operace a dotazujte se na konečná ukázková data.

Referenční dokumentace k rozhraní API | Zdrojový kód knihovny | Balíček (Maven)

Požadavky

• Předplatné Azure

  • Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

• Nejnovější verze Azure CLI v Azure Cloud Shellu

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, přihlaste se k Azure CLI pomocí az login příkazu.

• Java 21 nebo novější

Instalace

Nejprve pro tuto příručku nastavte účet a vývojové prostředí. Tato část vás provede procesem vytvoření účtu, získáním jeho přihlašovacích údajů a následnou přípravou vývojového prostředí.

Vytvoření účtu

Začněte vytvořením rozhraní API pro účet Apache Cassandra. Po vytvoření účtu vytvořte klíčový prostor a tabulkové zdroje.

Azure CLI

1. Pokud ještě nemáte cílovou skupinu prostředků, použijte az group create příkaz k vytvoření nové skupiny prostředků ve vašem předplatném.

   az group create \
       --name "<resource-group-name>" \
       --location "<location>"
   

2. az cosmosdb create Pomocí příkazu vytvořte nový účet Azure Cosmos DB pro Apache Cassandra s výchozím nastavením.

   az cosmosdb create \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --locations "regionName=<location>" \
       --capabilities "EnableCassandra"
   

3. Vytvořte nový keyspace pojmenovaný az cosmosdb cassandra keyspace createcosmicworks.

   az cosmosdb cassandra keyspace create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --name "cosmicworks"
   

4. Vytvořte nový objekt JSON, který bude reprezentovat schéma pomocí příkazu Bash s více řádky. Potom pomocí az cosmosdb cassandra table create příkazu vytvořte novou tabulku s názvem products.

   schemaJson=$(cat <<EOF
   {
     "columns": [
       {
         "name": "id",
         "type": "text"
       },
       {
         "name": "name",
         "type": "text"
       },
       {
         "name": "category",
         "type": "text"
       },
       {
         "name": "quantity",
         "type": "int"
       },
       {
         "name": "price",
         "type": "decimal"
       },
       {
         "name": "clearance",
         "type": "boolean"
       }
     ],
     "partitionKeys": [
       {
         "name": "id"
       }
     ]
   }
   EOF
   )
   

   az cosmosdb cassandra table create \
       --resource-group "<resource-group-name>" \
       --account-name "<account-name>" \
       --keyspace-name "cosmicworks" \
       --name "product" \
       --schema "$schemaJson"
   

Azure Portal

1. Přihlaste se k webu Azure Portal (https://portal.azure.com).

2. Do globálního panelu hledání zadejte Azure Cosmos DB .

3. V rámci služeb vyberte Azure Cosmos DB.

4. V podokně Azure Cosmos DB vyberte Vytvořit a potom Azure Cosmos DB for Apache Cassandra na kartě Ostatní.

5. Jako typ účtu vyberte účet databáze jednotky žádosti (RU ).

6. V podokně Základy nakonfigurujte následující možnosti a pak vyberte Zkontrolovat a vytvořit:

   	Hodnota
   Typ úlohy	Vzdělávání
   Předplatné	Výběr předplatného Azure
   Skupina prostředků	Vytvoření nové skupiny prostředků nebo výběr existující skupiny prostředků
   Název účtu	Zadejte globálně jedinečný název.
   Zóny dostupnosti	Zakázat
   Umístění	Vyberte podporovanou oblast Azure pro vaše předplatné.

   Návod

   U výchozích hodnot můžete ponechat všechny nezadané možnosti. Můžete také nakonfigurovat účet tak, aby omezil celkovou propustnost účtu na 1 000 jednotek žádostí za sekundu (RU/s), nebo povolit úroveň Free, aby se minimalizovaly náklady.

7. V podokně Zkontrolovat a vytvořit počkejte na úspěšné ověření účtu a pak vyberte Vytvořit.

8. Portál automaticky přejde do podokna Nasazení . Počkejte, až se nasazení dokončí.

9. Po dokončení nasazení vyberte Přejít k prostředku a přejděte do nového rozhraní API pro účet Apache Cassandra.

10. V nabídce prostředků vyberte možnost Průzkumník dat .

11. V Průzkumníku dat vyberte + Nová tabulka.

12. V dialogovém okně Přidat tabulku nakonfigurujte následující možnosti a pak vyberte OK:

    	Hodnota
    Keyspace	Create new
    Název prostoru klíčů	cosmicworks
    Název tabulky	product
    Schéma tabulky	(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))

    Návod

    U výchozích hodnot můžete ponechat všechny nezadané možnosti.

Získání přihlašovacích údajů

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI

1. Slouží az cosmosdb show k získání kontaktního bodu a uživatelského jména pro účet.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{username:name,contactPoint:documentEndpoint}"
   

2. Poznamenejte si hodnotu contactPoint a username vlastnosti z výstupu předchozích příkazů. Hodnoty těchto vlastností jsou kontaktní bod a uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Slouží az cosmosdb keys list k získání klíčů pro účet.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Azure Portal

1. V nabídce prostředků pro účet vyberte možnost Připojovací řetězce v části Nastavení .

2. Poznamenejte si hodnotu pole KONTAKTNÍ BOD na této stránce. Hodnota této vlastnosti je kontaktní bod , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Poznamenejte si hodnotu pole USERNAME na této stránce. Hodnota této vlastnosti je uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

4. Zveřejnit a zaznamenat hodnotu pole PRIMÁRNÍ HESLO na této stránce. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Příprava vývojového prostředí

Potom nakonfigurujte vývojové prostředí s novým projektem a klientskou knihovnou. Tento krok je posledním požadovaným předpokladem před přechodem na zbytek této příručky.

1. Začněte v prázdném adresáři.

2. Vygenerujte nový projekt konzoly Java pomocí Mavenu.

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

3. Importujte java-driver-core balíček z Mavenu. Přidejte tento oddíl do souborupom.xml .

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

4. Otevřete soubor /console/src/main/java/quickstart/App.java .

5. Podívejte se na stávající ukázkový kód aplikace v Javě.

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

6. Odeberte komentáře a výstup z konzoly z boilerplate kódu. Tento blok kódu je výchozím bodem zbývající části tohoto průvodce.

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

7. Naimportujte java.security.NoSuchAlgorithmException obor názvů.

   import java.security.NoSuchAlgorithmException;
   

8. Aktualizujte podpis metody main, aby naznačoval, že může vyvolat výjimku NoSuchAlgorithmException.

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

   Důležité

   Zbývající kroky v této příručce předpokládají, že do metody přidáváte svůj kód main .

9. Zkompilujte projekt.

   mvn compile
   

Objektový model

	Popis
CqlSession	Představuje konkrétní připojení ke clusteru.
PreparedStatement	Představuje předkompilovaný příkaz CQL, který lze provést několikrát efektivně.
BoundStatement	Představuje připravený příkaz s vázanými parametry.
Row	Představuje jeden řádek výsledku dotazu.

Příklady kódu

• Ověření klienta
• Provést operaci Upsert (aktualizace nebo vložení) na data
• Čtení dat
• Dotazování dat

Ověření klienta

Začněte ověřením klienta pomocí přihlašovacích údajů shromážděných dříve v této příručce.

1. Otevřete soubor /console/src/main/java/quickstart/App.java v integrovaném vývojovém prostředí (IDE).

2. Importujte následující typy:

   • 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. Vytvořte řetězcové proměnné pro přihlašovací údaje shromážděné dříve v této příručce. Pojmenujte proměnné username, passworda contactPoint. Vytvořte také proměnnou řetězce pojmenovanou region pro místní datové centrum.

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

4. Vytvořte další řetězcovou proměnnou pro oblast, ve které jste vytvořili účet Azure Cosmos DB for Apache Cassandra. Pojmenujte tuto proměnnou region.

   String region = "<region>";
   

5. Vytvořte objekt, SSLContext abyste měli jistotu, že používáte protokol TLS (Transport Layer Security).

   SSLContext sslContext = SSLContext.getDefault();
   

6. Vytvořte nový CqlSession objekt pomocí přihlašovacích údajů a konfiguračních proměnných vytvořených v předchozích krocích. Nastavte kontaktní bod, místní datové centrum, přihlašovací údaje pro ověřování, prostor klíčů a kontext TLS (Transport Layer Security).

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

Výstraha

Úplné ověření protokolu TLS (Transport Layer Security) je v tomto průvodci zakázané, aby se zjednodušilo ověřování. Pro produkční nasazení plně povolte ověřování.

Vložit nebo aktualizovat data

V dalším kroku přepište nová data do tabulky. Přenesení zajistí, že se data vytvoří nebo nahradí odpovídajícím způsobem v závislosti na tom, jestli stejná data již v tabulce existují.

1. Definujte novou třídu s Product poli odpovídajícími tabulce vytvořené dříve v této příručce.

   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);
       }
   }
   

   Návod

   V Javě můžete tento typ vytvořit v jiném souboru nebo ho vytvořit na konci existujícího souboru.

2. Vytvořte nový objekt typu Product. Uložte objekt do proměnné s názvem product.

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

3. Vytvořte novou řetězcovou proměnnou s názvem insertQuery dotazu Cassandra Query Language (CQL) pro vložení nového řádku.

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

4. Připravte příkaz insert a svážete vlastnosti produktu jako parametry.

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

5. Upsert produktu spuštěním vázaného příkazu.

   session.execute(boundInsert);
   

Čtení dat

Potom načtěte data, která byla dříve převedena do tabulky.

1. Vytvořte novou řetězcovou proměnnou pojmenovanou readQuery s dotazem CQL, který odpovídá položkám se stejným polem id.

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

2. Vytvořte řetězcovou proměnnou s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

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

3. Připravte příkaz a přiřaďte pole produktu id jako parametr.

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

4. Spusťte vázaný příkaz a uložte výsledek do proměnné s názvem readResult.

   ResultSet readResult = session.execute(boundRead);
   

5. Načtěte první řádek ze sady výsledků a namapujte ho na objekt Product, pokud je nalezen.

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

Dotaz k datům

Teď pomocí dotazu najděte všechna data, která odpovídají určitému filtru v tabulce.

1. Vytvořte novou řetězcovou proměnnou pojmenovanou findQuery s dotazem CQL, který odpovídá položkám se stejným polem category.

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

2. Vytvořte řetězcovou proměnnou s názvem id se stejnou hodnotou jako produkt vytvořený dříve v této příručce.

   String category = "gear-surf-surfboards";
   

3. Připravte příkaz a vytvořte vazbu kategorie produktu jako parametr.

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

4. Spusťte vázaný příkaz a uložte výsledek do proměnné s názvem findResults.

   ResultSet results = session.execute(boundFind);
   

5. Iterujte výsledky dotazu a namapujte každý řádek na Product objekt.

   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
   }
   

Zavřít relaci

V Javě budete muset relaci ukončit, až budete hotovi s dotazy a operacemi.

session.close();

Spuštění kódu

Spusťte nově vytvořenou aplikaci pomocí terminálu v adresáři vaší aplikace.

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

Návod

Ujistěte se, že tento příkaz spouštíte v cestě /console vytvořené v rámci této příručky.

Vyčistěte zdroje

Teď získejte heslo pro klientskou knihovnu, které se má použít k vytvoření připojení k nedávno vytvořenému účtu.

Azure CLI

1. Slouží az cosmosdb show k získání kontaktního bodu a uživatelského jména pro účet.

   az cosmosdb show \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --query "{username:name,contactPoint:documentEndpoint}"
   

2. Poznamenejte si hodnotu contactPoint a username vlastnosti z výstupu předchozích příkazů. Hodnoty těchto vlastností jsou kontaktní bod a uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Slouží az cosmosdb keys list k získání klíčů pro účet.

   az cosmosdb keys list \
       --resource-group "<resource-group-name>" \
       --name "<account-name>" \
       --type "keys"
   

4. Poznamenejte si hodnotu primaryMasterKey vlastnosti z výstupu předchozích příkazů. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Azure Portal

1. V nabídce prostředků pro účet vyberte možnost Připojovací řetězce v části Nastavení .

2. Poznamenejte si hodnotu pole KONTAKTNÍ BOD na této stránce. Hodnota této vlastnosti je kontaktní bod , který použijete později v tomto průvodci pro připojení k účtu s knihovnou.

3. Poznamenejte si hodnotu pole USERNAME na této stránce. Hodnota této vlastnosti je uživatelské jméno , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

4. Zveřejnit a zaznamenat hodnotu pole PRIMÁRNÍ HESLO na této stránce. Hodnota této vlastnosti je heslo , které použijete později v tomto průvodci pro připojení k účtu s knihovnou.

Další krok

Přehled služby Azure Cosmos DB pro Apache Cassandra