Udostępnij za pomocą

Szybki start: biblioteka klienta usługi Azure Cosmos DB dla oprogramowania Apache Cassandra dla języka Java

  • Dotyczy: ✅ Apache Cassanda

Rozpocznij pracę z biblioteką klienta usługi Azure Cosmos DB for Apache Cassandra dla języka Java, aby przechowywać dane bez struktury i zarządzać nimi. Wykonaj kroki opisane w tym przewodniku, aby utworzyć nowe konto, zainstalować bibliotekę klienta Java, nawiązać połączenie z kontem, wykonać typowe operacje i wykonać zapytania dotyczące końcowych danych przykładowych.

Dokumentacja referencyjna API | Kod źródłowy biblioteki | Pakiet (Maven)

Wymagania wstępne

  • Subskrypcja platformy Azure

    • Jeśli nie masz subskrypcji Azure, przed rozpoczęciem utwórz darmowe konto.
  • Środowisko Java 21 lub nowsze

Konfigurowanie

Najpierw skonfiguruj konto i środowisko programistyczne dla tego przewodnika. W tej sekcji przedstawiono proces tworzenia konta, uzyskiwania poświadczeń, a następnie przygotowywania środowiska deweloperskiego.

Tworzenie konta

Zacznij od utworzenia interfejsu API dla konta apache Cassandra. Po utworzeniu konta utwórz przestrzeń kluczy i zasoby tabeli.

  1. Jeśli nie masz jeszcze docelowej grupy zasobów, użyj az group create polecenia , aby utworzyć nową grupę zasobów w ramach subskrypcji.

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

  2. Użyj polecenia , az cosmosdb create aby utworzyć nowe konto usługi Azure Cosmos DB dla bazy danych Apache Cassandra z ustawieniami domyślnymi.

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

  3. Utwórz nową przestrzeń kluczy za pomocą az cosmosdb cassandra keyspace create o nazwie cosmicworks.

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

  4. Utwórz nowy obiekt JSON reprezentujący schemat przy użyciu wielolinijkowego polecenia Bash. Następnie użyj az cosmosdb cassandra table create polecenia , aby utworzyć nową tabelę o nazwie 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"

Pobieranie poświadczeń

Teraz pobierz hasło biblioteki klienta do utworzenia połączenia z niedawno utworzonym kontem.

  1. Użyj az cosmosdb show polecenia , aby uzyskać punkt kontaktu i nazwę użytkownika dla konta.

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

  2. Zapisz wartości właściwości contactPoint i username z danych wyjściowych poprzednich poleceń. Wartości tych właściwości to punkt kontaktowy i nazwa użytkownika używana w dalszej części tego przewodnika w celu nawiązania połączenia z kontem z biblioteką.

  3. Użyj az cosmosdb keys list polecenia, aby pobrać klucze dla konta.

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

  4. Zanotuj wartość właściwości primaryMasterKey z danych wyjściowych wcześniejszych poleceń. Wartość tej właściwości to hasło , którego użyjesz w dalszej części tego przewodnika, aby nawiązać połączenie z kontem z biblioteką.

Przygotowywanie środowiska projektowego

Następnie skonfiguruj środowisko deweloperskie przy użyciu nowego projektu i biblioteki klienta. Ten krok jest ostatnim wymaganiem wstępnym przed przejściem do pozostałej części tego przewodnika.

  1. Rozpocznij w pustym katalogu.

  2. Wygeneruj nowy projekt konsoli Java przy użyciu narzędzia Maven.

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

  3. Zaimportuj pakiet java-driver-core z Mavena. Dodaj tę sekcję do pliku pom.xml .

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

  4. Otwórz plik /console/src/main/java/quickstart/App.java .

  5. Obserwuj istniejący szablon aplikacji Java.

    package quickstart;

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

  6. Usuń komentarze i dane wyjściowe konsoli ze szablonu. Ten blok kodu jest punktem wyjścia dla pozostałej części tego przewodnika.

    package quickstart;

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

  7. Zaimportuj java.security.NoSuchAlgorithmException przestrzeń nazw.

    import java.security.NoSuchAlgorithmException;

  8. Zaktualizuj sygnaturę main metody, aby wskazać, że może zgłosić NoSuchAlgorithmException wyjątek.

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

    Ważne

    W pozostałych krokach w tym przewodniku założono, że dodajesz kod w metodzie main .

  9. Skompiluj projekt.

    mvn compile

Model obiektów

Opis
CqlSession Reprezentuje określone połączenie z klastrem
PreparedStatement Reprezentuje wstępnie skompilowaną instrukcję CQL, która może być wykonywana wiele razy wydajnie
BoundStatement Reprezentuje przygotowane zapytanie z przypisanymi parametrami
Row Reprezentuje pojedynczy wiersz wyniku zapytania

Przykłady kodu

Uwierzytelnianie klienta

Zacznij od uwierzytelnienia klienta przy użyciu poświadczeń zebranych wcześniej w tym przewodniku.

  1. Otwórz plik /console/src/main/java/quickstart/App.java w zintegrowanym środowisku projektowym (IDE).

  2. Zaimportuj następujące 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. Utwórz zmienne tekstowe dla poświadczeń zebranych wcześniej w tym przewodniku. Nazwij zmienne username, passwordi contactPoint. Utwórz również zmienną ciągu o nazwie region dla lokalnego centrum danych.

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

  4. Utwórz kolejną zmienną typu string dla regionu, w którym utworzyłeś swoje konto Azure Cosmos DB dla Apache Cassandra. Nadaj tej zmiennej regionnazwę .

    String region = "<region>";

  5. SSLContext Utwórz obiekt, aby upewnić się, że używasz protokołu TLS (Transport Layer Security).

    SSLContext sslContext = SSLContext.getDefault();

  6. Utwórz nowy CqlSession obiekt przy użyciu zmiennych poświadczeń i konfiguracji utworzonych w poprzednich krokach. Ustaw punkt kontaktowy, lokalne centrum danych, poświadczenia uwierzytelniania, kluczową przestrzeń oraz kontekst protokołu Transport Layer Security (TLS).

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

Ostrzeżenie

Pełna weryfikacja zabezpieczeń warstwy transportu (TLS) jest wyłączona w tym przewodniku, aby uprościć uwierzytelnianie. W przypadku wdrożeń produkcyjnych w pełni włącz walidację.

Aktualizuj lub dodaj dane

Następnie dodaj nowe dane do tabeli. Upserting gwarantuje, że dane są tworzone lub zastępowane odpowiednio w zależności od tego, czy te same dane już istnieją w tabeli.

  1. Zdefiniuj nową klasę o nazwie Product z polami odpowiadającymi tabeli utworzonej wcześniej w tym przewodniku.

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

    Wskazówka

    W języku Java możesz utworzyć ten typ w innym pliku lub utworzyć go na końcu istniejącego pliku.

  2. Utwórz nowy obiekt typu Product. Zapisz obiekt w zmiennej o nazwie product.

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

  3. Utwórz nową zmienną ciągu o nazwie insertQuery z zapytaniem Języka zapytań Cassandra (CQL) w celu wstawienia nowego wiersza.

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

  4. Przygotuj zapytanie insert i zwiąż właściwości produktu jako parametry.

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

  5. Wstaw lub zaktualizuj produkt, wykonując powiązaną instrukcję.

    session.execute(boundInsert);

Odczyt danych

Następnie odczytaj dane, które zostały wcześniej dodane lub zmodyfikowane w tabeli.

  1. Utwórz nową zmienną ciągu o nazwie readQuery z zapytaniem CQL, które pasuje do elementów z tym samym id polem.

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

  2. Utwórz zmienną ciągu o nazwie id o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

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

  3. Przygotuj wyrażenie i powiąż pole id produktu jako parametr.

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

  4. Wykonaj instrukcję bound i zapisz wynik w zmiennej o nazwie readResult.

    ResultSet readResult = session.execute(boundRead);

  5. Pobierz pierwszy wiersz z zestawu wyników i, jeśli jest on odnaleziony, przypisz go do obiektu Product.

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

Wykonywanie zapytań o dane

Teraz użyj zapytania, aby znaleźć wszystkie dane zgodne z określonym filtrem w tabeli.

  1. Utwórz nową zmienną ciągu o nazwie findQuery z zapytaniem CQL, które pasuje do elementów z tym samym category polem.

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

  2. Utwórz zmienną ciągu o nazwie id o tej samej wartości co produkt utworzony wcześniej w tym przewodniku.

    String category = "gear-surf-surfboards";

  3. Przygotuj instrukcję i powiąż kategorię produktu jako parametr.

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

  4. Wykonaj instrukcję bound i zapisz wynik w zmiennej o nazwie findResults.

    ResultSet results = session.execute(boundFind);

  5. Iteruj po wynikach zapytania i przemapuj każdy wiersz na obiekt 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
}

Zamknij sesję

W języku Java musisz zamknąć sesję po zakończeniu pracy z dowolnymi zapytaniami i operacjami.

session.close();

Uruchamianie kodu

Uruchom nowo utworzoną aplikację przy użyciu terminalu w katalogu aplikacji.

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

Wskazówka

Upewnij się, że to polecenie jest uruchamiane w ścieżce /console utworzonej w tym przewodniku.

Uprzątnij zasoby

Teraz pobierz hasło biblioteki klienta do utworzenia połączenia z niedawno utworzonym kontem.

  1. Użyj az cosmosdb show polecenia , aby uzyskać punkt kontaktu i nazwę użytkownika dla konta.

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

  2. Zapisz wartości właściwości contactPoint i username z danych wyjściowych poprzednich poleceń. Wartości tych właściwości to punkt kontaktowy i nazwa użytkownika używana w dalszej części tego przewodnika w celu nawiązania połączenia z kontem z biblioteką.

  3. Użyj az cosmosdb keys list polecenia, aby pobrać klucze dla konta.

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

  4. Zanotuj wartość właściwości primaryMasterKey z danych wyjściowych wcześniejszych poleceń. Wartość tej właściwości to hasło , którego użyjesz w dalszej części tego przewodnika, aby nawiązać połączenie z kontem z biblioteką.

Następny krok

Omówienie usługi Azure Cosmos DB dla bazy danych Apache Cassandra

  • Last updated on