Rychlý start: Vytvoření aplikace v Javě pro správu dat rozhraní SQL API služby Azure Cosmos DB

PLATÍ PRO: SQL API

V tomto rychlém startu vytvoříte a spravujete účet rozhraní SQL API služby Azure Cosmos DB z Azure Portal a pomocí aplikace Java naklonované z GitHub. Nejprve pomocí rozhraní Azure Portal vytvoříte účet rozhraní SQL API služby Azure Cosmos DB, pak vytvoříte aplikaci v Javě pomocí sady SQL Java SDK a pak přidáte prostředky do účtu Cosmos DB pomocí aplikace Java. Azure Cosmos DB je databázová služba pro více modelů, která umožňuje rychle vytvářet a dotazovat databáze dokumentů, tabulek, párů klíč-hodnota a grafů s globální distribucí a možnostmi horizontálního škálování.

Důležité

Tento rychlý start je pouze pro sadu Azure Cosmos DB Java SDK v4. Další informace najdete v poznámkách k verzi sady Azure Cosmos DB Java SDK v4,úložišti Maven,tipy pro zvýšení výkonu sady Azure Cosmos DB Java SDK v4a průvodci odstraňováním potíží se sadou Azure Cosmos DB Java SDK v4. Pokud aktuálně používáte starší verzi než v4, nápovědu k upgradu na verzi 4 najdete v průvodci migrací do Azure Cosmos DB Java SDK v4.

Požadavky

  • Účet Azure s aktivním předplatným. Vytvořte si ho zdarma. Nebo vyzkoušejte Azure Cosmos DB zdarma bez předplatného Azure. Můžete také použít azure Cosmos DB Emulator s identifikátorem URI a klíčem https://localhost:8081 C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== .
  • Java Development Kit (JDK) 8. JAVA_HOMENasažte proměnnou prostředí do složky, ve které je nainstalovaná JDK.
  • Binární archiv Mavenu. Na Ubuntu spusťte a apt-get install maven nainstalujte Maven.
  • Git. Spuštěním příkazu v Ubuntu sudo apt-get install git nainstalujte Git.

Úvodní poznámky

Struktura účtu Cosmos DB. Bez ohledu na rozhraní API nebo programovací jazyk obsahuje účet Cosmos DB žádnou nebo více databází , databáze (DB) obsahuje nula nebo více kontejnerů a kontejner obsahuje nula nebo více položek, jak je znázorněno na následujícím diagramu:

Entity Cosmos účtu Azure

Další informace o databázích, kontejnerech a položkách najdete tady. Na úrovni kontejneru se definuje několik důležitých vlastností, mezi které patří zřízená propustnost a klíč oddílu.

Zřízená propustnost se měří v jednotkách žádostí (JEDNOTEK ŽÁDOSTI), které mají peněžní cenu a jsou zásadním určujícím faktorem provozních nákladů na účet. Zřízenou propustnost je možné vybrat s členitostí pro kontejnery nebo s členitostí podle databáze, ale obvykle se upřednostní specifikace propustnosti na úrovni kontejneru. Další informace o zřizování propustnosti najdete tady.

Při vkládání položek do kontejneru Cosmos DB roste databáze vodorovně přidáním dalšího úložiště a výpočetních prostředků pro zpracování požadavků. Storage a výpočetní kapacitu se přidávají v samostatných jednotkách označované jako oddíly a musíte zvolit jedno pole v dokumentech jako klíč oddílu, který mapuje každý dokument na oddíl. Způsob, jakým se oddíly spravují, je, že každému oddílu je přiřazen přibližně stejný řez z rozsahu hodnot klíče oddílu. Proto se doporučuje zvolit klíč oddílu, který je relativně náhodný nebo rovnoměrně rozdělený. V opačném případě se u některých oddílů zobrazí podstatně více požadavků ( horký oddíl ), zatímco jiné oddíly uvidí podstatně méně požadavků (studený oddíl ), a tomu je třeba se vyhnout. Další informace o dělení najdete tady.

Vytvoření účtu databáze

Než budete moci vytvořit databázi dokumentů, je potřeba pomocí služby Azure Cosmos DB vytvořit účet rozhraní SQL API.

  1. V Azure Portal nebo na domovské stránce vyberte Vytvořit prostředek.

  2. Na stránce Nový vyhledejte a vyberte Azure Cosmos DB.

  3. Na stránce Azure Cosmos DB vyberte Vytvořit.

  4. Na stránce Create Azure Cosmos DB Account (Vytvořit účet Azure Cosmos DB) zadejte základní nastavení nového účtu Azure Cosmos DB.

    Nastavení Hodnota Popis
    Předplatné Název předplatného Vyberte předplatné Azure, které chcete pro tento účet Azure Cosmos Azure.
    Skupina prostředků Název skupiny prostředků Vyberte skupinu prostředků nebo vyberte Vytvořit novou a pak zadejte jedinečný název nové skupiny prostředků.
    Account Name Jedinečný název Zadejte název pro identifikaci vašeho účtu Azure Cosmos. Protože documents.azure.com k názvu, který poskytnete pro vytvoření identifikátoru URI, použijte jedinečný název.

    Název může obsahovat pouze malá písmena, číslice a znak spojovníku (-). Musí mít délku 3 až 44 znaků.
    rozhraní API Typ účtu, který se má vytvořit Vyberte Core (SQL) a vytvořte databázi dokumentů a dotaz pomocí SQL syntaxe.

    Rozhraní API určuje typ účtu, který se má vytvořit. Azure Cosmos DB poskytuje pět rozhraní API: Core (SQL) a MongoDB pro data dokumentů, Gremlin pro data grafu, Azure Table a Cassandra. V současné době musíte pro každé rozhraní API vytvořit samostatný účet.

    Další informace o rozhraní API SQL.
    Umístění Oblast nejbližší vašim uživatelům Vyberte zeměpisné umístění, ve kterém chcete účet služby Azure Cosmos DB hostovat. Použijte umístění, které je vašim uživatelům nejblíže, a podejte jim nejrychlejší přístup k datům.
    Režim kapacity Zřízená propustnost nebo bez serveru Vyberte Zřízená propustnost a vytvořte účet v režimu zřízené propustnosti. Vyberte Bez serveru a vytvořte účet v režimu bez serveru.
    Použití slevy na bezplatnou úroveň Azure Cosmos DB Použít nebo Neakusovat S úrovní Free služby Azure Cosmos DB získáte v účtu prvních 1 000 RU/s a 25 GB úložiště zdarma. Přečtěte si další informace o úrovni Free.

    Poznámka

    Pro jedno předplatné Azure můžete mít až jeden účet Azure Cosmos DB úrovně Free a při vytváření účtu se musíte přihlásit. Pokud nevidíte možnost uplatnit slevu na bezplatnou úroveň, znamená to, že u jiného účtu v předplatném už je povolená úroveň Free.

    Stránka nového účtu pro službu Azure Cosmos DB

  5. Na kartě Globální distribuce nakonfigurujte následující podrobnosti. Pro účely tohoto rychlého startu můžete ponechat výchozí hodnoty:

    Nastavení Hodnota Popis
    Geografická redundance Zakázat Povolte nebo zakažte globální distribuci vašeho účtu spárováním oblasti s párovou oblastí. Další oblasti můžete do svého účtu přidat později.
    Zápisy do více oblastí Zakázat Funkce zápisu do více oblastí umožňuje využít zřízenou propustnost pro databáze a kontejnery po celém světě.

    Poznámka

    Pokud jako Režim kapacity vyberete Bez serveru, nejsou k dispozici následující možnosti:

    • Použít slevu založenou na bezplatné úrovni
    • Geografická redundance
    • Zápisy do více oblastí
  6. Volitelně můžete nakonfigurovat další podrobnosti na následujících kartách:

  7. Vyberte Zkontrolovat a vytvořit.

  8. Zkontrolujte nastavení účtu a pak vyberte Vytvořit. Vytvoření účtu trvá několik minut. Počkejte, až se na stránce portálu zobrazí Vaše nasazení je dokončené.

    Podokno Oznámení portálu Azure Portal

  9. Vyberte Přejít k prostředku a přejděte na stránku účtu Azure Cosmos DB.

    Stránka účtu Azure Cosmos DB

Přidání kontejneru

Teď můžete pomocí Průzkumník dat v Azure Portal vytvořit databázi a kontejner.

  1. Vyberte Průzkumník dat > New Container (Nový kontejner).

    Oblast Přidat kontejner se zobrazí na pravé straně. Možná se budete muset posunout doprava, abyste ji viděli.

    Průzkumník dat na webu Azure Portal s podoknem Přidat kontejner

  2. Na stránce Přidat kontejner zadejte nastavení pro nový kontejner.

    Nastavení Navrhovaná hodnota Popis
    ID databáze ToDoList Jako název nové databáze zadejte Tasks. Názvy databází musí mít 1 až 255 znaků a nesmí obsahovat /, \\, #, ? ani koncovou mezeru. Zaškrtněte možnost Sdílet propustnost mezi kontejnery, která umožňuje sdílet propustnost zřízenou v databázi mezi všemi kontejnery v databázi. Tato možnost také pomáhá s úsporou nákladů.
    Propustnost databáze Můžete zřídit automatické škálování nebo ruční propustnost. Ruční propustnost umožňuje škálovat RU/s sami, zatímco propustnost automatického škálování umožňuje systému škálovat RU/s na základě využití. V tomto příkladu vyberte Ruční.

    Propustnost nechte na 400 jednotkách žádostí za sekundu (RU/s). Pokud chcete snížit latenci, můžete propustnost později škálovat odhadem požadovaných RU/s pomocí kalkulačky kapacity.

    Poznámka: Toto nastavení není k dispozici při vytváření nového kontejneru v účtu bez serveru.
    ID kontejneru Položky Jako název nového kontejneru zadejte Items. Pro ID kontejnerů platí stejné požadavky týkající se použitých znaků jako pro názvy databází.
    Klíč oddílu /kategorie Ukázka popsaná v tomto článku používá jako klíč oddílu /category.

    V tomto příkladu neskládejte jedinečné klíče ani zapněte Analytické úložiště. Jedinečné klíče umožňují přidat do databáze vrstvu integrity dat tím, že zajišťují jedinečnost jedné nebo více hodnot na klíč oddílu. Další informace najdete v tématu Jedinečné klíče v Azure Cosmos DB. Analytické úložiště umožňuje rozsáhlé analýzy provozních dat bez jakéhokoli dopadu na vaše transakční úlohy.

    Vyberte OK. Průzkumník dat zobrazí novou databázi a kontejner.

Přidání ukázkových dat

Teď můžete do nového kontejneru přidat data pomocí Průzkumník dat.

  1. V Průzkumník dat rozbalte databázi Tasks a rozbalte kontejner Items. Vyberte Items (Položky) a pak vyberte New Item (Nová položka).

    Vytváření nových dokumentů v Průzkumníku dat na webu Azure Portal

  2. Teď do kontejneru přidejte dokument s následující strukturou.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Po přidání kódu JSON na kartu Dokumenty vyberte Uložit.

    Zkopírujte data JSON a v Průzkumník dat vyberte Uložit Průzkumník dat Azure Portal

  4. Vytvořte a uložte ještě jeden dokument, ve kterém vložíte jedinečnou hodnotu pro vlastnost id a změníte ostatní vlastnosti podle svých potřeb. Nové dokumenty můžou mít jakoukoli strukturu, protože Azure Cosmos DB neuplatňuje pro data žádné schéma.

Dotazování dat

Pomocí dotazů v nástroji Průzkumník dat načíst a filtrovat data.

  1. V horní části karty Položky v Průzkumník dat zkontrolujte výchozí dotaz SELECT * FROM c . Tento dotaz načte a zobrazí všechny dokumenty z kontejneru seřazené podle ID.

    Výchozí dotaz v Průzkumník dat je SELECT * FROM c

  2. Pokud chcete dotaz změnit, vyberte Upravit filtr, nahraďte výchozí dotaz hodnotou ORDER BY c._ts DESC a pak vyberte Použít filtr.

    Změna výchozího dotazu přidáním „ORDER BY c._ts DESC“ a kliknutím na Použít filtr

    Upravený dotaz zobrazí dokumenty v sestupném pořadí na základě jejich časového razítka, takže váš druhý dokument je teď uvedený jako první.

    Změna dotazu na ORDER BY c._ts DESC a kliknutí na Použít filtr

Pokud znáte syntaxi SQL, můžete do pole predikátu dotazu zadat všechny podporované dotazy SQL. Můžete také použít Průzkumník dat k vytváření uložených procedur, UDF a triggerů pro obchodní logiku na straně serveru.

Průzkumník dat poskytuje Azure Portal přístup ke všem integrovaným funkcím programového přístupu k datům dostupným v rozhraních API. Pomocí portálu můžete také škálovat propustnost, získat klíče a připojovací řetězce a zkontrolovat metriky a smlouvy SLA pro Azure Cosmos DB účet.

Klonování ukázkové aplikace

Teď přejděme k práci s kódem. Naklonujeme aplikaci SQL API z GitHubu, nastavíme připojovací řetězec a spustíme ji. Přesvědčíte se, jak snadno se pracuje s daty prostřednictvím kódu programu.

Ukázkové úložiště naklonujete spuštěním následujícího příkazu. Tento příkaz vytvoří na vašem počítači kopii ukázkové aplikace.

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

Kontrola kódu

Tento krok je volitelný. Pokud chcete zjistit, jak se v kódu vytvářejí prostředky databáze, můžete si prohlédnout následující fragmenty kódu. Jinak můžete přeskočit přímo k části Spuštění aplikace.

Správa databázových prostředků pomocí synchronního (synchronního) rozhraní API

  • Inicializace klienta CosmosClient. Poskytuje CosmosClient logickou reprezentaci na straně klienta pro službu Azure Cosmos databázovou službu. Tento klient slouží ke konfiguraci a provádění požadavků na službu.

    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 Vytvoření.

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
  • CosmosContainer Vytvoření.

    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());
    
  • Vytvoření položky pomocí createItem metody .

    //  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);
    
  • Čtení bodů se provádí pomocí readItem metody .

    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 dotazy přes JSON se provádějí pomocí queryItems metody .

    // 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()));
    });
    

Spuštění aplikace

Teď se vraťte zpět na web Azure Portal, kde najdete informace o připojovacím řetězci, a spusťte aplikaci s použitím informací o vašem koncovém bodu. Tím aplikaci umožníte komunikovat s hostovanou databází.

  1. V okně terminálu Git přejděte pomocí příkazu cd do složky se vzorovým kódem.

    cd azure-cosmos-java-getting-started
    
  2. V okně terminálu Git pomocí následujícího příkazu nainstalujte požadované balíčky Java.

    mvn package
    
  3. V okně terminálu Git spusťte aplikaci Java pomocí následujícího příkazu (nahraďte SYNCASYNCMODE kódem nebo podle toho, který ukázkový kód chcete spustit, nahraďte YOUR_COSMOS_DB_HOSTNAME hodnotou identifikátoru URI v uvozovce z portálu a nahraďte YOUR_COSMOS_DB_MASTER_KEY primárním klíčem v uvozovce sync async z portálu).

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

    V okně terminálu se zobrazí oznámení o vytvoření databáze FamilyDB.

  4. Aplikace vytvoří databázi s názvem . AzureSampleFamilyDB

  5. Aplikace vytvoří kontejner s názvem . FamilyContainer

  6. Aplikace bude provádět čtení bodů pomocí ID objektů a hodnoty klíče oddílu (v naší ukázce je lastName).

  7. Aplikace se bude dotazovat na položky, aby se načítaly všechny rodiny s příjmením v souboru ('Andersen', 'Wakefield', 'Pište')

  8. Aplikace neodstraňuje vytvořené prostředky. Přepněte zpět na portál a vyčistěte prostředky ze svého účtu, aby se vám za ně neúčtovaly poplatky.

Ověření smluv SLA na webu Azure Portal

Tento Azure Portal monitoruje propustnost Cosmos DB účtu, úložiště, dostupnost, latenci a konzistenci vašeho účtu. Grafy metrik přidružených k Azure Cosmos DB smlouva SLA (SLA) zobrazují hodnotu SLA v porovnání se skutečným výkonem. Díky této metrice je monitorování smluv SLA transparentní.

Kontrola metrik a smluv SLA:

  1. V navigační nabídce vašeho Cosmos DB účtu vyberte Metriky.

  2. Vyberte kartu, například Latence, a vpravo vyberte časový rámec. Porovnejte čáry Actual (Skutečný) a SLA (Sla) v grafech.

    Sada metrik Azure Cosmos DB

  3. Zkontrolujte metriky na ostatních kartách.

Vyčištění prostředků

Až budete s aplikací a Azure Cosmos DB účtem hotovi, můžete odstranit prostředky Azure, které jste vytvořili, abyste se neúčtují další poplatky. Odstranění prostředků:

  1. Na panelu hledání Azure Portal vyhledejte a vyberte skupiny prostředků.

  2. V seznamu vyberte skupinu prostředků, kterou jste vytvořili pro tento rychlý Start.

    Vyberte skupinu prostředků, kterou chcete odstranit.

  3. Na stránce Přehled skupiny prostředků vyberte Odstranit skupinu prostředků.

    Odstranění skupiny prostředků

  4. V dalším okně zadejte název skupiny prostředků, kterou chcete odstranit, a pak vyberte Odstranit.

Další kroky

V tomto rychlém startu jste se dozvěděli, jak vytvořit účet rozhraní SQL API služby Azure Cosmos DB, vytvořit databázi dokumentů a kontejner pomocí Průzkumník dat a spustit aplikaci v Javě, která to samé naprogramuje. Teď můžete do svého účtu Azure Cosmos DB importovat další data.

Pokoušíte se provést plánování kapacity pro migraci do Azure Cosmos DB? Informace o existujícím databázovém clusteru můžete použít k plánování kapacity.

  • Pokud víte jen počet virtuálních jadr a serverů ve stávajícím databázovém clusteru, přečtěte si o odhadování jednotek žádostí pomocí virtuálních jadr nebo virtuálních procesorů.
  • Pokud znáte typickou míru požadavků pro aktuální databázové úlohy, přečtěte si o odhadování jednotek žádostí pomocí Plánovače kapacity služby Azure Cosmos DB.