Przewodnik dla deweloperów dotyczący usługi Azure Cosmos DB

  • Artykuł

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 plik readme zestawu SDK spring data for Azure Cosmos DB.

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 Zasady obsługi platformy Spring Boot. Użytkownicy programu Maven mogą dziedziczyć z spring-boot-starter-parent projektu, aby uzyskać sekcję zarządzania zależnościami, aby umożliwić platformie Spring zarządzanie wersjami zależności. Aby uzyskać więcej informacji, zobacz Obsługa wersji platformy 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óra wersja usługi Azure Spring Data w usłudze Azure Cosmos DB do użycia

Biblioteka usługi Azure Spring Data w usłudze Azure Cosmos DB obsługuje wiele wersji rozwiązania 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óra wersja usługi Azure Spring Data dla usługi Azure Cosmos DB powinna być używana?.

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>

Wymagania wstępne

  • Zestaw Java Development Kit (JDK) w wersji 8 lub nowszej.
  • Aktywne konto platformy Azure. Jeśli go nie masz, możesz zarejestrować się w celu utworzenia bezpłatnego konta. Alternatywnie możesz użyć emulatora usługi Azure Cosmos DB do programowania i testowania. Ponieważ certyfikat https emulatora jest podpisany samodzielnie, musisz zaimportować jego certyfikat do zaufanego magazynu certyfikatów java, wyjaśniono tutaj
  • (Opcjonalnie) SLF4J to fasada rejestrowania.
  • (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, zobaczpodręcznik użytkownika fasady SLF4J.

Konfigurowanie i dostosowywanie klasy konfiguracji

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

Podstawowe dane używane przez zestaw SDK usługi Azure Spring Data usługi Azure Cosmos DB można dostosować CosmosAsyncClient , podając DirectConnectionConfig lub GatewayConnectionConfig oba te elementy i podając je w usłudze 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, tworzenia kontenerów z przepływnością autoskalowania, obsługi zagnieżdżonego klucza partycji i 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:

  • save
  • Findall
  • findOne według identyfikatora
  • Deleteall
  • usuń według identyfikatora
  • usuwanie jednostki

Możesz rozszerzyć CosmosRepository (na potrzeby obsługi interfejsu API synchronizacji) lub ReactiveCosmosRepository (w celu obsługi asynchronicznego interfejsu API) w celu skonfigurowania repozytoriów spring data dla aplikacji. Aby uzyskać więcej informacji, zobacz Tworzenie repozytoriów.

Usługa Azure Spring Data w usłudze Azure Cosmos DB obsługuje określanie zapytań z adnotacjami w repozytoriach przy użyciu polecenia @Query. Aby uzyskać więcej informacji, zobacz QueryAnnotation : Using annotated query in repozytoriies (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ę kod adnotacji identyfikatora danych spring.

Automatyczne generowanie identyfikatorów

Usługa Azure Spring Data w usłudze Azure Cosmos DB obsługuje automatyczne generowanie identyfikatorów przy użyciu @GeneratedValue adnotacji. Aby uzyskać więcej informacji, zobacz sekcję Automatyczne generowanie 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 niestandardową nazwę kontenera.

Zasady indeksowania niestandardowego

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

Unikatowe zasady klucza

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

Partycja usługi Azure Cosmos DB

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

Aby określić pole klasy domeny jako pole klucza partycji, wystarczy dodać do niego adnotację za pomocą polecenia @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ę optymistycznej blokady.

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ż funkcję Spring Data Pageable, Slice i Sort. Aby uzyskać więcej informacji, zobacz sekcję zapytania, stronicowanie i sortowanie.

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

Azure-spring-data-cosmos program obsługuje przy użyciu polecenia Azure Cosmos DB Java SDK. Użytkownicy mogą pobierać CosmosClient lub CosmosAsyncClient uruchamiać ApplicationContext dowolne operacje obsługiwane przez zestaw JAVA SDK usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz sekcję using Azure Cosmos Client through Spring Data Cosmos (Korzystanie z klienta usługi Azure Cosmos za pośrednictwem usługi Spring Data Cosmos).

Spring Data REST

Azure-spring-data-cosmos obsługuje architekturę Spring Data REST. Aby uzyskać więcej informacji, zobacz sekcję Interfejs 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ę Inspekcja 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. Pełny fragment kodu można znaleźć w sekcji 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łączanie rejestrowania klienta

Azure-spring-data-cosmos używa SLF4j jako fasady rejestrowania, która obsługuje logowanie do popularnych struktur rejestrowania, takich jak log4j i logback. Aby uzyskać więcej informacji, zobacz sekcję Włączanie rejestrowania klientów.

Przykłady

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

Konta wielu baz danych

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

Jedno konto z wieloma bazami danych

Pełny przykładowy projekt można znaleźć w przykładowym projekcie Single account with Multi-database (Pojedyncze konto z przykładową bazą danych z wieloma bazami danych).

Następne kroki

Przyczyniając się

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość kontrybucja wymaga zgody na umowę licencyjną współautora (CLA), deklarując, że masz prawo, a w rzeczywistości przyznaj nam prawa do korzystania z twojego wkładu.

Po przesłaniu żądania ściągnięcia bot CLA automatycznie określi, czy musisz podać cla i odpowiednio ozdobić żądanie ściągnięcia (na przykład etykieta, komentarz). Po prostu postępuj zgodnie z instrukcjami dostarczonymi przez bota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego CLA.

W tym projekcie jest używany Kodeks postępowania firmy Microsoft dla oprogramowania typu open source. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com innymi pytaniami lub komentarzami.

Impressions