Quickstart: Een Java-app bouwen voor het beheren van Azure Cosmos DB voor Apache Cassandra-gegevens (v4-stuurprogramma)

Artikel
03/22/2023

VAN TOEPASSING OP: Cassandra

In deze quickstart maakt u een Azure Cosmos DB voor Apache Cassandra-account en gebruikt u een Cassandra Java-app die is gekloond vanuit GitHub om een Cassandra-database en -container te maken met behulp van de v4.x Apache Cassandra-stuurprogramma's voor Java. Azure Cosmos DB is een databaseservice met meerdere modellen waarmee u snel document-, tabel-, sleutelwaarde- en grafiekdatabases kunt maken en er query's op kunt uitvoeren met globale distributie en horizontale schaalmogelijkheden.

Vereisten

Een Azure-account met een actief abonnement. Maak er gratis een. Of probeer Azure Cosmos DB gratis zonder Azure-abonnement.
Java Development Kit (JDK) 8. Verwijs uw omgevingsvariabele JAVA_HOME naar de map waarin de JDK is geïnstalleerd.
Een binair Maven-archief. Voer op Ubuntu apt-get install maven uit om Maven te installeren.
Git. Voer op Ubuntu sudo apt-get install git uit om Git te installeren.

Notitie

Dit is een eenvoudige quickstart die gebruikmaakt van versie 4 van het opensource-Apache Cassandra-stuurprogramma voor Java. In de meeste gevallen moet u een bestaande Afhankelijke Java-toepassing van Apache Cassandra kunnen verbinden met Azure Cosmos DB voor Apache Cassandra zonder dat u uw bestaande code hoeft te wijzigen. We raden u echter aan om onze aangepaste Java-extensie toe te voegen, die aangepast beleid voor opnieuw proberen en taakverdeling bevat, evenals aanbevolen verbindingsinstellingen, voor een betere algehele ervaring. Dit is voor het afhandelen van snelheidsbeperking en failover op toepassingsniveau in Azure Cosmos DB, indien nodig. U vindt hier een uitgebreid voorbeeld waarmee de extensie wordt geïmplementeerd.

Een databaseaccount maken

Voordat u een documentdatabase kunt maken, moet u een Cassandra-account maken met Azure Cosmos DB.

Selecteer vanuit het menu van Azure Portal of op de startpagina de optie Een resource maken.
Zoek op de pagina Nieuw naar Azure Cosmos DB en selecteer dit.
Selecteer op de pagina Azure Cosmos DBMaken.
Selecteer maken in de sectie Cassandra op de pagina API.

De API bepaalt het type te maken account. Azure Cosmos DB biedt vijf API's: NoSQL voor documentdatabases, Gremlin voor grafiekdatabases, MongoDB voor documentdatabases, Azure Table en Cassandra. U moet voor elke API een afzonderlijk account maken.

Selecteer Cassandra, omdat u in deze quickstart een tabel maakt die werkt met de API voor Cassandra.

Meer informatie over de API voor Cassandra.

Voer op de pagina Azure Cosmos DB-account maken de basisinstellingen voor het nieuwe Azure Cosmos DB-account in.

Instelling	Waarde	Beschrijving
Abonnement	Uw abonnement	Selecteer het Azure-abonnement dat u voor dit Azure Cosmos DB-account wilt gebruiken.
Resourcegroep	Nieuwe maken Voer vervolgens dezelfde naam in als de Accountnaam	Selecteer Nieuw maken. Voer daarna een nieuwe resourcegroepnaam in voor het account. Gebruik dezelfde naam als uw Azure Cosmos DB-accountnaam om het uzelf gemakkelijk te maken.
Accountnaam	Voer een unieke naam in	Voer een unieke naam in om uw Azure Cosmos DB-account te identificeren. Uw account-URI wordt cassandra.cosmos.azure.com dat aan uw unieke accountnaam wordt toegevoegd. De accountnaam moet tussen de 3 en 31 tekens lang zijn en mag alleen kleine letters, cijfers en afbreekstreepjes bevatten.
Locatie	De regio het dichtst bij uw gebruikers	Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
Capaciteitsmodus	Ingerichte doorvoer of serverloos	Selecteer Ingerichte doorvoer om een account te maken in de modus Ingerichte doorvoer. Selecteer Serverloos om een account te maken in de modus serverloos.
Niveaukorting op gratis laag van Azure Cosmos DB toepassen	Toepassen of niet toepassen	Met de gratis laag van Azure Cosmos DB ontvangt u de eerste 1000 RU/s en 25 GB aan opslagruimte gratis in een account. Meer informatie over de gratis laag.
Totale accountdoorvoer beperken	Selecteer om de doorvoer van het account te beperken	Dit is handig als u de totale doorvoer van het account wilt beperken tot een specifieke waarde.

Notitie

U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als u de optie voor het toepassen van de korting voor gratis lagen niet ziet, betekent dit dat er al een ander account in het abonnement is ingeschakeld met een gratis laag.

De nieuwe accountpagina voor Azure Cosmos DB voor Apache Cassandra

Configureer op het tabblad Globale distributie de volgende details. U kunt de standaardwaarden voor deze quickstart laten staan:

Instelling	Waarde	Beschrijving
Georedundantie	Uitschakelen	Schakel globale distributie voor uw account in of uit door uw regio te koppelen met een koppelingsregio. U kunt later meer regio's aan uw account toevoegen.
Schrijven voor meerdere regio's	Uitschakelen	Dankzij de mogelijkheid voor schrijfbewerkingen in meerdere regio's kunt over de hele wereld profiteren van de ingerichte doorvoer voor uw databases en containers.
Beschikbaarheidszones	Uitschakelen	Beschikbaarheidszones zijn geïsoleerde locaties binnen een Azure-regio. Elke zone bestaat uit een of meer datacenters die zijn voorzien van een onafhankelijke stroomvoorziening, koeling en netwerken.

Notitie

De volgende opties zijn niet beschikbaar als u Serverloos als Capaciteitsmodus selecteert:

Korting voor gratis lagen toepassen
Geografische redundantie
Schrijven voor meerdere regio's

Optioneel kunt u aanvullende details configureren op de volgende tabbladen:
- Netwerken : configureer de toegang vanuit een virtueel netwerk.
- Back-upbeleid : configureer periodiek of doorlopend back-upbeleid.
- Versleuteling : gebruik een door de service beheerde sleutel of een door de klant beheerde sleutel.
- Tags : tags zijn naam-waardeparen waarmee u resources kunt categoriseren en geconsolideerde facturering kunt weergeven door dezelfde tag toe te passen op meerdere resources en resourcegroepen.
Selecteer Controleren + maken.
Controleer de accountinstellingen en selecteer vervolgens Maken. Het duurt een paar minuten om het account te maken. Wacht tot de portal-pagina Uw implementatie is voltooid weergeeft.
Selecteer Ga naar resource om naar de Azure Cosmos DB-accountpagina te gaan.

De voorbeeldtoepassing klonen

Nu gaan we werken met code. We gaan een Cassandra-app klonen vanuit GitHub, de verbindingsreeks instellen en de app uitvoeren. U zult zien hoe gemakkelijk het is om op een programmatische manier met gegevens te werken.

Open een opdrachtprompt. Maak een nieuwe map met de naam git-samples. Sluit vervolgens de opdrachtprompt.
```
md "C:\git-samples"
```
Open een git-terminalvenster, bijvoorbeeld git bash, en gebruik de cd-opdracht om naar de nieuwe map te gaan voor het installeren van de voorbeeld-app.
```
cd "C:\git-samples"
```
Voer de volgende opdracht uit om de voorbeeldopslagplaats te klonen. Deze opdracht maakt een kopie van de voorbeeld-app op uw computer.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-java-getting-started-v4.git
```

De code bekijken

Deze stap is optioneel. Als u wilt weten hoe de databaseresources met de code worden gemaakt, kunt u de volgende codefragmenten bekijken. Als u deze stap wilt overslaan, kunt u verdergaan naar Uw verbindingsreeks bijwerken. Deze codefragmenten zijn allemaal afkomstig uit het bestand src/main/java/com/azure/cosmosdb/cassandra/util/CassandraUtils.java.

De CqlSession maakt verbinding met de Azure Cosmos DB voor Apache Cassandra en retourneert een sessie voor toegang (Cluster object van het v3-stuurprogramma is nu verouderd). Cassandra-host, poort, gebruikersnaam en wachtwoord worden ingesteld met behulp van de pagina Verbindingsreeks in de Azure-portal.
```
    this.session = CqlSession.builder().withSslContext(sc)
            .addContactPoint(new InetSocketAddress(cassandraHost, cassandraPort)).withLocalDatacenter(region)
            .withAuthCredentials(cassandraUsername, cassandraPassword).build();
```

De volgende codefragmenten zijn afkomstig uit het bestand src/main/java/com/azure/cosmosdb/cassandra/repository/UserRepository.java.

Verwijder de spatie als deze al bestaat uit een eerdere uitvoering.

public void dropKeyspace() {
    String query = "DROP KEYSPACE IF EXISTS "+keyspace+"";
    session.execute(query);
    LOGGER.info("dropped keyspace '"+keyspace+"'");
}

Er wordt een nieuwe keyspace gemaakt.

public void createKeyspace() {
    String query = "CREATE KEYSPACE "+keyspace+" WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 }";
    session.execute(query);
    LOGGER.info("Created keyspace '"+keyspace+"'");
}

Er wordt een nieuwe tabel gemaakt.

  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+"'");
  }

Gebruikersentiteiten worden ingevoegd met een voorbereid instructieobject.

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

Voer een query uit om alle gebruikersgegevens op te halen.

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

Voer een query uit om de gebruikersgegevens van één gebruiker op te halen.

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

Uw verbindingsreeks bijwerken

Ga nu terug naar Azure Portal om de verbindingsreeksinformatie op te halen en kopieer deze in de app. De details van de verbindingsreeks stellen uw app in staat om te communiceren met de gehoste database.

Selecteer in uw Azure Cosmos DB-account in de Azure-portal de optie Verbindingsreeks.
Gebruik de knop aan de rechterkant van het scherm om de CONTACT POINT-waarde te kopiëren.
Open het bestand config.properties vanuit de map C:\git-samples\azure-cosmosdb-cassandra-java-getting-started\java-examples\src\main\resources.
Plak de CONTACT POINT-waarde uit de portal over <Cassandra endpoint host> op regel 2 heen.

Regel 2 van config.properties moet er nu als volgt uitzien

cassandra_host=cosmos-db-quickstart.cassandra.cosmosdb.azure.com
Ga terug naar de portal en kopieer de USERNAME-waarde. Plak de USERNAME-waarde uit de portal over <cassandra endpoint username> op regel 4 heen.

Regel 4 van config.properties moet er nu als volgt uitzien

cassandra_username=cosmos-db-quickstart
Ga terug naar de portal en kopieer de PASSWORD-waarde. Plak de PASSWORD-waarde uit de portal over <cassandra endpoint password> op regel 5 heen.

Regel 5 van config.properties moet er nu als volgt uitzien

cassandra_password=2Ggkr662ifxz2Mg...==
Als u wilt dat er een specifiek TLS/SSL-certificaat wordt gebruikt, vervangt u op regel 6 <SSL key store file location> door de locatie van het TLS/SSL-certificaat. Als er geen waarde wordt opgegeven, wordt het JDK-certificaat gebruikt dat is geïnstalleerd op <JAVA_HOME>/jre/lib/security/cacerts.
Als u regel 6 hebt gewijzigd omdat u wilt dat er een specifiek TLS/SSL-certificaat wordt gebruikt, werkt u regel 7 bij, zodat het wachtwoord voor dat certificaat wordt gebruikt.
U moet de standaardregio (bijvoorbeeld West US) voor het contactpunt toevoegen, bijvoorbeeld

region=West US

Dit komt doordat via het v.4x-stuurprogramma slechts één lokale domeincontroller kan worden gekoppeld aan het contactpunt. Als u een andere regio dan de standaardregio wilt toevoegen (dit is de regio die is opgegeven toen het Azure Cosmos DB-account voor het eerst werd gemaakt), moet u het regionale achtervoegsel gebruiken bij het toevoegen van een contactpunt, bijvoorbeeld host-westus.cassandra.cosmos.azure.com.
Sla het bestand config.properties op.

De Java-app uitvoeren

cd in het git-terminalvenster naar de map azure-cosmosdb-cassandra-java-getting-started-v4.
```
cd "C:\git-samples\azure-cosmosdb-cassandra-java-getting-started-v4"
```
Gebruik in het git-terminalvenster de volgende opdracht om het bestand cosmosdb-cassandra-examples.jar te genereren.
```
mvn clean install
```
Voer in het git-terminalvenster de volgende opdracht uit om de Java-toepassing te starten.
```
java -cp target/cosmosdb-cassandra-examples.jar com.azure.cosmosdb.cassandra.examples.UserProfile
```
In het terminalvenster worden meldingen weergegeven dat de keyspace en de tabel zijn gemaakt. Vervolgens worden gebruikers in de tabel geselecteerd en geretourneerd en wordt de uitvoer weergegeven, waarna een rij per id wordt geselecteerd en de waarde wordt weergegeven.

Druk op Ctrl+C om de uitvoering van het programma te stoppen en het consolevenster te sluiten.
Open Data Explorer in de Azure-portal om deze nieuwe gegevens te bekijken, te wijzigen, een query erop uit te voeren of er iets anders mee te doen.

SLA’s bekijken in Azure Portal

De Azure Portal bewaakt de doorvoer, opslag, beschikbaarheid, latentie en consistentie van uw Azure Cosmos DB-account. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) tonen de SLA-waarde in vergelijking met de werkelijke prestaties. Deze suite van metrische gegevens zorgt voor een transparante bewaking van uw SLA's.

Metrische gegevens en SLA's weergeven:

Selecteer Metrische gegevens in het navigatiemenu van uw Azure Cosmos DB-account.
Selecteer een tabblad, bijvoorbeeld Latentie, en selecteer aan de rechterkant een tijdsbestek. Vergelijk de lijnen Werkelijk en SLA in de grafieken met elkaar.
Bekijk de metrische gegevens op de andere tabbladen.

Resources opschonen

Wanneer u uw app en Azure Cosmos DB-account niet meer nodig hebt, kunt u de Azure-resources die u hebt gemaakt, verwijderen zodat er geen kosten meer voor in rekening worden gebracht. Om de resources te verwijderen:

Zoek en selecteer Resourcegroepen in de zoekbalk op Azure Portal.
Selecteer de resourcegroep die u eerder voor deze quickstart hebt gemaakt uit de lijst.
Selecteer Resourcegroep verwijderen op de pagina Overzicht van de resourcegroep.
Selecteer in het volgende venster de naam van de resourcegroep die u wilt verwijderen en selecteer vervolgens Verwijderen.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB-account maakt met API voor Cassandra en hoe u een Cassandra Java-app uitvoert waarmee een Cassandra-database en -container wordt gemaakt. Nu kunt u aanvullende gegevens in uw Azure Cosmos DB-account importeren.

Cassandra-gegevens importeren in Azure Cosmos DB

Quickstart: Een Java-app bouwen voor het beheren van Azure Cosmos DB voor Apache Cassandra-gegevens (v4-stuurprogramma)

Vereisten

Een databaseaccount maken

De voorbeeldtoepassing klonen

De code bekijken

Uw verbindingsreeks bijwerken

De Java-app uitvoeren

SLA’s bekijken in Azure Portal

Resources opschonen

Volgende stappen

Aanvullende resources