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 mithilfe verschiedener Standard-APIs wie SQL, MongoDB, Cassandra, Graph und Table mit Daten arbeiten können.

In diesem Handbuch werden die Konzepte Azure Spring Data Azure Cosmos DB SDK, unterstützte Features, Problembehandlung und bekannte Probleme erläutert. Weitere Informationen zu diesen Konzepten und Codebeispielen finden Sie in der Spring Data for Azure Cosmos DB SDK-Infodatei.

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 zur Abhängigkeitsverwaltung abzurufen, in dem 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 unterschiedliche 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

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 und Spring Cloud 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 der Emulator ein selbstsigniertes HTTPS-Zertifikat verwendet, müssen Sie sein Zertifikat in den Java vertrauenswürdigen Zertifikatspeicher importieren, der hier erläutert wird.
  • (Optional) SLF4J ist eine Protokollierungsfassade.
  • (Optional) Die SLF4J-Bindung wird verwendet, um ein bestimmtes Protokollierungsframework mit SLF4J zu verknüpfen.
  • (Optional) Maven

Sie benötigen SLF4J nur, 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, erweitern Sie AbstractCosmosConfiguration. 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, GatewayConnectionConfig oder beide bereitstellen und an CosmosClientBuilder übergeben. Ein vollständiges Beispiel finden Sie im Abschnitt zum Anpassen der Konfiguration.

Einrichtung der Entität

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

Die Containerannotation unterstützt die Angabe des Containernamens, Anforderungseinheiten (RUs), der Gültigkeitsdauer, das Erstellen von Containern mit automatisch skalierendem Durchsatz, die Unterstützung geschachtelter Partitionsschlüssel sowie weiterer 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 annotierten Abfragen in den Repositories mithilfe von @Query. Weitere Informationen finden Sie unter QueryAnnotation: Verwenden von kommentierten Abfragen in Repositorys.

Spring Data Anmerkungen

Spring Data-@Id-Anmerkung

Sie können ein Feld in einer Domänenklasse id auf mehrere Arten zuordnen. 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. Um den Containernamen anzupassen, 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 legt der Azure-Dienst IndexingPolicy fest. Um die IndexingPolicy anzupassen, fügen Sie der Domänenklasse die Annotation @CosmosIndexingPolicy hinzu. Weitere Informationen finden Sie im Abschnitt zur Indizierungsrichtlinie.

Eindeutige Schlüsselrichtlinie

Azure Spring Data Azure Cosmos DB unterstützt das Festlegen von UniqueKeyPolicy für den Container, indem die Annotation @CosmosUniqueKeyPolicy der Domänenklasse 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 mit @PartitionKey.

Wenn Sie einen CRUD-Vorgang ausführen, geben Sie den Partitionswert an.

Weitere Informationen finden Sie im Abschnitt hier testen.

Optimistische Sperre

Azure-spring-data-cosmos unterstützt die optimistische Sperrung für bestimmte Container. Diese Unterstützung bedeutet, dass Upserts und Löschungen nach Element mit einer Ausnahme fehlschlagen, wenn ein anderer Prozess das Element ändert. 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. Es unterstützt auch Spring Data Pageable, Slice und Sort. Weitere Informationen finden Sie im Abschnitt „Abfrage, Paginierung und Sortierung“.

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

Azure-spring-data-cosmos unterstützt die Nutzung von Azure Cosmos DB Java SDK. Sie können über ApplicationContext eine CosmosAsyncClient- oder CosmosClient-Bean beziehen und alle vom Azure Cosmos DB Java SDK unterstützten Vorgänge ausführen. 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 Auditing-Felder bei 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 mehrerer Datenbankkonten und eines einzelnen Kontos mit mehreren Datenbanken. Einen vollständigen Codeausschnitt finden Sie im Abschnitt Konfiguration mit mehreren Datenbanken.

Fehlerbehebung

Allgemein

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

Wenn Sie ein neues Feature oder eine neue Änderung vorschlagen möchten, 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 Beispielprojekt für mehrere Datenbanken.

Einzelnes Konto mit mehrstufiger Datenbank

Ein vollständiges Beispielprojekt finden Sie unter dem einzelnen Konto mit mehreren Datenbank-Beispielprojekts.

Nächste Schritte

Mitarbeit

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.

  • Zuletzt aktualisiert um