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
- Ett Azure-konto med en aktiv prenumeration. Skapa en utan kostnad. Eller prova Azure Cosmos DB utan en Azure-prenumeration. Du kan också använda Azure Cosmos DB Emulator med en URI
https://localhost:8081för och nyckelnC2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. - Java Development Kit (JDK) 8. Peka
JAVA_HOMEmiljövariabeln till den mapp där JDK är installerad. - Ett Maven-binärt arkiv. I Ubuntu kör du för
apt-get install mavenatt installera Maven. - Git. I Ubuntu kör du för
sudo apt-get install gitatt installera Git.
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:
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.
På Azure Portal eller på sidan Start väljer du Skapa en resurs.
På sidan Nytt söker du efter och väljer Azure Cosmos DB.
På sidan Azure Cosmos DB väljer du Skapa.
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.
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
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.
Välj Granska + skapa.
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.
Välj Gå till resurs för att gå till 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.
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.
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.
Från Datautforskaren expanderar du databasen Uppgifter och expanderar containern Objekt. Välj Objekt och välj sedan Nytt objekt.

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 }När du har lagt till json på fliken Dokument väljer du Spara.

Skapa och spara ännu ett dokument där du lägger till ett unikt värde för egenskapen
idoch ä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.
Granska standardfrågan längst upp på Datautforskaren fliken
SELECT * FROM cObjekt. Den här frågan hämtar och visar alla dokument från containern sorterade efter ID.
Om du vill ändra frågan väljer du Redigera filter, ersätter standardfrågan med
ORDER BY c._ts DESCoch väljer sedan Använd filter.
Den ändrade frågan visar dokumenten i fallande ordning baserat på deras tidsstämpel, så nu visas ditt andra dokument först.
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ållerCosmosClientlogisk 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();CosmosDatabaseSkapandet.CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName); database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());CosmosContainerSkapandet.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
createItemmetoden .// 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
readItemmetoden .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
queryItemsmetoden .// 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.
I git-terminalfönstret
cdtill exempelkodsmappen.cd azure-cosmos-java-getting-startedI git-terminalfönstret använder du följande kommando för att installera de Java-paket som krävs.
mvn packageI 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
syncasyncfrån portalen)mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEYTerminalfönstret visar ett meddelande om att FamilyDB-databasen har skapats.
Appen skapar en databas med namnet
AzureSampleFamilyDBAppen skapar en container med namnet
FamilyContainerAppen utför punktläsningar med objekt-ID:n och partitionsnyckelvärdet (som är lastName i vårt exempel).
Appen kommer att fråga efter objekt för att hämta alla familjer med efternamn i ('Andersen', 'Wakefield', 'Johnson')
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:
Välj Mått i Cosmos DB-kontots navigeringsmeny.
Välj en flik, till exempel Svarstid, och välj en tidsram till höger. Jämför linjerna Actual och SLA i diagrammen.

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:
I sökfältet Azure Portal du efter och väljer Resursgrupper.
I listan väljer du den resursgrupp som du skapade för den här snabbstarten.

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

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