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.

W tym przewodniku wyjaśniono pojęcia dotyczące zestawu SDK Azure Spring Data Azure Cosmos DB, obsługiwanych funkcji, rozwiązywania problemów i znanych problemów. Aby uzyskać więcej informacji o tych pojęciach i przykładach kodu, zobacz plik readme pakietu Spring Data for Azure Cosmos DB SDK.

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 spring-boot-starter-parent projektu, aby uzyskać sekcję zarządzania zależnościami, która umożliwia 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 spring-data-commons wersje. 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 Azure Cosmos DB obsługuje wiele wersji platform Spring Boot i Spring Cloud. Aby uzyskać więcej informacji na temat wersji Azure Spring Data Azure Cosmos DB do użycia z platformą Spring Boot i spring Cloud, zobacz Która wersja Azure Spring Data dla Azure Cosmos DB powinna być używana?

Wprowadzenie

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ż emulator używa samopodpisanego certyfikatu HTTPS, należy zaimportować jego certyfikat do zaufanego magazynu certyfikatów Java, jak wyjaśniono tutaj.
• (Opcjonalnie) SLF4J to interfejs do logowania.
• (Opcjonalnie) powiązanie SLF4J służy do kojarzenia określonej struktury rejestrowania z SLF4J.
• (Opcjonalnie) Maven

Potrzebujesz SLF4J tylko wtedy, jeśli planujesz używać logowania. Pobierz również powiązanie SLF4J, które łą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, rozszerz rozszerzenie AbstractCosmosConfiguration. Aby uzyskać więcej informacji, zobacz Setup Configuration Class.

Możesz dostosować bazowe CosmosAsyncClient używane przez zestaw SDK Azure Spring Data Azure Cosmos DB, podając DirectConnectionConfig, GatewayConnectionConfig lub oba te elementy i przekazując je do CosmosClientBuilder. Aby zapoznać się z kompletnym przykładem, odwiedź sekcję dostosowywania konfiguracji.

Konfiguracja jednostki

Jednostkę prostą można zdefiniować jako element w Azure Cosmos DB. Zdefiniuj jednostki, 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 umożliwia określenie nazwy kontenera, jednostek żądań (RUs), czasu wygaśnięcia, tworzenie kontenerów z automatycznie skalowaną przepustowością, obsługę zagnieżdżonych kluczy partycji oraz innych 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ń za pomocą ID
• 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 Azure Cosmos DB obsługuje określanie zapytań z adnotacjami w repozytoriach przy użyciu polecenia @Query. Aby uzyskać więcej informacji, zobacz QueryAnnotation : Używanie zapytań z adnotacjami w repozytoriach.

Adnotacje danych Spring

Adnotacja Spring Data @Id

Pole w klasie domeny można mapować na id na wiele sposobów. Aby uzyskać więcej informacji, zobacz sekcję kodu adnotacji identyfikatora danych spring .

Automatyczne generowanie identyfikatorów

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

Wyrażenie spEL i niestandardowa nazwa kontenera

Domyślnie nazwa kontenera to nazwa klasy klasy domeny użytkownika. Aby dostosować nazwę kontenera, 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 usługa Azure ustawia wartość IndexingPolicy. Aby dostosować element IndexingPolicy, dodaj adnotację @CosmosIndexingPolicy do klasy domeny. Aby uzyskać więcej informacji, zobacz sekcję zasad indeksowania .

Zasada unikalnego klucza

Azure Spring Data Azure Cosmos DB obsługuje ustawianie właściwości UniqueKeyPolicy dla kontenera 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, dodaj do niego adnotację za pomocą @PartitionKeypolecenia .

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 określonych kontenerów. Ta obsługa oznacza, że operacja upserts i usuwanie według elementu kończy się niepowodzeniem z wyjątkiem, jeśli inny proces modyfikuje element. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą optymistycznego blokowania .

Niestandardowe zapytanie w Spring Data z opcjami stronicowania i sortowania

Azure-spring-data-cosmos obsługuje zapytania niestandardowe spring data, takie jak operacja znajdowania, taka jak findByAFieldAndBField. Obsługuje również Spring Data Pageable, Slice i Sort. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą zapytań, 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życie polecenia Azure Cosmos DB Java SDK. Za pośrednictwem ApplicationContext można uzyskać składnik CosmosAsyncClient lub CosmosClient i wykonywać dowolne operacje obsługiwane przez zestaw SDK Java 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 Azure Cosmos DB.

Konfiguracja wielu baz danych

Azure-spring-data-cosmos Obsługuje konfigurację wielu baz danych, w tym wiele kont bazy danych i jedno 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 usterka, zgłoś problem tutaj.

Aby zasugerować nową funkcję lub zmiany, 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 z wieloma bazami danych.

Jedno konto z wieloma bazami danych

Aby zapoznać się z kompletnym przykładowym projektem, zobacz przykładowe konto z wieloma bazami danych.

Następne kroki

• Dowiedz się więcej o funkcjach Azure Spring Data w kontekście Azure Cosmos DB.
• Przeczytaj więcej na temat usługi Azure Cosmos DB Service.
• Zobacz przykłady Azure Spring Data Azure Cosmos DB.
• Zobacz przykład Spring MVC z Azure Cosmos DB Sample.

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.