Snabbstart: Skapa en grafdatabas i Azure Cosmos DB med Python och Azure Portal

GÄLLER FÖR: Gremlin API

I den här snabbstarten skapar och hanterar du ett Azure Cosmos DB Gremlin-API-konto (graph) från Azure Portal och lägger till data med hjälp av en Python-app som klonas från GitHub. Azure Cosmos DB är en databastjänst med flera modeller som gör att du snabbt kan skapa och fråga dokument-, tabell-, nyckelvärde- och grafdatabaser med globala distributions- och vågräta skalningsfunktioner.

Förutsättningar

Anteckning

Den här snabbstarten kräver ett grafdatabaskonto som skapats efter den 20 december 2017. Befintliga konton stöder Python när de är migrerade till allmän tillgänglighet.

Anteckning

Vi rekommenderar för närvarande att du använder gremlinpython==3.4.13 med Gremlin-API :et (Graph) eftersom vi inte har testat alla språkspecifika bibliotek av version 3.5.* för användning med tjänsten.

Skapa ett databaskonto

Innan du kan börja skapa en grafdatabas måste du skapa ett Gremlin-databaskonto (Graph) med Azure Cosmos DB.

  1. Logga in på Azure Portal i ett nytt webbläsarfönster.

  2. I den vänstra menyn väljer du Skapa en resurs.

    Create a resource in the Azure portal

  3. På sidan Nytt väljer du DatabaserAzure>Cosmos DB.

    The Azure portal Databases pane

  4. På sidan Skapa Azure Cosmos DB-konto anger du inställningarna för det nya Azure Cosmos DB-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 Ange ett unikt namn Ange ett unikt namn som identifierar ditt Azure Cosmos DB-konto. Din konto-URI läggs gremlin.azure.com till ditt unika kontonamn.

    Kontonamnet kan bara använda gemener, siffror och bindestreck (-) och måste vara mellan 3 och 44 tecken långt.
    API Gremlin (graf) API:et avgör vilken typ av konto som skapas. Azure Cosmos DB innehåller fem API:er: Core (SQL) för dokumentdatabaser, Gremlin för grafdatabaser, MongoDB för dokumentdatabaser, Azure Table och Cassandra. Du måste skapa ett separat konto för varje API.

    Välj Gremlin (graf) eftersom du i den här snabbstarten skapar en tabell som fungerar med Gremlin-API:et.

    Läs mer om Gremlin-API:et.
    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 rabatt på den kostnadsfria Azure Cosmos DB-nivån Använd eller använd inte Med den kostnadsfria Azure Cosmos DB-nivån får du de första 1 000 RU/s och 25 GB lagringsutrymme kostnadsfritt på ett konto. Läs mer om den kostnadsfria nivån.

    Anteckning

    Du kan ha upp till ett Azure Cosmos DB-konto på kostnadsfri nivå per Azure-prenumeration och måste anmäla dig 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.

    The new account page for Azure Cosmos DB

  5. På fliken Global distribution konfigurerar du följande information. 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 para 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 funktionen skrivningar i 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äkerhetskopieringsprincip – Konfigurera antingen regelbunden eller kontinuerlig säkerhetskopieringsprincip.
    • Kryptering – Använd antingen tjänsthanterad nyckel eller en kundhanterad nyckel.
    • Taggar – Taggar är namn/värde-par som gör att du kan kategorisera resurser och visa konsoliderad fakturering genom att använda samma tagg för flera resurser och resursgrupper.
  7. Välj Granska + skapa.

  8. Det tar några minuter att skapa kontot. Vänta tills portalen visar Grattis! Sidan för ditt Azure Cosmos DB-konto skapades .

    Azure Cosmos DB account created page

Lägga till en graf

Nu kan du använda datautforskarverktyget i Azure Portal för att skapa en grafdatabas.

  1. Välj Data Explorer>Ny Graph.

    Området Lägg till diagram visas längst till höger, du kan behöva bläddra åt höger för att se det.

    The Azure portal Data Explorer, Add Graph page

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

    Inställning Föreslaget värde Beskrivning
    Databas-id sample-database Ange sample-database som namn på den nya databasen. Databasnamn måste innehålla mellan 1 och 255 tecken och får inte innehålla / \ # ? eller avslutande blanksteg.
    Dataflöde 400 RU:er Ändra genomflödet till 400 begäransenheter per sekund (RU/s). Du kan skala upp dataflödet senare om du vill minska svarstiden.
    Graf-id sample-graph Ange sample-graph som namnet på den nya samlingen. Samma teckenkrav gäller för diagramnamn som databas-ID:n.
    Partition Key (Partitionsnyckel) /pk Alla Cosmos DB-konton behöver en partitionsnyckel för horisontell skalning. Lär dig hur du väljer en lämplig partitionsnyckel i artikeln Graph datapartitionering.
  3. När formuläret har fyllts i väljer du OK.

Klona exempelprogrammet

Nu ska vi övergå till att arbeta med kod. Nu ska vi klona en Gremlin-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.

  1. Öppna en kommandotolk, skapa en ny mapp som heter git-samples och stäng sedan kommandotolken.

    mkdir "./git-samples"
    
  2. Öppna ett git-terminalfönster, t.ex. git bash, och använd kommandot cd för att ändra till en mapp där du vill installera exempelappen.

    cd "./git-samples"
    
  3. 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-db-graph-python-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. Alla kodfragment hämtas från den connect.py filen i mappen C:\git-samples\azure-cosmos-db-graph-python-getting-started\ . Annars kan du gå vidare till Uppdatera din anslutningssträng.

  • Gremlin client initieras på rad 155 i connect.py. Se till att ersätta <YOUR_DATABASE> och <YOUR_CONTAINER_OR_GRAPH> med värdena för ditt kontos databasnamn och grafnamn:

    ...
    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_CONTAINER_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    ...
    
  • En serie Gremlin-steg deklareras i början av connect.py filen. De körs sedan med metoden client.submitAsync():

    client.submitAsync(_gremlin_cleanup_graph)
    

Uppdatera din anslutningsinformation

Gå nu tillbaka till Azure Portal för att hämta anslutningsinformation och kopiera den till appen. De här inställningarna gör det möjligt för appen att kommunicera med den värdbaserade databasen.

  1. I ditt Azure Cosmos DB-konto i Azure Portal väljer du Nycklar.

    Kopiera den första delen av URI-värdet.

    View and copy an access key in the Azure portal, Keys page

  2. Öppna filen connect.py och klistra in URI-värdet <YOUR_ENDPOINT> på rad 155 här:

    client = client.Client('wss://<YOUR_ENDPOINT>.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    

    URI-delen av klientobjektet bör nu likna den här koden:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/<YOUR_DATABASE>/colls/<YOUR_COLLECTION_OR_GRAPH>", 
        password="<YOUR_PASSWORD>")
    
  3. Ändra den andra parametern för objektet client för att ersätta strängarna <YOUR_DATABASE> och <YOUR_COLLECTION_OR_GRAPH>. Om du använde de föreslagna värdena bör parametern se ut som den här koden:

    username="/dbs/sample-database/colls/sample-graph"

    Hela objektet client bör nu se ut som den här koden:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="<YOUR_PASSWORD>")
    
  4. På sidan Nycklar använder du kopieringsknappen för att kopiera PRIMÄRNYCKEL och klistra in den <YOUR_PASSWORD> i parametern password=<YOUR_PASSWORD> .

    Hela objektdefinitionen client bör nu se ut som den här koden:

    client = client.Client('wss://test.gremlin.cosmosdb.azure.com:443/','g', 
        username="/dbs/sample-database/colls/sample-graph", 
        password="asdb13Fadsf14FASc22Ggkr662ifxz2Mg==")
    
  5. Spara filen connect.py .

Kör konsolappen

  1. I git-terminalfönstret cd till mappen azure-cosmos-db-graph-python-getting-started.

    cd "./git-samples\azure-cosmos-db-graph-python-getting-started"
    
  2. I git-terminalfönstret använder du följande kommando för att installera de Python-paket som krävs.

    pip install -r requirements.txt
    
  3. I git-terminalfönstret använder du följande kommando för att starta Python-programmet.

    python connect.py
    

    I terminalfönstret visas de hörn och gränser som läggs till i tabellen.

    Om du får timeout-fel kontrollerar du att du har uppdaterat anslutningsinformationen på rätt sätt i Uppdatera din anslutningsinformation. Prova även att köra det senaste kommandot igen.

    När programmet har slutat arbeta trycker du på Retur och växlar sedan tillbaka till Azure Portal i webbläsaren.

Granska och lägg till exempeldata

När hörnen och kanterna har infogats kan du nu gå tillbaka till Data Explorer och se hörnen som lagts till i diagrammet och lägga till ytterligare datapunkter.

  1. I ditt Azure Cosmos DB-konto i Azure Portal väljer du Data Explorer, expanderar sample-graph, väljer Graph och väljer sedan Använd filter.

    Screenshot shows Graph selected from the A P I with the option to Apply Filter.

  2. Observera att tre nya användare läggs till i diagrammet i resultatlistan. Du kan flytta hörnen genom att dra och släppa, zooma in och ut genom att bläddra med mushjulet, och utöka diagrammets storlek med hjälp av dubbelpilen.

    New vertices in the graph in Data Explorer in the Azure portal

  3. Vi ska nu lägga till några nya användare. Välj knappen Nytt hörn för att lägga till data i diagrammet.

    Screenshot shows the New Vertex pane where you can enter values.

  4. Ange en etikett för person.

  5. Välj Lägg till egenskap för att lägga till var och en av följande egenskaper. Tänk på att du kan skapa unika egenskaper för varje person i grafen. Endast id-nyckeln krävs.

    key värde Kommentarer
    Pk /pk
    id ashley Den unika identifieraren för hörnet. Om du inte anger något id skapas ett automatiskt.
    kön kvinna
    teknik Java

    Anteckning

    I den här snabbstartsguiden skapar vi en icke-partitionerad samling. Men om du skapar en partitionerad samling genom att ange en partitionsnyckel när samlingen skapas, måste du lägga till partitionsnyckeln som nyckel i varje nytt hörn.

  6. Välj OK. Du kan behöva expandera skärmen för att se OK längst ned på skärmen.

  7. Välj Nytt hörn igen och lägg till ytterligare en ny användare.

  8. Ange en etikett för person.

  9. Välj Lägg till egenskap för att lägga till var och en av följande egenskaper:

    key värde Kommentarer
    Pk /pk
    id rakesh Den unika identifieraren för hörnet. Om du inte anger något id skapas ett automatiskt.
    kön man
    skola MIT
  10. Välj OK.

  11. Välj knappen Använd filter med standardfiltret g.V() för att visa alla värden i diagrammet. Nu visas alla användare i listan Resultat.

    Allteftersom du lägger till data kan du använda filter för att begränsa resultaten. Som standard använder Datautforskaren g.V() för att hämta alla hörnen i ett diagram. Du kan ändra till en annan diagramfråga, t.ex. g.V().count(), för att returnera en uppräkning av alla hörn i diagrammet i JSON-format. Om du har ändrat filtret ändrar du tillbaka filtret till g.V() och väljer Använd filter för att visa alla resultat igen.

  12. Nu kan vi koppla ihop Rakesh och Ashley. Se till att ashley har valts i resultatlistan och välj sedan redigeringsknappen bredvid Mål längst ned till höger. Du kan behöva bredda fönstret för att se området Egenskaper.

    Change the target of a vertex in a graph

  13. I rutan Mål skriver du rakesh och i rutan Edge-etikett skriver du vet och markerar sedan kryssrutan.

    Add a connection between ashley and rakesh in Data Explorer

  14. Markera nu rakesh i resultatlistan och se att Ashley och Rakesh är anslutna.

    Two vertices connected in Data Explorer

Då är delen om att skapa resurser slutförd i den här självstudien. Du kan fortsätta att lägga till hörn i diagrammet, ändra befintliga hörn eller ändra frågorna. Vi ska nu titta på de mått som Azure Cosmos DB tillhandahåller, och sedan ska vi rensa resurserna.

Granska serviceavtal i Azure-portalen

Azure Portal övervakar dataflöde, lagring, tillgänglighet, svarstid och konsekvens för Ditt Cosmos DB-konto. Diagram för mått som är associerade med ett serviceavtal för Azure Cosmos DB (SLA) visar SLA-värdet jämfört med faktiska prestanda. Den här måttsviten gör övervakningen av serviceavtalen 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 metrics suite

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

Rensa resurser

När du är klar med din app och ditt 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 Azure Portal sökfältet söker du efter och väljer Resursgrupper.

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

    Select the resource group to delete

  3. resursgruppens översiktssida väljer du Ta bort resursgrupp.

    Delete the resource group

  4. I nästa fönster anger du namnet på resursgruppen 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-konto, skapar en graf med hjälp av Data Explorer och kör en Python-app för att lägga till data i diagrammet. Nu kan du skapa mer komplexa frågor och implementera kraftfull logik för grafbläddring med Gremlin.