Supporto di Spring Data

Questo articolo descrive in che modo Spring Cloud Azure e Spring Data possono essere usati insieme.

Supporto di Spring Data per Azure Cosmos DB

azure Cosmos DB è un servizio di database distribuito a livello globale che consente agli sviluppatori di lavorare con i dati usando varie API standard, ad esempio SQL, MongoDB, Graph e Archiviazione tabelle di Azure.

Configurazione delle dipendenze

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

Configurazione

Nota

Se si usa un'entità di sicurezza per eseguire l'autenticazione e l'autorizzazione con Microsoft Entra ID per accedere a una risorsa di Azure, assicurarsi che all'entità di sicurezza sia stata concessa l'autorizzazione sufficiente per accedere alla risorsa di Azure. Per altre informazioni, vedere Autorizzare l'accesso con Microsoft Entra ID.

Nella tabella seguente sono elencate le proprietà configurabili di spring-cloud-azure-starter-data-cosmos:

Proprietà	Descrizione
spring.cloud.azure.cosmos.enabled	Valore che indica se il servizio Azure Cosmos DB è abilitato. Il valore predefinito è true.
spring.cloud.azure.cosmos.database	ID del database di Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint	URI per connettere Azure Cosmos DB.
spring.cloud.azure.cosmos.key	PrivateKey per connettere Azure Cosmos DB.
spring.cloud.azure.cosmos.credential.client-certificate-password	Password del file di certificato.
spring.cloud.azure.cosmos.credential.client-certificate-path	Percorso di un file di certificato PEM da usare quando si esegue l'autenticazione dell'entità servizio con Azure.
spring.cloud.azure.cosmos.credential.client-id	ID del client da utilizzare per eseguire l'autenticazione del service principal con Azure.
spring.cloud.azure.cosmos.credential.client-secret	Il segreto del client da usare quando si esegue l'autenticazione tramite service principal con Azure.
spring.cloud.azure.cosmos.credential.managed-identity-enabled	Indica se abilitare l'identità gestita. Il valore predefinito è false.
spring.cloud.azure.cosmos.credential.password	Password da usare quando si esegue l'autenticazione con nome utente/password con Azure.
spring.cloud.azure.cosmos.credential.username	Nome utente da usare quando si esegue l'autenticazione con nome utente/password con Azure.
spring.cloud.azure.cosmos.populate-query-metrics	Un valore che indica se compilare le stringhe di diagnostica e le metriche di query. Il valore predefinito è false.
spring.cloud.azure.cosmos.consistency-level	Un livello di coerenza per Azure Cosmos DB.

Concetti chiave

L'elenco seguente illustra i concetti chiave del supporto spring data:

• Spring Data CrudRepository e ReactiveCrudRepository, che forniscono le funzionalità CRUD di base seguenti:

  • salvare
  • trova tutto
  • findOne per ID
  • eliminaTutto
  • elimina per ID
  • eliminare un'entità

• L'annotazione Spring Data @Id. Esistono due modi per eseguire il mapping di un campo in una classe di dominio alla id di un documento di Azure Cosmos DB:

  • Annotare un campo nella classe di dominio con @Id. Questo campo verrà mappato al documento id in Azure Cosmos DB.
  • Impostare il nome di questo campo su id. Questo campo verrà mappato al documento id in Azure Cosmos DB.

  Nota

  Se vengono applicati entrambi i modi, l'annotazione @Id ha priorità più alta.

• Nomi di raccolta personalizzati. Per impostazione predefinita, il nome della raccolta sarà il nome della classe di dominio utente. Per personalizzarla, aggiungere un'annotazione @Document(collection="myCustomCollectionName") alla classe di dominio.

• Supporta partizione di Azure Cosmos DB. Per specificare un campo della classe di dominio come campo della chiave di partizione, annotarlo con @PartitionKey. Quando si eseguono operazioni CRUD, specificare il valore della partizione. Per altri esempi, vedere AddressRepositoryIT.java su GitHub.

• Supporta l'operazione di ricerca query personalizzata di Spring Data.

• Supporta spring-boot-starter-data-rest.

• Supporta l'elenco e i tipi annidati nelle classi di dominio.

Utilizzo di base

Usare una chiave privata per accedere ad Azure Cosmos DB

Il modo più semplice per connettere Azure Cosmos DB con spring-cloud-azure-starter-data-cosmos è con una chiave primaria. Aggiungere le proprietà seguenti:

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

Definire un'entità

Definire un'entità come documento in Azure Cosmos DB, come illustrato nell'esempio seguente:

@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);
    }
}

Il campo id verrà usato come documento id in Azure Cosmos DB. In alternativa, è possibile annotare qualsiasi campo con @Id per eseguirne il mapping al documento id.

L'annotazione @Container(containerName = "mycollection") viene usata per specificare il nome della raccolta del documento in Azure Cosmos DB.

Creare repository

Per creare repository, estendere l'interfaccia ReactiveCosmosRepository, che fornisce il supporto del repository Spring Data.

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

Attualmente, l'interfaccia ReactiveCosmosRepository fornisce operazioni di salvataggio, eliminazione e ricerca di base. Altre operazioni saranno supportate in un secondo momento.

Creare una classe dell'applicazione

L'esempio seguente crea una classe applicazione con tutti i componenti:

@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();
    }
}

Questo esempio include un'interfaccia UserRepository cablata per supportare operazioni di salvataggio, eliminazione e ricerca.

Campioni

Vedi azure-spring-boot-samples su GitHub.

Oltre a usare la libreria di spring-cloud-azure-starter-data-cosmos, è possibile usare direttamente azure-spring-data-cosmos libreria per scenari più complessi. Per altre informazioni, vedere Spring Data per la libreria client di Azure Cosmos DB.