Spring-Data-Unterstützung

In diesem Artikel wird beschrieben, wie Spring Cloud Azure und Spring Data zusammen verwendet werden können.

Spring Data Azure Cosmos DB-Unterstützung

Azure Cosmos DB ist ein global verteilter Datenbankdienst, mit dem Entwickler mit verschiedenen Standard-APIs wie SQL, MongoDB, Graph und Azure Table Storage arbeiten können.

Einrichtung von Abhängigkeiten

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>

Konfiguration

Anmerkung

Wenn Sie einen Sicherheitsprinzipal zur Authentifizierung und Autorisierung gegenüber Microsoft Entra ID für den Zugriff auf eine Azure-Ressource verwenden, stellen Sie sicher, dass dem Sicherheitsprinzipal ausreichende Zugriffsberechtigungen für die Azure-Ressource erteilt wurden. Weitere Informationen finden Sie unter Autorisieren des Zugriffs mit microsoft Entra ID.

In der folgenden Tabelle sind die konfigurierbaren Eigenschaften von spring-cloud-azure-starter-data-cosmosaufgeführt:

Eigentum	Beschreibung
spring.cloud.azure.cosmos.enabled	Ein Wert, der angibt, ob Azure Cosmos DB Service aktiviert ist. Der Standardwert ist true.
spring.cloud.azure.cosmos.database	Die Azure Cosmos DB-Datenbank-ID.
spring.cloud.azure.cosmos.endpoint	Der URI zum Verbinden von Azure Cosmos DB.
spring.cloud.azure.cosmos.key	Der PrivateKey zum Verbinden von Azure Cosmos DB.
spring.cloud.azure.cosmos.credential.client-certificate-password	Das Kennwort der Zertifikatdatei.
spring.cloud.azure.cosmos.credential.client-certificate-path	Der Pfad einer PEM-Zertifikatdatei, die beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll.
spring.cloud.azure.cosmos.credential.client-id	Die Client-ID, die beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll.
spring.cloud.azure.cosmos.credential.client-secret	Der geheime Clientschlüssel, der beim Ausführen der Dienstprinzipalauthentifizierung mit Azure verwendet werden soll.
spring.cloud.azure.cosmos.credential.managed-identity-enabled	Gibt an, ob verwaltete Identität aktiviert werden soll. Der Standardwert ist false.
spring.cloud.azure.cosmos.credential.password	Das Kennwort, das beim Ausführen der Authentifizierung mit Benutzername/Kennwort mit Azure verwendet werden soll.
spring.cloud.azure.cosmos.credential.username	Der Benutzername, der bei der Authentifizierung mit Benutzername/Kennwort bei Azure verwendet werden soll.
spring.cloud.azure.cosmos.populate-query-metrics	Ein Wert, der angibt, ob Diagnosezeichenfolgen und Abfragemetriken ausgefüllt werden sollen. Der Standardwert ist false.
spring.cloud.azure.cosmos.consistency-level	Eine Konsistenzstufe für Azure Cosmos DB.

Schlüsselkonzepte

Die folgende Liste zeigt die wichtigsten Konzepte der Spring Data-Unterstützung:

• Die Spring Data CrudRepository und ReactiveCrudRepository, die die folgenden grundlegenden CRUD-Funktionen bieten:

  • Speichern
  • findAll
  • findOne anhand der ID
  • Alle löschen
  • Per ID löschen
  • Entität löschen

• Die Spring Data @Id Anmerkung. Es gibt zwei Möglichkeiten, ein Feld in einer Domänenklasse dem id eines Azure Cosmos DB-Dokuments zuzuordnen:

  • Kommentieren Sie ein Feld in der Domänenklasse mit @Id. Dieses Feld wird dokument id in Azure Cosmos DB zugeordnet.
  • Legen Sie den Namen dieses Felds auf idfest. Dieses Feld wird dokument id in Azure Cosmos DB zugeordnet.

  Anmerkung

  Wenn beide Methoden angewendet werden, hat die @Id Anmerkung eine höhere Priorität.

• Benutzerdefinierte Auflistungsnamen. Standardmäßig ist der Sammlungsname der Klassenname der Benutzerdomänenklasse. Um es anzupassen, fügen Sie Ihrer Domänenklasse die Annotation @Document(collection="myCustomCollectionName") hinzu, mehr ist nicht nötig.

• Unterstützt Azure Cosmos DB-Partition. Wenn Sie ein Feld Ihrer Domänenklasse als Partitionsschlüsselfeld angeben möchten, kommentieren Sie es mit @PartitionKey. Wenn Sie CRUD-Vorgänge ausführen, geben Sie den Partitionswert an. Weitere Beispiele finden Sie unter AddressRepositoryIT.java auf GitHub.

• Unterstützt den Suchvorgang mit benutzerdefinierter Spring-Data-Abfrage.

• Unterstützt spring-boot-starter-data-rest.

• Unterstützt Listen- und geschachtelte Typen in Domänenklassen.

Grundlegende Nutzung

Verwenden eines privaten Schlüssels für den Zugriff auf Azure Cosmos DB

Die einfachste Möglichkeit, Azure Cosmos DB mit spring-cloud-azure-starter-data-cosmos zu verbinden, ist mit einem Primärschlüssel. Fügen Sie die folgenden Eigenschaften hinzu:

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${AZURE_COSMOS_DATABASE}

Definieren einer Entität

Definieren Sie eine Entität als Dokument in Azure Cosmos DB, wie im folgenden Beispiel gezeigt:

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {
    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

Das feld id wird als Dokument id in Azure Cosmos DB verwendet. Alternativ können Sie jedes Feld mit @Id kommentieren, um es dem Dokument idzuzuordnen.

Die Anmerkung @Container(containerName = "mycollection") wird verwendet, um den Auflistungsnamen Ihres Dokuments in Azure Cosmos DB anzugeben.

Erstellen von Repositorys

Um Repositories zu erstellen, erweitern Sie die Schnittstelle ReactiveCosmosRepository, die Unterstützung für Spring-Data-Repositories bietet.

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

Derzeit stellt die ReactiveCosmosRepository-Schnittstelle grundlegende Speicher-, Lösch- und Suchvorgänge bereit. Weitere Operationen werden später unterstützt.

Erstellen einer Anwendungsklasse

Im folgenden Beispiel wird eine Anwendungsklasse mit allen Komponenten erstellt:

@SpringBootApplication
public class CosmosSampleApplication implements CommandLineRunner {

private static final Logger LOGGER = LoggerFactory.getLogger(CosmosSampleApplication.class);

    @Autowired
    private UserRepository repository;

    @Autowired
    private CosmosProperties properties;

    public static void main(String[] args) {
        SpringApplication.run(CosmosSampleApplication.class, args);
    }

    public void run(String... var1) {
        final User testUser = new User("testId", "testFirstName",
                "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()),
                "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()),
                "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()),
                "query result lastName doesn't match!");
        LOGGER.info("findOne in User collection get result: {}", result.toString());

    }

    @PostConstruct
    public void setup() {
        // For this example, remove all of the existing records.
        this.repository.deleteAll().block();
    }
}

Dieses Beispiel enthält eine automatisch verkabelte UserRepository Schnittstelle zur Unterstützung von Speicher-, Lösch- und Suchvorgängen.

Proben

Siehe azure-spring-boot-samples auf GitHub.

Neben der Verwendung der spring-cloud-azure-starter-data-cosmos-Bibliothek können Sie azure-spring-data-cosmos Bibliothek direkt für komplexere Szenarien verwenden. Weitere Informationen finden Sie unter Spring Data für Azure Cosmos DB-Clientbibliothek.