Snabbstart: Skapa en Java-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 Java-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 Java-app med hjälp av SQL Java SDK och lägger sedan till resurser i ditt Cosmos DB-konto med hjälp av Java-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 horisontella skalningsfunktioner.

Viktigt

Den här snabbstarten är endast Azure Cosmos DB Java SDK v4. Mer information finns i Azure Cosmos DB Java SDK v4Viktig information, Maven-lagringsplats,Azure Cosmos DB Java SDK v4-prestandatips och Azure Cosmos DB Java SDK v4-felsökningsguide för mer information. Om du för närvarande använder en äldre version än v4, se guiden Migrera till Azure Cosmos DB Java SDK v4 för hjälp med att uppgradera till v4.

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 i enheter 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 specifikationen för dataflöde på containernivå är normalt att föredra. Du kan läsa mer om dataflödesetablering här.

När objekt infogas i en Cosmos DB databas växer databasen vågrätt genom att lägga till mer lagring och beräkning för att hantera begäranden. Storage och beräkningskapacitet 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 rekommenderar vi att du väljer 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-cosmos-java-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.

Hantera databasresurser med hjälp av det synkrona API:et (synkronisering)

  • CosmosClient-initiering. tillhandahåller CosmosClient logisk representation på klientsidan för Azure Cosmos-databastjänsten. Den här klienten används för att konfigurera och köra förfrågningar till tjänsten.

    client = new CosmosClientBuilder()
        .endpoint(AccountSettings.HOST)
        .key(AccountSettings.MASTER_KEY)
        //  Setting the preferred location to Cosmos DB Account region
        //  West US is just an example. User should set preferred location to the Cosmos DB region closest to the application
        .preferredRegions(Collections.singletonList("West US"))
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildClient();
    
    
  • CosmosDatabase Skapandet.

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
  • CosmosContainer Skapandet.

    CosmosContainerProperties containerProperties =
        new CosmosContainerProperties(containerName, "/lastName");
    
    //  Create container with 400 RU/s
    CosmosContainerResponse cosmosContainerResponse =
        database.createContainerIfNotExists(containerProperties, ThroughputProperties.createManualThroughput(400));
    container = database.getContainer(cosmosContainerResponse.getProperties().getId());
    
  • Skapa objekt med hjälp av createItem metoden .

    //  Create item using container that we created using sync client
    
    //  Use lastName as partitionKey for cosmos item
    //  Using appropriate partition key improves the performance of database operations
    CosmosItemRequestOptions cosmosItemRequestOptions = new CosmosItemRequestOptions();
    CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()), cosmosItemRequestOptions);
    
  • Punktläsningar utförs med hjälp av readItem metoden .

    try {
        CosmosItemResponse<Family> item = container.readItem(family.getId(), new PartitionKey(family.getLastName()), Family.class);
        double requestCharge = item.getRequestCharge();
        Duration requestLatency = item.getDuration();
        logger.info("Item successfully read with id {} with a charge of {} and within duration {}",
            item.getItem().getId(), requestCharge, requestLatency);
    } catch (CosmosException e) {
        logger.error("Read Item failed with", e);
    }
    
  • SQL frågor över JSON utförs med hjälp av queryItems metoden .

    // Set some common query options
    CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions();
    //queryOptions.setEnableCrossPartitionQuery(true); //No longer necessary in SDK v4
    //  Set query metrics enabled to get metrics around query executions
    queryOptions.setQueryMetricsEnabled(true);
    
    CosmosPagedIterable<Family> familiesPagedIterable = container.queryItems(
        "SELECT * FROM Family WHERE Family.lastName IN ('Andersen', 'Wakefield', 'Johnson')", queryOptions, Family.class);
    
    familiesPagedIterable.iterableByPage(10).forEach(cosmosItemPropertiesFeedResponse -> {
        logger.info("Got a page of query result with {} items(s) and request charge of {}",
                cosmosItemPropertiesFeedResponse.getResults().size(), cosmosItemPropertiesFeedResponse.getRequestCharge());
    
        logger.info("Item Ids {}", cosmosItemPropertiesFeedResponse
            .getResults()
            .stream()
            .map(Family::getId)
            .collect(Collectors.toList()));
    });
    

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-cosmos-java-getting-started
    
  2. I git-terminalfönstret använder du följande kommando för att installera de Java-paket som krävs.

    mvn package
    
  3. I git-terminalfönstret använder du följande kommando för att starta Java-programmet (ersätt SYNCASYNCMODE med eller beroende på vilken exempelkod du vill köra, ersätt YOUR_COSMOS_DB_HOSTNAME med det angivna URI-värdet från portalen och ersätt YOUR_COSMOS_DB_MASTER_KEY med den angivna primärnyckeln sync async från portalen)

    mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY
    
    

    Terminalfönstret visar ett meddelande om att FamilyDB-databasen har skapats.

  4. Appen skapar en databas med namnet AzureSampleFamilyDB

  5. Appen skapar en container med namnet FamilyContainer

  6. Appen utför punktläsningar med objekt-ID:n och partitionsnyckelvärdet (som är lastName i vårt exempel).

  7. Appen kommer att fråga efter objekt för att hämta alla familjer med efternamn i ('Andersen', 'Wakefield', 'Johnson')

  8. Appen tar inte bort de skapade resurserna. Växla tillbaka till portalen för att rensa resurserna. från ditt konto så att du inte debiteras.

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 Java-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 vanliga begärandefrekvenser för din aktuella databasarbetsbelastning kan du läsa om att uppskatta enheter för programbegäran Azure Cosmos DB kapacitetsplaneraren