Entwicklerhandbuch für Azure Cosmos DB

Azure Spring Data für Azure Cosmos DB bietet Spring Data-Unterstützung für Azure Cosmos DB für NoSQL. Azure Cosmos DB ist ein global verteilter Datenbankdienst, mit dem Entwickler mit verschiedenen Standard-APIs wie SQL, MongoDB, Cassandra, Graph und Table arbeiten können.

Dieser Leitfaden führt Sie durch die Konzepte von Azure Spring Data Azure Cosmos DB SDK, unterstützte Features, Problembehandlung und bekannte Probleme. Weitere Informationen zu den folgenden Konzepten und Codebeispielen finden Sie in der Spring Data for Azure Cosmos DB SDK readme.

Versionsunterstützungsrichtlinie

Versionenunterstützung für Spring Boot

Dieses Projekt unterstützt mehrere Spring Boot-Versionen. Weitere Informationen finden Sie unter Spring Boot Support Policy. Maven-Benutzer können vom spring-boot-starter-parent Projekt erben, um einen Abschnitt für abhängigkeitsverwaltung zu erhalten, damit Spring die Versionen für Abhängigkeiten verwalten kann. Weitere Informationen finden Sie unter Spring Boot Version Support.

Versionsunterstützung für Spring Data

Dieses Projekt unterstützt verschiedene Spring Data Commons-Versionen. Weitere Informationen finden Sie unter Spring Data Version Support.

Welche Version von Azure Spring Data Azure Cosmos DB verwendet werden soll

Die Azure Spring Data Azure Cosmos DB-Bibliothek unterstützt mehrere Versionen von Spring Boot / Spring Cloud. Weitere Informationen dazu, welche Version von Azure Spring Data Azure Cosmos DB mit Spring Boot / Spring Cloud-Version verwendet werden soll, finden Sie unter Welche Version von Azure Spring Data für Azure Cosmos DB sollte ich verwenden?.

Loslegen

Einschließen des Pakets

Wenn Sie Maven verwenden, fügen Sie die folgende Abhängigkeit hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher.
• Ein aktives Azure-Konto. Wenn Sie kein Konto haben, können Sie sich für ein kostenloses Kontoregistrieren. Alternativ können Sie den Azure Cosmos DB Emulator für Entwicklung und Tests verwenden. Da das HTTPS-Zertifikat des Emulators selbstsigniert ist, müssen Sie das Zertifikat in den vertrauenswürdigen Zertifikatspeicher von Java importieren, wie in hier erklärt.
• (Optional) SLF4J ist eine Protokollierungsfassade.
• (Optional) Die SLF4J-Bindung wird verwendet, um ein bestimmtes Protokollierungsframework mit SLF4J zu verknüpfen.
• (Optional) Maven

SLF4J ist nur erforderlich, wenn Sie die Protokollierung verwenden möchten, laden Sie auch eine SLF4J-Bindung herunter, die die SLF4J-API mit der Protokollierungsimplementierung Ihrer Wahl verknüpft. Weitere Informationen finden Sie im SLF4J-Benutzerhandbuch.

Einrichten und Anpassen der Konfigurationsklasse

Um die Konfigurationsklasse einzurichten, müssen Sie AbstractCosmosConfigurationerweitern. Weitere Informationen finden Sie unter Einrichten der Konfigurationsklasse.

Sie können das zugrunde liegende CosmosAsyncClient, das vom Azure Spring Data Azure Cosmos DB SDK verwendet wird, anpassen, indem Sie DirectConnectionConfig oder GatewayConnectionConfig oder beide angeben und diese an CosmosClientBuilderübergeben. Ein vollständiges Beispiel finden Sie unter Anpassen des Konfigurationsabschnitts.

Einrichtung der Entität

Sie können eine einfache Entität als Element in Azure Cosmos DB definieren. Sie können Entitäten definieren, indem Sie die @Container Anmerkung hinzufügen und Eigenschaften für den Container angeben. Weitere Informationen finden Sie unter Definieren einer Entität.

Die Containeranmerkung unterstützt die Angabe von Containernamen, Anforderungseinheiten (Request Units, RUs), Gültigkeitsdauer, Erstellen von Containern mit Autoskalierung des Durchsatzes, Unterstützung geschachtelter Partitionsschlüssel und anderen Containereigenschaften.

Einrichtung des Repositorys

Azure Spring Data Azure Cosmos DB unterstützt ReactiveCrudRepository (asynchrone APIs) und CrudRepository (Synchronisierungs-APIs), die die folgenden grundlegenden CRUD-Funktionen bereitstellen:

• Speichern
• findAll
• findOne (nach ID)
• Alle löschen
• delete (nach ID)
• Entität löschen

Sie können CosmosRepository (für die Synchronisierungs-API-Unterstützung) oder ReactiveCosmosRepository (für die asynchrone API-Unterstützung) erweitern, um Spring Data-Repositorys für Ihre Anwendung einzurichten. Weitere Informationen finden Sie unter Erstellen von Repositorys.

Azure Spring Data Azure Cosmos DB unterstützt die Angabe von kommentierten Abfragen in den Repositorys mithilfe von @Query. Weitere Informationen finden Sie unter QueryAnnotation: Verwenden von kommentierten Abfragen in Repositorys.

Spring Data Anmerkungen

Spring Data-@Id-Anmerkung

Es gibt mehrere Möglichkeiten, ein Feld in der Domänenklasse idzuzuordnen. Weitere Informationen finden Sie im Codeabschnitt zur Spring Data-ID-Anmerkung.

Automatische ID-Generierung

Azure Spring Data Azure Cosmos DB unterstützt die automatische Generierung von IDs mithilfe der @GeneratedValue Anmerkung. Weitere Informationen finden Sie im Abschnitt zur automatischen ID-Generierung.

SpEL-Ausdruck und benutzerdefinierter Containername

Standardmäßig ist der Containername der Klassenname der Benutzerdomänenklasse. Zum Anpassen fügen Sie der Domänenklasse die @Container(containerName="myCustomContainerName") Anmerkung hinzu. Weitere Informationen finden Sie im Abschnitt SpEL-Ausdruck und benutzerdefinierter Containername.

Benutzerdefinierte Indexierungsrichtlinie

Standardmäßig wird IndexingPolicy vom Azure-Dienst festgelegt. Zum Anpassen fügen Sie der Domänenklasse die Anmerkung @CosmosIndexingPolicy hinzu. Weitere Informationen finden Sie im Abschnitt zur Indizierungsrichtlinie.

Eindeutige Schlüsselrichtlinie

Azure Spring Data Azure Cosmos DB unterstützt das Festlegen UniqueKeyPolicy für den Container, indem der Domänenklasse die Anmerkung @CosmosUniqueKeyPolicy hinzugefügt wird. Weitere Informationen finden Sie im Abschnitt Richtlinie für eindeutige Schlüssel.

Azure Cosmos DB-Partition

Azure-spring-data-cosmos unterstützt Azure Cosmos DB-Partitionen.

Wenn Sie ein Feld der Domänenklasse als Partitionsschlüsselfeld angeben möchten, kommentieren Sie es einfach mit @PartitionKey.

Wenn Sie CRUD-Vorgänge ausführen, geben Sie den Partitionswert an.

Weitere Informationen finden Sie im Abschnitt hier testen.

Optimistische Sperre

Azure-spring-data-cosmos unterstützt das Optimistic Locking für bestimmte Container, was bedeutet, dass Aktualisierungen/Löschungen pro Element mit einer Ausnahme fehlschlagen, falls das Element in der Zwischenzeit von einem anderen Prozess geändert worden ist. Weitere Informationen finden Sie im Abschnitt zu optimistischen Sperren.

Benutzerdefinierte Spring Data-Abfrage, Paginierung und Sortierung

Azure-spring-data-cosmos unterstützt benutzerdefinierte Spring Data-Abfragen, z. B. einen Suchvorgang wie findByAFieldAndBField. Unterstützt werden auch Paginierung, Slice und Sortierung für Spring Data. Weitere Informationen finden Sie im Abschnitt zu Abfrage, Paginierung und Sortierung.

Verwenden des Azure Cosmos DB Java SDK über Spring Data Cosmos

Azure-spring-data-cosmos unterstützt die Verwendung von Azure Cosmos DB Java SDK. Benutzer können CosmosClient oder CosmosAsyncClient Bean über ApplicationContext abrufen und alle Vorgänge ausführen, die von Azure Cosmos DB Java SDK unterstützt werden. Weitere Informationen finden Sie im Abschnitt zur Verwendung des Azure Cosmos-Clients mit Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos unterstützt Spring Data REST. Weitere Informationen finden Sie im Abschnitt Azure Spring Data Azure Cosmos DB REST API.

Rechnungsprüfung

Azure-spring-data-cosmos unterstützt Auditfelder in Datenbankentitäten mithilfe standardmäßiger spring-data-Annotationen. Weitere Informationen finden Sie im Abschnitt Spring Data Azure Cosmos DB-Überwachung.

Konfiguration mit mehreren Datenbanken

Azure-spring-data-cosmos unterstützt die Konfiguration mehrerer Datenbanken, einschließlich "mehrere Datenbankkonten" und "einzelnes Konto, mit mehreren Datenbanken". Einen vollständigen Codeausschnitt finden Sie im Abschnitt Konfiguration mit mehreren Datenbanken.

Fehlerbehebung

Allgemein

Wenn Sie einen Fehler entdecken, melden Sie das Problem hier.

Um ein neues Feature oder änderungen vorzuschlagen, die vorgenommen werden könnten, geben Sie ein Problem auf die gleiche Weise wie bei einem Fehler an.

Aktivieren der Clientprotokollierung

Azure-spring-data-cosmos verwendet SLF4j als Protokollierungsfassade, die die Anmeldung bei beliebten Protokollierungsframeworks wie Log4j und Logback unterstützt. Weitere Informationen finden Sie im Abschnitt zum Aktivieren der Clientprotokollierung.

Beispiele

Ein vollständiges Beispielprojekt finden Sie im Beispielprojekt.

Konten mit mehreren Datenbanken

Ein vollständiges Beispielprojekt finden Sie im Multidatenbank-Beispielprojekt.

Einzelnes Konto mit mehrstufiger Datenbank

Ein vollständiges Beispielprojekt finden Sie im Einzelkonto mit Mehrdatenbank-Beispielprojekt.

Nächste Schritte

• Erfahren Sie mehr über Azure Spring Data Azure Cosmos DB.
• Weitere Informationen zu Azure Cosmos DB Service
• Sehen Sie sich die Azure Spring Data Azure Cosmos DB-Beispiele
• Sehen Sie sich das Spring MVC-Beispiel mit Azure Cosmos DB an

Contributing

Dieses Projekt begrüßt Beiträge und Vorschläge. 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 ü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). Folgen Sie einfach den Anweisungen des Bots. Dieser Vorgang muss nur einmal für alle Repositorys mit unserem CLA ausgeführt werden.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie im Code of Conduct FAQ oder wenden Sie sich an opencode@microsoft.com mit anderen Fragen oder Kommentaren.