Entwicklerleitfaden zu 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 mithilfe verschiedener Standard-APIs wie SQL, MongoDB, Cassandra, Graph und Table mit Daten 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 Infodatei "Spring Data for Azure Cosmos DB SDK".

Richtlinie zur Versionsunterstützung

Versionsunterstü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 mittels Vererbung aus dem Projekt spring-boot-starter-parent einen Abschnitt zur Abhängigkeitsverwaltung beziehen, um Spring die Versionsverwaltung für Abhängigkeiten zu überlassen. 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 und 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?.

Erste Schritte

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 keines besitzen, können Sie sich für ein kostenloses Kontoregistrieren. Zu Entwicklungs- und Testzwecken können Sie alternativ den Azure Cosmos DB-Emulator verwenden. Da das HTTPS-Zertifikat des Emulators selbstsigniert ist, müssen Sie es in den Speicher der vertrauenswürdigen Zertifikate für Java importieren. Eine entsprechende Anleitung finden Sie hier.
• (Optional) SLF4J ist eine Protokollierungsfassade.
• (Optional) Die SLF4J-Bindung wird verwendet, um SLF4J ein bestimmtes Protokollierungsframework zuzuordnen.
• (Optional) Maven

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.

Einrichten und Anpassen der Konfigurationsklasse

Um die Konfigurationsklasse einzurichten, müssen Sie erweitern AbstractCosmosConfiguration. Weitere Informationen finden Sie unter Setup Configuration Class.

Sie können die zugrunde liegende, CosmosAsyncClient von Azure Spring Data Azure Cosmos DB SDK verwendete Anpassung anpassen, indem Sie sie bereitstellen DirectConnectionConfig oder GatewayConnectionConfig beides bereitstellen und diese bereitstellen CosmosClientBuilder. Ein vollständiges Beispiel finden Sie im Abschnitt zum Anpassen der Konfiguration.

Entitätssetup

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.

Containeranmerkung unterstützt die Angabe des Containernamens, anforderungseinheiten (RUs), Zeit zum Leben, Erstellen von Containern mit Autoskalendurchsatz, unterstützung geschachtelter Partitionsschlüssel und andere Containereigenschaften.

Repositorysetup

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

• save
• findAll
• findOne (nach ID)
• deleteAll
• delete (nach ID)
• delete (Entität)

Sie können (für die Synchronisierungs-API-Unterstützung) oder ReactiveCosmosRepository (für die asynchrone API-Unterstützung) erweitern CosmosRepository , 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 do Standard Klasse zuzuordnenid. Weitere Informationen finden Sie im Codeabschnitt der Federdaten-ID.

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 Benutzer do Standard Klasse. Fügen Sie zum Anpassen die @Container(containerName="myCustomContainerName") Anmerkung zur Do Standard klasse hinzu. Weitere Informationen finden Sie im Abschnitt "SpEL-Ausdruck und benutzerdefinierter Containername".

Benutzerdefinierte IndexingPolicy

Standardmäßig IndexingPolicy wird der Azure-Dienst festgelegt. Fügen Sie zum Anpassen die Anmerkung @CosmosIndexingPolicy zur Do Standard klasse hinzu. Weitere Informationen finden Sie im Abschnitt " Indizierungsrichtlinie".

Eindeutige Schlüsselrichtlinie

Azure Spring Data Azure Cosmos DB unterstützt die Einstellung UniqueKeyPolicy für den Container, indem die Anmerkung @CosmosUniqueKeyPolicy zur Do Standard Klasse hinzugefügt wird. Weitere Informationen finden Sie im Abschnitt "Eindeutige Schlüsselrichtlinie".

Azure Cosmos DB-Partition

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

Wenn Sie ein Feld der Do Standard Klasse als Partitionsschlüsselfeld angeben möchten, kommentieren Sie es einfach mit @PartitionKey.

Geben Sie beim Ausführen eines CRUD-Vorgangs Ihren Partitionswert an.

Weitere Informationen finden Sie im Abschnitt "Test hier".

Optimistische Sperre

Azure-spring-data-cosmos unterstützt die optimistische Sperre für bestimmte Container, was bedeutet, dass Upserts/Löschungen nach Element mit einer Ausnahme fehlschlagen, falls das Element in der Zwischenzeit von einem anderen Prozess geändert wird. Weitere Informationen finden Sie im Abschnitt "Optimistische Sperrung".

Benutzerdefinierte Spring Data-Abfrage, Paginierung und Sortierung

Azure-spring-data-cosmos unterstützt benutzerdefinierte Spring Data-Abfragen, z. B. einen Suchvorgang wie findByAFieldAndBFieldz. B. . Es unterstützt auch Spring Data Pageable, Slice und Sort. Weitere Informationen finden Sie im Abschnitt "Abfrage", "seitenfähig" und "Sortieren".

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 alle Vorgänge abrufen CosmosClient oder CosmosAsyncClient ApplicationContext durchlaufen und ausführen, die von Azure Cosmos DB Java SDK unterstützt werden. Weitere Informationen finden Sie im Abschnitt "Verwenden des Azure Cosmos-Clients über Spring Data Cosmos".

Federdaten-REST

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

Überwachung

Azure-spring-data-cosmos unterstützt Überwachungsfelder für Datenbankentitäten mithilfe standardmäßiger Federdatenanmerkungen. Weitere Informationen finden Sie im Abschnitt "Spring Data Azure Cosmos DB audit".

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".

Problembehandlung

Allgemein

Wenn ein Fehler auftritt, führen Sie hier ein Problem aus.

Wenn Sie ein neues Feature oder Änderungen vorschlagen möchten, die vorgenommen werden könnten, melden Sie ein Problem auf die gleiche Weise wie bei einem Fehler.

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 "Clientprotokollierung aktivieren".

Beispiele

Ein vollständiges Beispielprojekt finden Sie im Beispielprojekt.

Konten mit mehreren Datenbanken

Ein vollständiges Beispielprojekt finden Sie im Beispielprojekt mit mehreren Datenbanken.

Einzelnes Konto mit mehreren Datenbanken

Ein vollständiges Beispielprojekt finden Sie im Beispielprojekt "Einzelkonto mit mehreren Datenbanken".For a complete sample project, see the Single account with Multi-database sample project.

Nächste Schritte

• Weitere Informationen zu Azure Spring-Daten in Azure Cosmos DB.
• Weitere Informationen zu Azure Cosmos DB Service
• Sehen Sie sich die Azure Spring Data Azure Cosmos DB-Beispiele an
• Sehen Sie sich das Spring MVC mit Azure Cosmos DB-Beispiel an

Contributing

This project welcomes contributions and suggestions. 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 eine Pull-Anforderung einreichen, bestimmt ein CLA-Bot automatisch, ob Sie eine CLA bereitstellen und die PR entsprechend dekorieren müssen (z. B. Bezeichnung, Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Reposs mithilfe unserer CLA tun.

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.