Snabbstart: Skapa en Spring Data Azure Cosmos DB v3-app för att hantera Azure Cosmos DB SQL API-data

GÄLLER FÖR: SQL API

I den här snabbstarten skapar och hanterar du ett Azure Cosmos DB SQL API-konto från Azure Portal och med hjälp av en Spring Data Azure Cosmos DB v3-app som klonas från GitHub. Först skapar du ett Azure Cosmos DB SQL API-konto med hjälp av Azure Portal, skapar sedan en Spring Boot-app med hjälp av Spring Data Azure Cosmos DB v3-anslutningsappen och lägger sedan till resurser till ditt Cosmos DB-konto med hjälp av Spring Boot-programmet. Azure Cosmos DB är en databastjänst med flera modeller som gör att du snabbt kan skapa och fråga databaser för dokument, tabeller, nyckelvärden och grafer med global distribution och horisontell skalning.

Viktigt

Den här versionsinformationen gäller för version 3 av Spring Data Azure Cosmos DB. Du hittar versionsanteckningar för version 2 här.

Spring Data Azure Cosmos DB stöder endast SQL API.

I de här artiklarna finns information om Spring Data på Azure Cosmos DB API:er:

Förutsättningar

Introduktionsanteckningar

Strukturen för ett Cosmos DB konto. Oavsett API eller programmeringsspråk innehåller ett Cosmos DB-konto noll eller flera databaser, en databas (DB) innehåller noll eller flera containrar och en container innehåller noll eller flera objekt, enligt diagrammet nedan:

Azure Cosmos-kontoentiteter

Du kan läsa mer om databaser, containrar och objekt här. Några viktiga egenskaper definieras på containernivå, bland annat etablerat dataflöde och partitionsnyckel.

Det etablerade dataflödet mäts ienheter för begäran (RU:er) som har ett penningpris och som är en viktig faktor för kontots driftskostnader. Etablerat dataflöde kan väljas med kornighet per container eller kornighet per databas, men dataflödesspecifikation på containernivå föredras vanligtvis. Du kan läsa mer om dataflödesetablering här.

När objekt infogas i en Cosmos DB container växer databasen vågrätt genom att lägga till mer lagringsutrymme och beräkning för att hantera begäranden. Storage och beräkningskapaciteten läggs till i diskreta enheter som kallas partitioner, och du måste välja ett fält i dina dokument som partitionsnyckeln som mappar varje dokument till en partition. Sättet som partitioner hanteras på är att varje partition tilldelas en ungefär lika stor sektor utanför intervallet med partitionsnyckelvärden. Därför bör du välja en partitionsnyckel som är relativt slumpmässig eller jämnt distribuerad. I annat fall ser vissa partitioner betydligt fler begäranden (heta partitioner) medan andra partitioner ser betydligt färre begäranden ( kall partition), och detta bör undvikas. Du kan lära dig mer om partitionering här.

Skapa ett databaskonto

Innan du kan börja skapa en dokumentdatabas måste du skapa ett SQL-API-konto med Azure Cosmos DB.

  1. På Azure Portal eller på sidan Start väljer du Skapa en resurs.

  2. På sidan Nytt söker du efter och väljer Azure Cosmos DB.

  3. På sidan Azure Cosmos DB väljer du Skapa.

  4. På sidan Skapa Azure Cosmos DB-konto anger du de grundläggande inställningarna för det nya Azure Cosmos-kontot.

    Inställning Värde Beskrivning
    Prenumeration Prenumerationens namn Välj den Azure-prenumeration som ska användas för det här Azure Cosmos-kontot.
    Resursgrupp Namn på resursgrupp Välj en resursgrupp eller välj Skapa ny och ange sedan ett unikt namn för den nya resursgruppen.
    Account Name Ett unikt namn Ange ett namn som identifierar ditt Azure Cosmos-konto. Eftersom documents.azure.com läggs till det namn du anger för att skapa din URI måste du använda ett unikt namn.

    Namnet får endast innehålla gemener, siffror och bindestreck (-). Det måste vara mellan 3 och 44 tecken långt.
    API Typ av konto som skapas Välj Core (SQL) för att skapa en dokumentdatabas och kör frågor med hjälp av SQL-syntax.

    API:et avgör vilken typ av konto som skapas. Azure Cosmos DB innehåller fem API:er: Core (SQL) och MongoDB för dokumentdata, Gremlin för grafdata, Azure Table och Cassandra. För närvarande måste du skapa ett separat konto för varje API.

    Läs mer om SQL API.
    Location Den region som är närmast dina användare Välj en geografisk plats som värd för ditt Azure Cosmos DB-konto. Använd den plats som är närmast dina användare för att ge dem så snabb åtkomst till data som möjligt.
    Kapacitetsläge Etablerat dataflöde eller serverlöst Välj Etablerat dataflöde för att skapa ett konto i etablerat dataflödesläge. Välj Serverlös för att skapa ett konto i serverlöst läge.
    Tillämpa Azure Cosmos DB rabatt på kostnadsfri nivå Tillämpa eller Tillämpa inte Med Azure Cosmos DB kostnadsfri nivå får du de första 1 000 RU/s och 25 GB lagringsutrymme kostnadsfritt i ett konto. Läs mer om den kostnadsfria nivån.

    Anteckning

    Du kan ha upp till en kostnadsfri nivå Azure Cosmos DB per Azure-prenumeration och måste välja när du skapar kontot. Om du inte ser alternativet för att tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

    Den nya kontosidan för Azure Cosmos DB

  5. Konfigurera följande information på fliken Global distribution. Du kan lämna standardvärdena i den här snabbstarten:

    Inställning Värde Beskrivning
    Geo-redundans Inaktivera Aktivera eller inaktivera global distribution på ditt konto genom att koppla ihop din region med en parregion. Du kan lägga till fler regioner i ditt konto senare.
    Skrivåtgärder för flera regioner Inaktivera Med skrivfunktioner för flera regioner kan du dra nytta av det etablerade dataflödet för dina databaser och containrar över hela världen.

    Anteckning

    Följande alternativ är inte tillgängliga om du väljer Serverlös som Kapacitetsläge:

    • Tillämpa rabatt för kostnadsfri nivå
    • Geo-redundans
    • Skrivåtgärder för flera regioner
  6. Du kan också konfigurera ytterligare information på följande flikar:

    • Nätverk – Konfigurera åtkomst från ett virtuellt nätverk.
    • Säkerhetskopieringspolicy – Konfigurera princip för regelbunden eller kontinuerlig säkerhetskopiering.
    • Kryptering – Använd antingen en tjänst hanterad nyckel eller en kund hanterad nyckel.
    • Taggar – Taggar är namn-/värdepar som gör att du kan kategorisera resurser och visa konsoliderad fakturering genom att tillämpa samma tagg på flera resurser och resursgrupper.
  7. Välj Granska + skapa.

  8. Granska kontoinställningarna och välj sedan Skapa. Det tar några minuter att skapa kontot. Vänta tills portalsidan visar meddelandet Distributionen är klar.

    Meddelandefönstret på Azure-portalen

  9. Välj Gå till resurs för att gå till sidan för Azure Cosmos DB-kontot.

    Sidan för Azure Cosmos DB-kontot

Lägga till en container

Nu kan du använda Datautforskaren i Azure Portal för att skapa en databas och container.

  1. Välj Datautforskaren > Ny container.

    Området Lägg till container visas längst till höger. Du kan behöva rulla åt höger för att se det.

    Datautforskaren på Azure-portalen, fönstret Lägg till container

  2. På sidan Lägg till container anger du inställningarna för den nya containern.

    Inställning Föreslaget värde Beskrivning
    Databas-ID ToDoList Ange Uppgifter som namn på den nya databasen. Databasnamn måste innehålla 1–255 tecken och får inte innehålla /, \\, #, ?, eller avslutande blanksteg. Markera alternativet Dela dataflöde mellan containrar. Det gör att du kan dela dataflödet som etablerats på databasen över alla containrar i databasen. Det här alternativet hjälper också till med kostnadsbesparingar.
    Databasdataflöde Du kan etablera autoskalning eller manuellt dataflöde. Med manuellt dataflöde kan du skala RU/s själv, medan dataflödet för automatisk skalning gör att systemet kan skala RU/s baserat på användning. Välj Manuell för det här exemplet.

    Lämna dataflödet på 400 enheter för begäran per sekund (RU/s). Om du vill minska svarstiden kan du skala upp dataflödet senare genom att uppskatta nödvändiga RU/s med kapacitetskalkylatorn.

    Obs! Den här inställningen är inte tillgänglig när du skapar en ny container i ett serverlöst konto.
    Container-ID Poster Ange Objekt som namn på den nya containern. För container-ID:n gäller samma teckenkrav som för databasnamn.
    Partitionsnyckel /category Exemplet som beskrivs i den här artikeln använder /category som partitionsnyckel.

    Lägg inte till unika nycklar eller aktivera analysarkiv för det här exemplet. Med unika nycklar kan du lägga till ett lager av dataintegritet i databasen genom att se till att ett eller flera värden per partitionsnyckel är unika. Mer information finns i Unika nycklar i Azure Cosmos DB. Analysarkiv används för att möjliggöra storskalig analys mot driftdata utan att påverka dina transaktionsarbetsbelastningar.

    Välj OK. Datautforskaren visar den nya databasen och containern.

Lägga till exempeldata

Nu kan du lägga till data i den nya containern med Datautforskaren.

  1. Från Datautforskaren expanderar du databasen Uppgifter och expanderar containern Objekt. Välj Objekt och välj sedan Nytt objekt.

    Skapa nya dokument i datautforskaren i Azure Portal

  2. Lägg nu till ett dokument i containern med följande struktur.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. När du har lagt till json på fliken Dokument väljer du Spara.

    Kopiera json-data och välj Spara i Datautforskaren i Azure Portal

  4. Skapa och spara ännu ett dokument där du lägger till ett unikt värde för egenskapen id och ändrar de andra egenskaperna som passar. Dina nya dokument kan ha vilken struktur du vill eftersom Azure Cosmos DB inte kräver något schema för dina data.

Fråga dina data

Du kan använda frågor i Datautforskaren för att hämta och filtrera dina data.

  1. Granska standardfrågan längst upp på Datautforskaren fliken SELECT * FROM c Objekt. Den här frågan hämtar och visar alla dokument från containern sorterade efter ID.

    Standardfrågan i Datautforskaren är SELECT * FROM c

  2. Om du vill ändra frågan väljer du Redigera filter, ersätter standardfrågan med ORDER BY c._ts DESC och väljer sedan Använd filter.

    Ändra standardfrågan genom att lägga till ORDER BY c._ts DESC och klicka på Tillämpa filter

    Den ändrade frågan visar dokumenten i fallande ordning baserat på deras tidsstämpel, så nu visas ditt andra dokument först.

    Frågan har ändrats till ORDER BY c._ts DESC och klicka på Använd filter

Om du är bekant med SQL-syntax kan du ange alla SQL-frågor som stöds i fråge predikatrutan. Du kan också använda Datautforskaren för att skapa lagrade procedurer,udf:er och utlösare för affärslogik på serversidan.

Datautforskaren ger enkel Azure Portal åtkomst till alla inbyggda funktioner för programmatisk dataåtkomst som är tillgängliga i API:erna. Du kan också använda portalen för att skala dataflöde, hämta nycklar och anslutningssträngar samt granska mått och serviceavtal för ditt Azure Cosmos DB konto.

Klona exempelprogrammet

Nu ska vi övergå till att arbeta med kod. Vi ska klona en SQL API-app från GitHub, ange anslutningssträngen och köra appen. Du kommer att se hur lätt det är att arbeta med data programmässigt.

Klona exempellagringsplatsen med följande kommando. Detta kommando skapar en kopia av exempelappen på din dator.

git clone https://github.com/Azure-Samples/azure-spring-data-cosmos-java-sql-api-getting-started.git

Granska koden

Det här är valfritt. Om du vill lära dig hur databasresurserna skapas i koden kan du granska följande kodavsnitt. Annars kan du gå vidare till Köra appen.

Programkonfigurationsfil

Här visar vi hur Spring Boot och Spring Data förbättrar användarupplevelsen – processen för att upprätta en Cosmos-klient och ansluta till Cosmos-resurser är nu konfiguration i stället för kod. Vid programstart Spring Boot allt detta exempel med hjälp av inställningarna i application.properties:

cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

När du har skapat ett Azure Cosmos DB-konto, databas och container fyller du bara i tomma filer i konfigurationsfilen så gör Spring Boot/Spring Data automatiskt följande: (1) skapa en underliggande Java SDK-instans med URI:n och nyckeln och (2) ansluta till databasen och CosmosClient containern. Nu är allt klart – ingen mer resurshanteringskod!

Java-källa

Spring Data-värde-tillägget kommer också från dess enkla, rena, standardiserade och plattformsoberoende gränssnitt för drift i datalager. Nedan följer crud-exempel GitHub spring data-exempel som är länkade ovan och frågeexempel för att manipulera Azure Cosmos DB-dokument med Spring Data Azure Cosmos DB.

  • Skapa och uppdatera objekt med hjälp av save metoden .

    
    logger.info("Saving user : {}", testUser1);
    userRepository.save(testUser1);
    
    
  • Punktläsningar med hjälp av den härledda frågemetoden som definierats i lagringsplatsen. findByIdAndLastNameutför punktläsningar för UserRepository . Fälten som anges i metodnamnet gör att Spring Data kör en punktläsning som definieras av id fälten lastName och :

    
    // to find by Id, please specify partition key value if collection is partitioned
    final User result = userRepository.findByIdAndLastName(testUser1.getId(), testUser1.getLastName());
    logger.info("Found user : {}", result);
    
    
  • Objektet tas bort med hjälp av deleteAll :

    
    userRepository.deleteAll();
    
    
  • Härledd fråga baserat på lagringsplatsens metodnamn. Spring Data implementerar UserRepository metoden som en Java SDK SQL fråga i fältet (den här frågan kunde inte findByFirstName firstName implementeras som en punktläsning):

    
    Flux<User> users = reactiveUserRepository.findByFirstName("testFirstName");
    users.map(u -> {
        logger.info("user is : {}", u);
        return u;
    }).subscribe();
    
    

Kör appen

Gå nu tillbaka till Azure-portalen för att hämta information om din anslutningssträng och starta appen med din slutpunktsinformation. På så vis kan appen kommunicera med den värdbaserade databasen.

  1. I git-terminalfönstret cd till exempelkodsmappen.

    cd azure-spring-data-cosmos-java-sql-api-getting-started/azure-spring-data-cosmos-java-getting-started/
    
  2. I git-terminalfönstret använder du följande kommando för att installera de Spring Data-Azure Cosmos DB paket.

    mvn clean package
    
  3. I git-terminalfönstret använder du följande kommando för att starta Spring Data Azure Cosmos DB program:

    mvn spring-boot:run
    
  4. Appen läser in application.properties och ansluter resurserna i ditt Azure Cosmos DB konto.

  5. Appen utför CRUD-åtgärder för punkt som beskrivs ovan.

  6. Appen utför en härledd fråga.

  7. Appen tar inte bort dina resurser. Växla tillbaka till portalen för att rensa resurserna från ditt konto om du vill undvika kostnader.

Granska serviceavtal i Azure-portalen

Den Azure Portal övervakar Cosmos DB dataflöde, lagring, tillgänglighet, svarstid och konsekvens för ditt konto. Diagram för mått som är associerade med Azure Cosmos DB Serviceavtal (SLA) visar SLA-värdet jämfört med faktiska prestanda. Den här måttsviten gör övervakningen av dina serviceavtal transparent.

Så här granskar du mått och serviceavtal:

  1. Välj Mått i Cosmos DB-kontots navigeringsmeny.

  2. Välj en flik, till exempel Svarstid, och välj en tidsram till höger. Jämför linjerna Actual och SLA i diagrammen.

    Azure Cosmos DB-måttsvit

  3. Granska måtten på de andra flikarna.

Rensa resurser

När du är klar med din app och Azure Cosmos DB-konto kan du ta bort de Azure-resurser som du skapade så att du inte debiteras mer. Ta bort resurser:

  1. I sökfältet Azure Portal du efter och väljer Resursgrupper.

  2. I listan väljer du den resursgrupp som du skapade för den här snabbstarten.

    Välj den resursgrupp som ska tas bort

  3. På sidan Översikt för resursgruppen väljer du Ta bort resursgrupp.

    Ta bort resursgruppen

  4. I nästa fönster anger du namnet på den resursgrupp som ska tas bort och väljer sedan Ta bort.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett Azure Cosmos DB SQL API-konto, skapar en dokumentdatabas och container med hjälp av Datautforskaren och kör en Spring Data-app för att göra samma sak programmässigt. Du kan nu importera ytterligare data till ditt Azure Cosmos DB konto.

Försöker du göra kapacitetsplanering för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.

  • Om allt du vet är antalet virtuella kärnor och servrar i ditt befintliga databaskluster kan du läsa om att uppskatta enheter för programbegäran med hjälp av virtuella kärnor eller virtuella processorer
  • Om du känner till typiska begärandefrekvenser för din aktuella databasarbetsbelastning kan du läsa om att uppskatta enheter för programbegäran Azure Cosmos DB kapacitetsplaneraren