Guida per sviluppatori di Azure Cosmos DB

Azure Spring Data per Azure Cosmos DB offre il supporto spring data per Azure Cosmos DB per NoSQL. 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, Cassandra, Graph e Table.

Questa guida illustra i concetti di Azure Spring Data Azure Cosmos DB SDK, funzionalità supportate, risoluzione dei problemi e problemi noti. Per altre informazioni sui concetti e sugli esempi di codice seguenti, vedere il file leggimi Spring Data per Azure Cosmos DB SDK.

Criteri di supporto delle versioni

Supporto della versione di Spring Boot

Questo progetto supporta più versioni di Spring Boot. Per altre informazioni, vedere Spring Boot Support Policy .For more information, see Spring Boot Support Policy. Gli utenti Maven possono ereditare dal spring-boot-starter-parent progetto per ottenere una sezione di gestione delle dipendenze per consentire a Spring di gestire le versioni per le dipendenze. Per altre informazioni, vedere Supporto della versione di Spring Boot.

Supporto della versione di Spring Data

Questo progetto supporta diverse versioni di spring-data-commons. Per altre informazioni, vedere Spring Data Version Support.For more information, see Spring Data Version Support.

Quale versione di Azure Spring Data azure Cosmos DB usare

La libreria Azure Cosmos DB di Azure Spring Data supporta più versioni di Spring Boot/Spring Cloud. Per altre informazioni su quale versione di Azure Spring Data Azure Cosmos DB usare con Spring Boot/Spring Cloud, vedere Quale versione di Azure Spring Data per Azure Cosmos DB è consigliabile usare?.

Attività iniziali

Includere il pacchetto

Se si usa Maven, aggiungere la dipendenza seguente.

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

Prerequisiti

• Java Development Kit (JDK), versione 8 o successiva.
• Un account Azure attivo. Se non si ha un account, è possibile iscriversi per ottenere un account gratuito. In alternativa, è possibile usare l'emulatore di Azure Cosmos DB per lo sviluppo e il test. Poiché il certificato https dell'emulatore è autofirmato, è necessario importarne il certificato nell'archivio certificati attendibili Java, come illustrato qui
• (Facoltativo) SLF4J è una facciata di registrazione.
• (Facoltativo) L'associazione SLF4J viene usata per associare un framework di registrazione specifico a SLF4J.
• (Facoltativo) Maven

SLF4J è necessario solo se si prevede di usare la registrazione, scaricare anche un binding SLF4J, che collegerà l'API SLF4J all'implementazione di registrazione preferita. Per altre informazioni, vedere il manuale dell'utente di SLF4J.

Configurare e personalizzare la classe di configurazione

Per configurare la classe di configurazione, è necessario estendere AbstractCosmosConfiguration. Per altre informazioni, vedere Classe di configurazione del programma di installazione.

È possibile personalizzare l'istanza sottostante CosmosAsyncClient usata da Azure Spring Data Azure Cosmos DB SDK fornendo DirectConnectionConfig o GatewayConnectionConfig entrambi e fornendoli a CosmosClientBuilder. Per un esempio completo, vedere la sezione personalizzazione della configurazione.

Configurazione delle entità

È possibile definire un'entità semplice come elemento in Azure Cosmos DB. È possibile definire le entità aggiungendo l'annotazione @Container e specificando le proprietà correlate al contenitore. Per altre informazioni, vedere Definire un'entità.

L'annotazione del contenitore supporta la specifica del nome del contenitore, le unità richiesta (UR), la durata, la creazione di contenitori con velocità effettiva con scalabilità automatica, il supporto della chiave di partizione annidata e altre proprietà del contenitore.

Configurazione del repository

Azure Spring Data Azure Cosmos DB supporta ReactiveCrudRepository (API asincrone) e CrudRepository (API di sincronizzazione), che forniscono le funzionalità CRUD di base seguenti:

• save
• Findall
• findOne per ID
• deleteAll
• delete by ID
• eliminare un'entità

È possibile estendere CosmosRepository (per il supporto dell'API di sincronizzazione) o ReactiveCosmosRepository (per il supporto dell'API asincrona) per configurare i repository Spring Data per l'applicazione. Per altre informazioni, vedere Creare repository.

Azure Spring Data Azure Cosmos DB supporta la specifica di query con annotazioni nei repository usando @Query. Per altre informazioni, vedere QueryAnnotation : Uso di query con annotazioni nei repository.

Annotazioni spring data

Annotazione spring data @Id

Esistono diversi modi per eseguire il mapping di un campo nella classe di dominio a id. Per altre informazioni, vedere la sezione relativa al codice di annotazione dell'ID dati spring.

Generazione automatica id

Azure Spring Data Azure Cosmos DB supporta la generazione automatica di ID usando l'annotazione @GeneratedValue . Per altre informazioni, vedere la sezione Generazione automatica ID.

Espressione SpEL e nome del contenitore personalizzato

Per impostazione predefinita, il nome del contenitore sarà il nome della classe di dominio utente. Per personalizzare, aggiungere l'annotazione @Container(containerName="myCustomContainerName") alla classe di dominio. Per altre informazioni, vedere la sezione SpEL expression and custom container name .For more information, see the SpEL expression and custom container name section.

IndexingPolicy personalizzato

Per impostazione predefinita, IndexingPolicy verrà impostato dal servizio di Azure. Per personalizzare, aggiungere l'annotazione @CosmosIndexingPolicy alla classe di dominio. Per altre informazioni, vedere la sezione criteri di indicizzazione.

Criteri di chiave univoca

Azure Spring Data Azure Cosmos DB supporta l'impostazione UniqueKeyPolicy nel contenitore aggiungendo l'annotazione @CosmosUniqueKeyPolicy alla classe di dominio. Per altre informazioni, vedere la sezione Criteri chiave univoca.

Partizione di Azure Cosmos DB

Azure-spring-data-cosmos supporta le partizioni di Azure Cosmos DB.

Per specificare un campo della classe di dominio come campo chiave di partizione, è sufficiente annotarlo con @PartitionKey.

Quando si esegue un'operazione CRUD, specificare il valore della partizione.

Per altre informazioni, vedere la sezione test qui.

Blocco ottimistico

Azure-spring-data-cosmos supporta il blocco ottimistico per contenitori specifici, il che significa che upserts/deletes by item avrà esito negativo con un'eccezione nel caso in cui l'elemento venga modificato da un altro processo nel frattempo. Per altre informazioni, vedere la sezione relativa al blocco ottimistico.

Query personalizzata Spring Data, ricercabile e ordinamento

Azure-spring-data-cosmos supporta query personalizzate Spring Data, ad esempio un'operazione di ricerca, findByAFieldAndBFieldad esempio . Supporta anche Spring Data Pageable, Slice e Sort. Per altre informazioni, vedere la sezione query, ricercabile e ordinamento.

Uso di Java SDK di Azure Cosmos DB tramite Spring Data Cosmos

Azure-spring-data-cosmos supporta l'uso di Azure Cosmos DB Java SDK. Gli utenti possono ottenere o CosmosAsyncClient inviare CosmosClient un bean tramite ApplicationContext ed eseguire qualsiasi operazione supportata da Azure Cosmos DB Java SDK. Per altre informazioni, vedere la sezione uso di Azure Cosmos Client tramite Spring Data Cosmos.

Spring Data REST

Azure-spring-data-cosmos supporta Spring Data REST. Per altre informazioni, vedere la sezione API REST di Azure Cosmos DB per Azure Spring Data.

Controllo

Azure-spring-data-cosmos supporta il controllo dei campi nelle entità di database che usano annotazioni spring-data standard. Per altre informazioni, vedere la sezione Relativa al controllo di Azure Cosmos DB per Spring Data.

Configurazione multi-database

Azure-spring-data-cosmos supporta la configurazione multi-database, tra cui "più account di database" e "account singolo, con più database". Per un frammento di codice completo, vedere la sezione configurazione multi database.

Risoluzione dei problemi

Generali

Se si verifica un bug, inviare un problema qui.

Per suggerire una nuova funzionalità o modifiche che potrebbero essere apportate, inviare un problema nello stesso modo in cui si farebbe per un bug.

Abilitare la registrazione client

Azure-spring-data-cosmos usa SLF4j come facciata di registrazione che supporta l'accesso ai framework di registrazione più diffusi, ad esempio log4j e logback. Per altre informazioni, vedere la sezione abilitare la registrazione client.

Esempi

Per un progetto di esempio completo, vedere il progetto di esempio.

Account di database multipli

Per un progetto di esempio completo, vedere il progetto di esempio multi-database.

Account singolo con più database

Per un progetto di esempio completo, vedere Il progetto di esempio Single account with Multi-database .For a complete sample project, see the Single account with Multi-database sample project.

Passaggi successivi

• Altre informazioni su Azure Spring Data Azure Cosmos DB.
• Altre informazioni sul servizio Azure Cosmos DB
• Vedere gli esempi di Azure Spring Data per Azure Cosmos DB
• Vedere l'esempio Spring MVC con Azure Cosmos DB

Contributo

This project welcomes contributions and suggestions. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un contratto di licenza e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire le istruzioni specificate dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando il nostro contratto di licenza.

Questo progetto ha adottato il codice di comportamento open source Microsoft. Per altre informazioni, vedere Domande frequenti sul codice di comportamento oppure scrivere a opencode@microsoft.com per qualsiasi altro commento o domanda.