Quickstart: Azure Cosmos DB for NoSQL-bibliotheek voor Java

Artikel
01/10/2024

VAN TOEPASSING OP: NoSQL

Ga aan de slag met de Azure Cosmos DB for NoSQL-clientbibliotheek voor Java om gegevens in uw containers op te vragen en algemene bewerkingen uit te voeren op afzonderlijke items. Volg deze stappen om een minimale oplossing in uw omgeving te implementeren met behulp van de Azure Developer CLI.

API-referentiedocumentatiebibliotheek | broncodepakket | (Maven) | Azure Developer CLI

Vereisten

Een Azure-account met een actief abonnement. Gratis een account maken
Een GitHub-account

Een Azure-account met een actief abonnement. Gratis een account maken
Azure Developer CLI
Docker Desktop

Instellen

Implementeer de ontwikkelcontainer van dit project in uw omgeving. Gebruik vervolgens de Azure Developer CLI (azd) om een Azure Cosmos DB for NoSQL-account te maken en een containervoorbeeldtoepassing te implementeren. De voorbeeldtoepassing maakt gebruik van de clientbibliotheek voor het beheren, maken, lezen en opvragen van voorbeeldgegevens.

Belangrijk

GitHub-accounts bevatten gratis rechten voor opslag en kernuren. Zie inbegrepen opslag- en kernuren voor GitHub-accounts voor meer informatie.

Open een terminal in de hoofdmap van het project.
Verifiëren bij de Azure Developer CLI met behulp van azd auth login. Volg de stappen die door het hulpprogramma zijn opgegeven om te verifiëren bij de CLI met behulp van uw favoriete Azure-referenties.
```
azd auth login
```
Gebruik azd init dit om het project te initialiseren.
```
azd init
```
Configureer tijdens de initialisatie een unieke omgevingsnaam.

Tip

De omgevingsnaam wordt ook gebruikt als de naam van de doelresourcegroep. Voor deze quickstart kunt u overwegen .msdocs-cosmos-db-
Implementeer het Azure Cosmos DB-account met behulp van azd up. De Bicep-sjablonen implementeren ook een voorbeeldwebtoepassing.
```
azd up
```
Selecteer tijdens het inrichtingsproces uw abonnement en gewenste locatie. Wacht tot het inrichtingsproces is voltooid. Het proces kan ongeveer vijf minuten duren.

Zodra het inrichten van uw Azure-resources is voltooid, wordt er een URL naar de actieve webtoepassing opgenomen in de uitvoer.

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

Gebruik de URL in de console om naar uw webtoepassing in de browser te navigeren. Bekijk de uitvoer van de actieve app.

De clientbibliotheek installeren

De clientbibliotheek is beschikbaar via Maven, als pakket azure-spring-data-cosmos .

Navigeer naar de /src/web map en open het pom.xml-bestand .

Als deze nog niet bestaat, voegt u een vermelding voor het azure-spring-data-cosmos pakket toe.

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

Voeg ook nog een afhankelijkheid voor het azure-identity pakket toe als het nog niet bestaat.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Objectmodel

Name	Beschrijving
`EnableCosmosRepositories`	Dit type is een methode-decorator die wordt gebruikt om een opslagplaats te configureren voor toegang tot Azure Cosmos DB for NoSQL.
`CosmosRepository`	Deze klasse is de primaire clientklasse en wordt gebruikt voor het beheren van gegevens in een container.
`CosmosClientBuilder`	Deze klasse is een fabriek die wordt gebruikt om een client te maken die door de opslagplaats wordt gebruikt.
`Query`	Dit type is een methode-decorator die wordt gebruikt om de query op te geven die door de opslagplaats wordt uitgevoerd.

De voorbeeldcode in de sjabloon maakt gebruik van een database met de naam cosmicworks en container.products De products container bevat details zoals naam, categorie, hoeveelheid, een unieke id en een verkoopvlag voor elk product. De container gebruikt de /category eigenschap als een logische partitiesleutel.

De client verifiëren

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Gebruik het DefaultAzureCredential type als voorkeursmethode om een wachtwoordloze verbinding tussen uw toepassingen en Azure Cosmos DB for NoSQL te implementeren. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt.

Belangrijk

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan zich verifiëren bij de databaseservice. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken zonder het risico dat sleutels worden opgeslagen.

Eerst maakt dit voorbeeld een nieuwe klasse die de verbinding met Azure Cosmos DB for NoSQL over neemt AbstractCosmosConfiguration om de verbinding te configureren.

@Configuration
@EnableCosmosRepositories
public class CosmosConfiguration extends AbstractCosmosConfiguration {

In de configuratieklasse maakt dit voorbeeld een nieuw exemplaar van de CosmosClientBuilder klasse en configureert verificatie met behulp van een DefaultAzureCredential exemplaar.

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    DefaultAzureCredential azureTokenCredential = new DefaultAzureCredentialBuilder()
        .build();
        
    return new CosmosClientBuilder()
        .endpoint(uri)
        .credential(azureTokenCredential);
}

Een database ophalen

In de configuratieklasse implementeert het voorbeeld een methode om de naam van de bestaande database met de naam cosmicworkste retourneren.

@Override
protected String getDatabaseName() {
    return "cosmicworks";
}

Een container ophalen

Gebruik de Container methode-decorator om een klasse te configureren om items in een container weer te geven. Ontwerp de klasse om alle leden op te nemen die u in JSON wilt serialiseren. In dit voorbeeld heeft het type een unieke id en velden voor categorie, naam, hoeveelheid, prijs en klaring.

@Container(containerName = "products", autoCreateContainer = false)
public class Item {
    private String id;
    private String name;
    private Integer quantity;
    private Boolean sale;

    @PartitionKey
    private String category;

Een item maken

Maak een item in de container met behulp van repository.save.

Item item = new Item(
    "70b63682-b93a-4c77-aad2-65501347265f",
    "gear-surf-surfboards",
    "Yamba Surfboard",
    12,
    false
);
Item created_item = repository.save(item);

Een item lezen

Voer een puntleesbewerking uit met behulp van zowel de unieke id (id) als de partitiesleutelvelden. Gebruik repository.findById dit om het specifieke item efficiënt op te halen.

PartitionKey partitionKey = new PartitionKey("gear-surf-surfboards");
Optional<Item> existing_item = repository.findById("70b63682-b93a-4c77-aad2-65501347265f", partitionKey);
if (existing_item.isPresent()) {
    // Do something  
}

Query-items

Voer een query uit op meerdere items in een container door een query te definiëren in de interface van de opslagplaats. In dit voorbeeld wordt de Query methode-decorator gebruikt om een methode te definiëren waarmee deze geparameteriseerde query wordt uitgevoerd:

SELECT * FROM products p WHERE p.category = @category

@Repository
public interface ItemRepository extends CosmosRepository<Item, String> {
    @Query("SELECT * FROM products p WHERE p.category = @category")
    List<Item> getItemsByCategory(@Param("category") String category);
}

Haal alle resultaten van de query op met behulp van repository.getItemsByCategory. Doorloop de resultaten van de query.

List<Item> items = repository.getItemsByCategory("gear-surf-surfboards");
for (Item item : items) {
    // Do something
}

Volgende stap

Zelfstudie: Een Java-web-app bouwen