Azure Cosmos DB-Clientbibliothek für Java – Version 4.52.0

  • Artikel

Azure Cosmos DB ist der global verteilte Datenbankdienst von Microsoft mit mehreren Modellen für operative Workloads und Analyseworkloads. Er bietet Multimaster-Features, indem Durchsatz, Compute und Speicher automatisch skaliert werden. Dieses Projekt stellt die SDK-Bibliothek in Java für die Interaktion mit der SQL-API von Azure Cosmos DB Database Service bereit.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der GA-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
  </dependency>
</dependencies>

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu. //: # ({x-version-update-start; com.azure:azure-cosmos; current})

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos</artifactId>
  <version>4.52.0</version>
</dependency>

Weitere Informationen finden Sie unter maven central für frühere Releases.

Weitere Informationen zum Paket finden Sie unter javadocs .

Voraussetzungen

SLF4J ist nur erforderlich, wenn Sie die Protokollierung verwenden möchten. Laden Sie außerdem eine SLF4J-Bindung herunter, um die SLF4J-API mit der Protokollierungsimplementierung Ihrer Wahl zu verknüpfen. Weitere Informationen finden Sie im SLF4J-Benutzerhandbuch.

Das SDK stellt Reactor Core-basierte asynchrone APIs bereit. Weitere Informationen zu den Reaktorkern- und Flux/Mono-Typen finden Sie hier.

Authentifizieren des Clients

Um mit dem Azure Cosmos DB-Dienst zu interagieren, müssen Sie eine instance der Cosmos-Clientklasse erstellen. Um dies zu ermöglichen, benötigen Sie eine URL und einen Schlüssel des Azure Cosmos DB-Diensts.

Das SDK stellt zwei Clients bereit.

  1. CosmosAsyncClient für Vorgänge, die asynchrone APIs verwenden.
  2. CosmosClient für Vorgänge, die synchrone (blockierende) APIs verwenden.

Erstellen von CosmosAsyncClient

CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildAsyncClient();

Erstellen von CosmosClient

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildClient();

Wichtige Konzepte

Das Azure Cosmos DB Java SDK bietet clientseitige logische Darstellungen für den Zugriff auf die Azure Cosmos DB-SQL-API. Ein Cosmos DB-Konto enthält null oder mehr Datenbanken, eine Datenbank (DB) null oder mehr Container und ein Container null oder mehr Elemente. Weitere Informationen zu Datenbanken, Containern und Elementen finden Sie hier. Einige wichtige Eigenschaften, die auf Containerebene definiert sind, darunter der bereitgestellte Durchsatz und der Partitionsschlüssel.

Globale Verteilung

  • Azure Cosmos DB ist ein global verteilter Datenbankdienst, der kurze Wartezeiten, elastische Skalierbarkeit des Durchsatzes, gut definierte Semantik zum Gewährleisten der Datenkonsistenz und Hochverfügbarkeit bietet. Kurz gesagt: Wenn Ihre Anwendung auf der ganzen Welt schnelle Antwortzeiten garantieren muss, immer online sein muss und eine unbegrenzte sowie elastische Skalierbarkeit des Durchsatzes und Speichers erfordert, sollten Sie Ihre Anwendungen mit Azure Cosmos DB erstellen. Weitere Informationen zur globalen Verteilung finden Sie hier.

Durchsatzbereitstellung

  • Mit Azure Cosmos DB können Sie bereitgestellten Durchsatz für Ihre Datenbanken und Container festlegen. Es gibt zwei Arten von bereitgestelltem Durchsatz: Standard (manuell) oder automatische Skalierung. Der bereitgestellte Durchsatz kann container- oder datenbankspezifisch ausgewählt werden. In der Regel wird jedoch die containerspezifische Durchsatzangabe bevorzugt. Weitere Informationen zur Durchsatzbereitstellung finden Sie hier.

Anforderungseinheiten (RUs)

  • Azure Cosmos DB unterstützt viele APIs wie z.B. SQL, MongoDB, Cassandra, Gremlin und Tabelle. Jede API verfügt über einen eigenen Satz von Datenbankvorgängen. Diese Vorgänge reichen von einfachen Lese- und Schreibvorgängen für Datenpunkte bis hin zu komplexen Abfragen. Jeder Datenbankvorgang beansprucht je nach Komplexität eine bestimmte Menge an Systemressourcen. Die Kosten sämtlicher Datenbankvorgänge werden von Azure Cosmos DB normalisiert und in Anforderungseinheiten (Request Units, RUs) ausgedrückt. RUs pro Sekunde ist also gewissermaßen die Währung für Durchsatz. RUs pro Sekunde ist eine ratenbasierte Währung. Sie abstrahiert die Systemressourcen wie CPU, IOPS und Arbeitsspeicher, die zum Ausführen der von Azure Cosmos DB unterstützten Datenbankvorgänge erforderlich sind. Weitere Informationen zu Anforderungseinheiten finden Sie hier.

Partitionierung

  • Wenn Elemente in einen Cosmos DB-Container eingefügt werden, wird die Datenbank horizontal skaliert, indem weitere Speicher- und Computeressourcen zur Bewältigung der Anforderungen hinzugefügt werden. Speicher- und Computekapazität werden in diskreten Einheiten (Partitionen) hinzugefügt. In Ihren Dokumenten muss ein Feld als Partitionsschlüssel ausgewählt werden, durch den jedes Dokument einer Partition zugeordnet wird. Zur Verwaltung von Partitionen wird jeder Partition ein ungefähr gleicher Slice aus dem Bereich der Partitionsschlüsselwerte zugewiesen. Es empfiehlt sich daher, einen relativ zufälligen oder gleichmäßig verteilten Partitionsschlüssel zu wählen. Andernfalls fallen für einige Partitionen deutlich mehr Anforderungen an als für andere. Diese werden als heiße Partitionen bzw. kalte Partitionen bezeichnet und sollten vermieden werden. Weitere Informationen zur Partitionierung finden Sie hier.

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die einige der gängigsten Sql-API-Aufgaben von Cosmos DB behandeln, einschließlich:

Erstellen eines Cosmos-Clients

// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildAsyncClient();

// Create a new CosmosClient via the CosmosClientBuilder
CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildClient();

// Create a new CosmosClient with customizations
cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .directMode(directConnectionConfig, gatewayConnectionConfig)
    .consistencyLevel(ConsistencyLevel.SESSION)
    .connectionSharingAcrossClientsEnabled(true)
    .contentResponseOnWriteEnabled(true)
    .userAgentSuffix("my-application1-client")
    .preferredRegions(Arrays.asList("West US", "East US"))
    .buildClient();

Erstellen einer Datenbank

Mit einem der im vorherigen Beispiel erstellten Clients können Sie eine Datenbank wie folgt erstellen:

// Get a reference to the container
// This will create (or read) a database and its container.
cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .map(databaseResponse -> cosmosAsyncClient.getDatabase(databaseResponse.getProperties().getId()))
    .subscribe(database -> System.out.printf("Created database '%s'.%n", database.getId()));

Create Container

Mithilfe der oben erstellten Datenbank können Sie einen anderen Vorgang an diese ketten, um einen Container wie folgt zu erstellen:

cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .flatMap(databaseResponse -> {
        String databaseId = databaseResponse.getProperties().getId();
        return cosmosAsyncClient.getDatabase(databaseId)
            // Create Container
            .createContainerIfNotExists("<YOUR CONTAINER NAME>", "/id")
            .map(containerResponse -> cosmosAsyncClient.getDatabase(databaseId)
                .getContainer(containerResponse.getProperties().getId()));
    })
    .subscribe(container -> System.out.printf("Created container '%s' in database '%s'.%n",
        container.getId(), container.getDatabase().getId()));

CRUD-Vorgang für Elemente

// Create an item
cosmosAsyncContainer.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
    .flatMap(response -> {
        System.out.println("Created item: " + response.getItem());
        // Read that item 👓
        return cosmosAsyncContainer.readItem(response.getItem().getId(),
            new PartitionKey(response.getItem().getId()), Passenger.class);
    })
    .flatMap(response -> {
        System.out.println("Read item: " + response.getItem());
        // Replace that item 🔁
        Passenger p = response.getItem();
        p.setDestination("SFO");
        return cosmosAsyncContainer.replaceItem(p, response.getItem().getId(),
            new PartitionKey(response.getItem().getId()));
    })
    // delete that item 💣
    .flatMap(response -> cosmosAsyncContainer.deleteItem(response.getItem().getId(),
        new PartitionKey(response.getItem().getId())))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// ...

Hier finden Sie eine Erste Schritte-Beispiel-App.

Außerdem haben wir weitere Beispielbeispiele projekt.

Problembehandlung

Allgemein

Azure Cosmos DB ist eine schnelle und flexible verteilte Datenbank mit nahtloser Skalierung, garantierter Latenz und garantiertem Durchsatz. Die Skalierung Ihrer Datenbank mit Azure Cosmos DB erfordert weder aufwendige Änderungen an der Architektur noch das Schreiben von komplexem Code. Zentrales Hoch- und Herunterskalieren ist ebenso problemlos möglich wie das Aufrufen einer einzelnen API oder SDK-Methode. Da der Zugriff auf Azure Cosmos DB jedoch über Netzwerkaufrufe erfolgt, können Sie bei der Verwendung des Azure Cosmos DB Java SDK v4 clientseitige Optimierungen vornehmen, um eine optimale Leistung zu erzielen.

Aktivieren der Clientprotokollierung

Das Azure Cosmos DB Java SDK v4 verwendet SLF4j als Protokollierungsfassade, die die Anmeldung bei gängigen Protokollierungsframeworks wie log4j und logback unterstützt.

Wenn Sie beispielsweise log4j als Protokollierungsframework verwenden möchten, fügen Sie Ihrem Java-Klassenpfad die folgenden Bibliotheken hinzu:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

Fügen Sie außerdem eine log4j-Konfiguration hinzu:

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

Nächste Schritte

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe