Przewodnik deweloperski usługi Azure Cosmos DB

Usługa Azure Spring Data dla usługi Azure Cosmos DB zapewnia obsługę usługi Spring Data dla usługi Azure Cosmos DB for NoSQL. azure Cosmos DB to globalnie rozproszona usługa bazy danych, która umożliwia deweloperom pracę z danymi przy użyciu różnych standardowych interfejsów API, takich jak SQL, MongoDB, Cassandra, Graph i Table.

Ten przewodnik zawiera omówienie pojęć związanych z zestawem AZURE Spring Data Azure Cosmos DB SDK, obsługiwanymi funkcjami, rozwiązywaniem problemów i znanymi problemami. Aby uzyskać więcej informacji na temat poniższych pojęć i przykładów kodu, zobacz Spring Data for Azure Cosmos DB SDK readme.

Zasady obsługi wersji

Obsługa wersji platformy Spring Boot

Ten projekt obsługuje wiele wersji platformy Spring Boot. Aby uzyskać więcej informacji, zobacz politykę wsparcia Spring Boot. Użytkownicy programu Maven mogą dziedziczyć z projektu spring-boot-starter-parent, aby uzyskać sekcję zarządzania zależnościami, aby umożliwić platformie Spring zarządzanie wersjami zależności. Więcej informacji znajdziesz w sekcji Obsługa wersji Spring Boot.

Obsługa wersji rozwiązania Spring Data

Ten projekt obsługuje różne wersje spring-data-commons. Aby uzyskać więcej informacji, zobacz Obsługa wersji Spring Data.

Którą wersję Azure Spring Data for Azure Cosmos DB użyć

Biblioteka Azure Spring Data dla Azure Cosmos DB obsługuje wiele wersji Spring Boot/Spring Cloud. Aby uzyskać więcej informacji na temat wersji usługi Azure Spring Data Azure Cosmos DB do użycia z wersją spring boot/Spring Cloud, zobacz Której wersji usługi Azure Spring Data dla usługi Azure Cosmos DB należy używać?.

Rozpocznij

Uwzględnij pakiet

Jeśli używasz narzędzia Maven, dodaj następującą zależność.

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

Warunki wstępne

• pakiet Java Development Kit (JDK)w wersji 8 lub nowszej.
• Aktywne konto platformy Azure. Jeśli go nie masz, możesz zarejestrować się w celu uzyskania bezpłatnego konta . Alternatywnie możesz użyć emulatora usługi Azure Cosmos DB do programowania i testowania. Ponieważ certyfikat HTTPS emulatora jest samopodpisany, musisz zaimportować jego certyfikat do zaufanego magazynu certyfikatów Java, wyjaśnione tutaj
• (Opcjonalnie) SLF4J to interfejs do logowania.
• (Opcjonalnie) powiązanie SLF4J służy do kojarzenia określonej struktury rejestrowania z SLF4J.
• (Opcjonalnie) Maven

SLF4J jest wymagany tylko wtedy, gdy planujesz używać rejestrowania, pobierz również powiązanie SLF4J, które połączy interfejs API SLF4J z wybraną implementacją rejestrowania. Aby uzyskać więcej informacji, zobacz podręcznik użytkownika SLF4J.

Konfigurowanie i dostosowywanie klasy konfiguracji

Aby skonfigurować klasę konfiguracji, należy rozszerzyć AbstractCosmosConfiguration. Aby uzyskać więcej informacji, zobacz Setup Configuration Class.

Podstawowe komponenty CosmosAsyncClient używane przez zestaw SDK Azure Spring Data dla Azure Cosmos DB można dostosować, udostępniając DirectConnectionConfig, GatewayConnectionConfig lub oba i dostarczając je do CosmosClientBuilder. Aby uzyskać pełny przykład, odwiedź sekcję dostosowywania konfiguracji.

Konfiguracja jednostki

Jednostkę prostą można zdefiniować jako element w usłudze Azure Cosmos DB. Jednostki można zdefiniować, dodając adnotację @Container i określając właściwości powiązane z kontenerem. Aby uzyskać więcej informacji, zobacz Definiowanie jednostki.

Adnotacja kontenera obsługuje określanie nazwy kontenera, jednostek żądań (RU), czasu wygaśnięcia, tworzenie kontenerów z przepływnością automatycznego skalowania, obsługę zagnieżdżonych kluczy partycjioraz inne właściwości kontenera.

Konfiguracja repozytorium

Usługa Azure Spring Data Azure Cosmos DB obsługuje ReactiveCrudRepository (asynchroniczne interfejsy API) i CrudRepository (interfejsy API synchronizacji), które zapewniają następujące podstawowe funkcje CRUD:

• zapisać
• findAll
• znajdźJedno po identyfikatorze
• usuńWszystko
• usuń według identyfikatora
• usuwanie jednostki

Możesz rozszerzyć CosmosRepository (na potrzeby obsługi interfejsu API synchronizacji) lub ReactiveCosmosRepository (obsługa asynchronicznego interfejsu API), aby skonfigurować repozytoria Spring Data dla aplikacji. Aby uzyskać więcej informacji, zobacz Tworzenie repozytoriów.

Azure Spring Data w Azure Cosmos DB obsługuje określanie zapytań z adnotacjami w repozytoriach przy użyciu @Query. Aby uzyskać więcej informacji, zobacz QueryAnnotation : Używanie zapytań z adnotacjami w repozytoriach.

Adnotacje danych Spring

Adnotacja Spring Data @Id

Istnieje wiele sposobów mapowania pola w klasie domeny na id. Aby uzyskać więcej informacji, zobacz sekcję kodu adnotacji identyfikatora danych spring .

Automatyczne generowanie identyfikatorów

Usługa Azure Spring Data Azure Cosmos DB obsługuje automatyczne generowanie identyfikatorów przy użyciu adnotacji @GeneratedValue. Aby uzyskać więcej informacji, zobacz sekcję automatycznego generowania identyfikatorów .

Wyrażenie spEL i niestandardowa nazwa kontenera

Domyślnie nazwa kontenera będzie nazwą klasy klasy domeny użytkownika. Aby dostosować, dodaj adnotację @Container(containerName="myCustomContainerName") do klasy domeny. Aby uzyskać więcej informacji, zobacz sekcję Wyrażenie SpEL i niestandardowa nazwa kontenera.

Zasady indeksowania niestandardowego

Domyślnie IndexingPolicy zostanie ustawiony przez usługę Azure. Aby dostosować, dodaj adnotację @CosmosIndexingPolicy do klasy domeny. Aby uzyskać więcej informacji, zobacz sekcję zasad indeksowania .

Zasada unikalnego klucza

Usługa Azure Spring Data Azure Cosmos DB obsługuje ustawianie UniqueKeyPolicy w kontenerze przez dodanie adnotacji @CosmosUniqueKeyPolicy do klasy domeny. Aby uzyskać więcej informacji, zobacz sekcję unikatowych zasad klucza.

Partycja Azure Cosmos DB

Azure-spring-data-cosmos obsługuje partycje Azure Cosmos DB .

Aby określić pole klasy domeny jako pole klucza partycji, po prostu dodaj do niego adnotację przy użyciu @PartitionKey.

Podczas wykonywania operacji CRUD określ wartość partycji.

Aby uzyskać więcej informacji, zobacz sekcję test tutaj.

Optymistyczne blokowanie

Azure-spring-data-cosmos obsługuje optymistyczne blokowanie dla określonych kontenerów, co oznacza, że operacja upserts/deletes według elementu zakończy się niepowodzeniem z wyjątkiem w przypadku, gdy element zostanie zmodyfikowany przez inny proces w międzyczasie. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą optymistycznego blokowania .

Zapytanie niestandardowe Spring Data, stronicowanie i sortowanie

Azure-spring-data-cosmos obsługuje zapytania niestandardowe Spring Data, na przykład operację znajdowania, taką jak findByAFieldAndBField. Obsługuje również Spring Data Pageable, Slice i Sort. Aby uzyskać więcej informacji, zobacz sekcję zapytania oraz stronicowania i sortowania.

Korzystanie z zestawu Java SDK usługi Azure Cosmos DB za pośrednictwem usługi Spring Data Cosmos

Azure-spring-data-cosmos obsługuje używanie Azure Cosmos DB Java SDK. Użytkownicy mogą pobierać dokumenty CosmosClient lub CosmosAsyncClient przez ApplicationContext i wykonywać wszystkie obsługiwane operacje przez Java SDK usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz sekcję using Azure Cosmos Client through Spring Data Cosmos (Klient usługi Azure Cosmos za pośrednictwem usługi Spring Data Cosmos).

Spring Data REST

obsługujeSpring Data REST. Aby uzyskać więcej informacji, zobacz sekcję interfejsu API REST usługi Azure Spring Data w usłudze Azure Cosmos DB.

Inspekcja

Azure-spring-data-cosmos obsługuje pola inspekcji jednostek bazy danych przy użyciu standardowych adnotacji spring-data. Aby uzyskać więcej informacji, zobacz sekcję inspekcji Spring Data w usłudze Azure Cosmos DB.

Konfiguracja wielu baz danych

Azure-spring-data-cosmos obsługuje konfigurację wielu baz danych, w tym "wiele kont baz danych" i "pojedyncze konto" z wieloma bazami danych. Aby uzyskać pełny fragment kodu, zobacz sekcję konfiguracji wielu baz danych .

Rozwiązywanie problemów

Ogólne

Jeśli wystąpi jakakolwiek usterka, zgłoś problem tutaj.

Aby zasugerować nową funkcję lub zmiany, które można wprowadzić, zgłoś problem w taki sam sposób, jak w przypadku usterki.

Włącz rejestrowanie klienta

Azure-spring-data-cosmos używa SLF4j jako interfejsu rejestrowania, który obsługuje logowanie do popularnych frameworków rejestrowania, takich jak log4j i logback. Aby uzyskać więcej informacji, zobacz sekcję enable client logging (Włączanie rejestrowania klienta).

Przykłady

Pełny przykładowy projekt można znaleźć w przykładowym projekcie .

Konta z wieloma bazami danych

Pełny przykładowy projekt można znaleźć w przykładowym projekcie Multi-database.

Jedno konto z wieloma bazami danych

Aby uzyskać kompletny przykładowy projekt, zobacz przykładowy projekt Pojedyncze konto z wieloma bazami danych.

Następne kroki

• Dowiedz się więcej o funkcjach Azure Spring Data w kontekście Azure Cosmos DB.
• dowiedz się więcej o usłudze Azure Cosmos DB
• Zobacz przykłady usługi Azure Spring Data oraz usługi Azure Cosmos DB
• Zobacz przykład Spring MVC z usługą Azure Cosmos DB

Wkład

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość wkładów wymaga zgody na Umowę Licencyjną Współtwórcy (CLA), deklarując, że masz prawo do i faktycznie udzielasz nam praw do korzystania z twojego wkładu.

Po przesłaniu pull request, CLA-bot automatycznie określi, czy musisz podać CLA i odpowiednio oznaczy PR — na przykład etykietą, komentarzem. Po prostu postępuj zgodnie z instrukcjami dostarczonymi przez bota. Można to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszej umowy licencyjnej dla współtwórców (CLA).

Ten projekt przyjął kodeks postępowania otwartego firmy Microsoft . Aby uzyskać więcej informacji, zobacz Kodeks postępowania — często zadawane pytania lub skontaktuj się opencode@microsoft.com z innymi pytaniami lub komentarzami.