Übung: Einrichten Ihrer Java-App mithilfe von Maven

15 Minuten

In dieser Einheit erstellen Sie eine einfache Konsolen-App, indem Sie eine IDE Ihrer Wahl verwenden, um Code zu bearbeiten. Optional können Sie ein Terminal Ihrer Wahl verwenden, um den Code auszuführen.

Erstellen von Azure Cosmos DB-Ressourcen

Zum Abschließen dieses Labs stellt Microsoft Learn eine kostenlose Azure-Sandbox bereit, in der Sie Konten und Ressourcen erstellen können. Sie richten ein Azure Cosmos DB-Konto in diesem Abonnement ein, dann erstellen Sie eine Datenbank und einen Container.

Melden Sie sich beim Azure-Portal mit dem Konto an, über das Sie die Sandbox aktiviert haben.
Erstellen Sie mithilfe des Azure-Portals ein Azure Cosmos DB-Konto mit einem Namen Ihrer Wahl. Wenn Sie eine Ressourcengruppe für Ihr Konto auswählen können, suchen Sie nach der Ressourcengruppe [Sandbox-Ressourcengruppe], und klicken Sie darauf.
Erstellen Sie in Ihrem Azure Cosmos DB-Konto eine Datenbank namens Users.
Erstellen Sie in der Datenbank Benutzer einen Container namens WebCustomers mit dem Partitionsschlüssel /userId. Stellen Sie 400 Ru/s für WebCustomers bereit.

Erstellen eines Arbeitsverzeichnisses

Wir stellen eine Vorlage für Ihre Java-Anwendung zur Verfügung. Klonen Sie das Vorlagenrepository in Ihr System.
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Öffnen Sie Windows-Explorer, und navigieren Sie zum geklonten Repository. Öffnen Sie das Unterverzeichnis java_lab.

Wichtig

Ihre gesamte Arbeit im Rahmen dieses Moduls wird im Unterverzeichnis java_lab gespeichert.
Die Vorlage enthält eine Maven-Datei pom.xml, die die für Ihr Projekt erforderlichen Abhängigkeiten bereits abruft. Öffnen Sie diese Datei, und suchen Sie darin nach der folgenden Abhängigkeit:
```
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>LATEST</version>
</dependency>
```
Diese Abhängigkeit ruft die neueste Version des Java SDK in Azure Cosmos DB ab. Sie können diese Datei schließen.
Als nächsten Schritt erstellen Sie eine App „Hello World“ und führen sie aus. Öffnen Sie mithilfe Ihrer IDE oder des Terminals dieses Projekt. Je nach verwendeter IDE gibt es ggf. eine Option, die Datei pom.xml im Unterverzeichnis java als Projekt zu öffnen.

Nachdem das Projekt geöffnet wurde, navigieren Sie zu src/main/java/com/azure/cosmos/examples/mslearnbasicapp und öffnen CosmosApp.java. Dabei handelt es sich um eine Vorlage für die Java-Anwendung, die hier entwickelt werden soll. Der Bericht könnte beispielsweise wie folgt aussehen:
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}
```
Aktuell implementiert der Anwendungscode eine einfache „Hello World“-Anwendung.
Wenn Ihre IDE Tools zum Erstellen und Ausführen ihrer Maven-Anwendung bietet: Erstellen Sie die Anwendung mithilfe der IDE, und führen Sie sie aus. Vergewissern Sie sich, dass die Anwendung Hello World im Terminal protokolliert.
Wenn Sie das Terminal zum Erstellen und Ausführen Ihrer Maven-Anwendung verwenden: Verwenden Sie den folgenden Befehl, um die das Maven-Projekt zu erstellen:
```
mvn clean package
```
Führen Sie dann Folgendes aus:
```
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Vergewissern Sie sich, dass die Anwendung die folgende Ausgabe im Terminal protokolliert:
```
INFO: Hello World.
```

Herstellen einer Verbindung zwischen der App und Azure Cosmos DB

Erstellen Sie innerhalb der CosmosApp-Klasse die folgenden statischen Klassenvariablen als Details für Ihre Azure Cosmos DB-Verbindung:

/** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

Navigieren Sie erneut zum Azure-Portal, navigieren Sie zum Bereich Schlüssel, und kopieren Sie Ihren Azure Cosmos DB-Endpunkt-URI und den Primärschlüssel, und fügen Sie die entsprechenden Werte in die Variablendefinitionen oben ein.

Wenn Ihr URI beispielsweise https://cosmosacct.documents.azure.com:443/ lautet, sähe die neue Variablenzuweisung wie folgt aus: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Wenn Ihr Primärschlüssel elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== lautet, sähe die neue Variablenzuweisung wie folgt aus: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Erstellen der CosmosAsyncClient-Instanz

Jetzt ist es an der Zeit, eine Instanz von CosmosAsyncClient zu erstellen. Dies ist die clientseitige Darstellung des Azure Cosmos DB-Diensts. Mit diesem Client werden Anforderungen für den Dienst konfiguriert und ausgeführt.

Fügen Sie in CosmosApp.java die folgende statische Variablendeklaration der CosmosApp-Klasse hinzu:
```
/** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;
```
Höchstwahrscheinlich wurden die Klassen client, database und container noch nicht in die Java-Datei importiert. Es ist also ein guter Zeitpunkt, sich jetzt darum zu kümmern. Einige IDEs ermöglichen es Ihnen ggf., geeignete Abhängigkeiten basierend auf dem von Ihnen eingegebenen Code automatisch zu importieren. Im Allgemeinen sollten Sie davon ausgehen, dass Sie einige import-Anweisungen hinzufügen müssen, wenn Sie von uns einen Codeblock zum Einfügen erhalten, damit dieser ordnungsgemäß funktioniert.
Erstellen Sie eine private void-Methode namens basicOperations ohne Argumente in der Klasse.

Fügen Sie den folgenden Code hinzu, um in der basicOperations-Methode eine CosmosAsyncClient-Instanz zu erstellen, und schließen Sie Code ein, um zu überprüfen, ob die Datenbank Users vorhanden ist.

 client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

Nun enthält Ihre basicOperations-Methode den Code, um mit Azure Cosmos DB interagieren zu können. Diese Methode wird jedoch nicht in main aufgerufen, sodass unsere Anwendung weiterhin zum Drucken von „Hello World“ dient. Erstellen Sie zum Überprüfen CosmosApp.java in der IDE, und führen Sie es aus, oder führen Sie das Programm im Terminal aus, indem Sie Folgendes verwenden:
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Vergewissern Sie sich, dass die App noch immer die folgende Ausgabe im Terminal protokolliert:
```
INFO: Hello World.
```

Kopieren Sie den folgenden Code, und fügen Sie ihn in die main-Methode ein. Überschreiben Sie hierbei die aktuelle logger.info("Hello World.");-Zeile.

try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

Dadurch wird der Azure Cosmos DB-Code in Ihrer Anwendung ausgelöst.

Erstellen Sie CosmosApp.java in der IDE, und führen Sie das Programm aus, oder führen Sie das Programm im Terminal wie folgt aus:
```
mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"  
```
Möglicherweise wird eine große Anzahl von Protokollmeldungen im Terminal angezeigt. Einige dieser Meldungen werden vom SDK selbst generiert. Sehen Sie sich die Meldungen an, und überprüfen Sie, ob die App die folgende Ausgabe im Terminal protokolliert:
```
INFO: Database and container validation complete
```

In dieser Lerneinheit haben Sie das Fundament für Ihre Azure Cosmos DB-Java-Anwendung gelegt. Sie haben Ihre Maven-Anwendung eingerichtet, ein einfaches „Hallo Welt“-Projekt erstellt und es so erweitert, dass das Projekt mit dem Azure Cosmos DB-Endpunkt verbunden wurde.

Es steht eine Vorlage für Ihre Java-Anwendung zur Verfügung. Klonen Sie das Vorlagenrepository in Ihr System.
```
git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git
```
Öffnen Sie Windows Explorer, und navigieren Sie zum geklonten Repository. Öffnen Sie das Unterverzeichnis spring_lab.

Wichtig

Ihre gesamte Arbeit im Rahmen dieses Moduls wird im Unterverzeichnis spring_lab gespeichert.
Die Vorlage enthält eine pom.xml-Maven-Datei, die die für Ihr Projekt erforderlichen Abhängigkeiten bereits abruft. Öffnen Sie diese Datei, und suchen Sie darin nach untenstehender Abhängigkeit:
```
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>LATEST</version>
</dependency>
```
Diese Abhängigkeit ruft die neueste Version von Spring Data Azure Cosmos DB ab. Sie können diese Datei schließen.

Herstellen einer Verbindung zwischen der App und Azure Cosmos DB

Öffnen Sie mithilfe Ihrer IDE oder des Terminals dieses Projekt. Je nach verwendeter IDE gibt es ggf. eine Option, die Datei pom.xml im Unterverzeichnis spring als Projekt zu öffnen. Navigieren Sie nach dem Öffnen des Projekts mithilfe eines Datei-Explorer-Tools zu src/main/resources/. Dort sollten Sie eine Datei namens application.properties.rename sehen. In Spring Data wird Konfigurationsdateien der Vorzug vor hartcodierten Konfigurationsparametern gegeben. Um die Konfigurationsdatei für Ihr Spring Data-Projekt zu erstellen, kopieren Sie application.properties.rename in application.properties und öffnen die neue application.properties-Datei. Folgendes sollte angezeigt werden:
```
cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true
```
Sie werden ${ACCOUNT_HOST} und ${ACCOUNT_KEY} mithilfe einer Methode Ihrer Wahl auffüllen: durch Kopieren und Einfügen der Werte in application.properties oder durch Definieren dieser Umgebungsvariablen in Ihrer IDE. Im nächsten Schritt erhalten Sie die Werte, die diese Variablen aufweisen sollten.
Kehren Sie zum Azure-Portal zurück, navigieren Sie zum Bereich Schlüssel, und kopieren Sie den URI und den Primärschlüssel Ihres Azure Cosmos DB-Endpunkts. Wie bereits im vorherigen Schritt erläutert, verwenden Sie die Methode Ihrer Wahl, um den URI und den Primärschlüssel Ihres Azure Cosmos DB-Endpunkts den oben genannten Variablen zuzuweisen.

Wenn Ihr URI beispielsweise https://cosmosacct.documents.azure.com:443/ lautet und Sie den Endpunkt und den Primärschlüssel in application.properties einfügen möchten, sieht die Zeile in application.properties anschließend so aus: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Wenn Ihr Primärschlüssel elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ== lautet, sieht bei Verwendung derselben Methode die neue Variablenzuweisung wie folgt aus: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Konfigurieren des Azure Cosmos DB-Clients

Spring Data Azure Cosmos DB instanziiert den Azure Cosmos DB-Client beim Start automatisch. Der Azure Cosmos DB-Client ist die clientseitige Darstellung des Azure Cosmos DB-Diensts und wird zum Ausführen von Anforderungen an den Dienst verwendet. Ihr Code kann den Azure Cosmos DB-Client konfigurieren, bevor er instanziiert wird. Dazu verwendet der Code eine Reihe von Generator-Methoden sowie Eigenschaften, die aus application.properties abgerufen werden.

Öffnen Sie CosmosProperties.java. Wir haben diese Datei bereits vollständig bereitgestellt. Sehen Sie sich daher einfach den Inhalt an.
```
@ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}
```
Beachten Sie die Klassenmember uri, key, secondaryKey, queryMetricsEnabled. Bei einem Blick in application.properties werden Sie feststellen, dass die Namen der CosmosProperties-Member den Eigenschaftsnamen von „application.properties“ sehr ähnlich sind. Die CosmosProperties-Klasse stellt Getter und Setter bereit, damit der Rest Ihrer Anwendung von application.properties auf Konfigurationseinstellungen zugreifen kann. Beachten Sie, dass kein Code zum Pullen der Konfiguration aus application.properties vorhanden ist. Spring Datei kennt die Struktur dieser Datei und legt die Membervariablen nach dem Analysieren der Konfigurationsdatei automatisch fest.

Wir werden zu einem späteren Zeitpunkt von diesem Setup profitieren, wenn wir den Azure Cosmos DB-Client konfigurieren.
Sehen Sie sich in CosmosSampleConfiguration.java die CosmosSampleConfiguration-Klasse an, und suchen Sie die leere cosmosClientBuilder-Method:
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}
```
Beim Start ruft Spring Data automatisch diese Methode auf, ruft den von dieser Methode zurückgegebenen CosmosClientBuilder ab und ruft dessen build()-Methode auf. An diesem Punkt wird (hinter den Kulissen) eine CosmosAsyncClient-Instanz erstellt, die auf den Konfigurationseinstellungen im CosmosClientBuilder basiert. Sie können diese Methode verwenden, um den CosmosClientBuilder mithilfe von Generator-Methoden zu konfigurieren.
Beachten Sie, dass wir die Konstruktorinjektion verwenden (anstelle der Feldinjektion mit @Autowired)), um die Variable properties zu instanziieren und die Membervariablen mit analysierten Werten aus der Konfigurationsdatei aufzufüllen. Dadurch wird sichergestellt, dass alle erforderlichen Abhängigkeiten vorhanden sind, wenn die Instanz dieser Klasse erstellt wird, und das Schreiben von Testcode wird in Zukunft erleichtert.
```
//use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}
```
Wir können properties verwenden, um die Werte für uri und key für unser Azure Cosmos DB-Konto abzurufen und cosmosClientBuilder wie unten gezeigt zu implementieren:
```
@Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}
```
Diese Implementierung führt Folgendes aus:
1. Sie ruft uri und key aus properties ab.
2. Sie fügt diese in die Generator-Methoden endpoint und key ein.
3. Sie konfiguriert zusätzlich die Netzwerkverbindung mit dem Azure Cosmos DB-Dienst. (Im direkten Modus kommuniziert Ihre Clientanwendung direkt mit den Azure Cosmos DB-Partitionen im Back-End.)
Kehren Sie zu CosmosSampleConfiguration.java zurück, und suchen Sie die getDatabaseName-Methode:
```
@Override
protected String getDatabaseName() { return ""; }
```
Ändern Sie den standardmäßigen Rückgabewert in "Users", den Namen Ihrer Datenbank. Auf diese Weise stellt Spring Data bei der automatischen Verbindungsherstellung mit Azure Cosmos DB beim Start eine Verbindung mit der Datenbank *Users her.
Navigieren Sie zu WebCustomer.java. Sie werden feststellen, dass der WebCustomer-Klasse eine @Container-Anmerkung vorangestellt ist:
```
@Container(containerName = "", ru = "")
```
@Container akzeptiert zwei Argumente:
- containerName: Der Name des Azure Cosmos DB-Containers (WebCustomers).
- ru: Der bereitgestellte Durchsatz im Container. 400 RU/s ist ein guter Standardwert für eine Microsoft Learn-Übung.
Passen Sie @Container an Ihren Anwendungsfall an, wie im Folgenden gezeigt:
```
@Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {
```

Jetzt ist Ihr Spring Data-Projekt für die Interaktion mit Azure Cosmos DB eingerichtet. Als nächsten Schritt erstellen Sie eine App „Hello World“ und führen sie aus. Navigieren Sie zu src/main/java/com/azure/cosmos/examples/springexamples. Öffnen Sie dort CosmosSample.java, eine Vorlage für die Spring Data-Anwendung, die wir in diesem Modul entwickeln. Der Bericht könnte beispielsweise wie folgt aussehen:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

Aktuell implementiert der Anwendungscode eine einfache „Hello World“-Anwendung.

Wenn Ihre IDE Tools zum Erstellen und Ausführen ihrer Maven-Anwendung bietet: Erstellen Sie die Anwendung mithilfe der IDE, und führen Sie sie aus. Vergewissern Sie sich, dass die Anwendung Hello World im Terminal protokolliert.
Wenn Sie das Terminal zum Erstellen und Ausführen Ihrer Maven-Anwendung verwenden: Verwenden Sie den folgenden Befehl, um die das Maven-Projekt zu erstellen:
```
mvn clean package
```
Führen Sie dann Folgendes aus:
```
mvn spring-boot:run
```
Vergewissern Sie sich, dass die Anwendung neben anderen Informationen die folgende Ausgabe im Terminal protokolliert:
```
INFO: Hello World.
```

In dieser Lerneinheit haben Sie das Fundament für Ihre Azure Cosmos DB-Java-Anwendung gelegt. Sie haben die Maven-Anwendung angepasst und ein einfaches „Hello World“-Projekt so erweitert, dass eine Verbindung mit einem Azure Cosmos DB-Endpunkt hergestellt werden kann.

Übung: Einrichten Ihrer Java-App mithilfe von Maven

Erstellen von Azure Cosmos DB-Ressourcen

Erstellen eines Arbeitsverzeichnisses

Herstellen einer Verbindung zwischen der App und Azure Cosmos DB

Erstellen der CosmosAsyncClient-Instanz

Herstellen einer Verbindung zwischen der App und Azure Cosmos DB

Konfigurieren des Azure Cosmos DB-Clients

Feedback