Snabbstart: Skapa ett Python-program med ett Azure Azure Azure Db SQL API-konto

GÄLLER FÖR: SQL API

I den här snabbstarten kan du skapa och hantera ett Azure Azures DB SQL API-konto från Azure-portalen och från Visual Studio-kod med en Python-app klonad från GitHub. Azure Azure Azures DB är en databastjänst med flera modeller som gör att du snabbt kan skapa och frågedokument, tabeller, nyckelvärden och grafdatabaser med globala distributionsfunktioner och vågräta skalfunktioner.

Krav

Viktig uppdatering för Python 2.x-support

Nya versioner av det här SDK stöder inte Python 2.x från och med 1 januari 2022. Mer information finns i CHANGELOG.

Skapa ett databaskonto

  1. På Azure Portal-menyn eller startsidan väljerdu Skapa en resurs.

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

  3. Välj Skapa på sidan Azure Azure Azures DB.

  4. Ange de grundläggande inställningarna för det nya Azure Azures DB-kontot på sidan Create Azure Azure Azures DB Account.

    Inställning Värde Beskrivning
    Prenumeration Prenumerationsnamn Välj den Azure-prenumeration som du vill använda för det här Azure Azure-kontot.
    Resursgrupp Resursgruppnamn Välj en resursgrupp eller välj Skapa nyoch ange sedan ett unikt namn för den nya resursgruppen.
    Kontonamn Ett unikt namn Ange ett namn för att identifiera ditt Azure Azure Azure-konto. Använd documents.azure.com ett unikt namn eftersom den läggs till i namnet som du anger för att skapa din URI.

    Namnet får endast innehålla gemener, siffror och bindestreck (-). Den måste vara mellan 3 och 44 tecken lång.
    API Typen av konto som ska skapas Välj Bas (SQL) för att skapa en dokumentdatabas och fråga med hjälp av SQL syntax.

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

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

    Obs!

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

    Den nya kontosidan för Azure Azure Azures DB

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

    Inställning Värde Beskrivning
    Geo-Redundancy Inaktivera Aktivera eller inaktivera global distribution på ditt konto genom att koppla ihop regionen med en parregion. Du kan lägga till fler regioner i ditt konto senare.
    Skriver flera regioner Inaktivera Med funktionen för flera regioner kan du dra nytta av det etablerade dataflödet för dina databaser och behållare över hela världen.

    Obs!

    Följande alternativ är inte tillgängliga om du väljer Serverless som kapacitetsläge:

    • Använd kostnadsfri nivårabatt
    • Georedundans
    • Skriver flera regioner
  6. Du kan även konfigurera ytterligare information på följande flikar:

  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 Distributionen är klar.

    Azure Portal Notifications-fönstret

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

    Kontosidan Azure Azure Azures DB

Lägga till en behållare

Nu kan du använda verktyget Datautforskaren i Azure-portalen för att skapa en databas och behållare.

  1. Välj Ny behållare iDatautforskaren.

    Området Lägg till behållare visas längst till höger och du kan behöva rulla till höger för att se det.

    Azure Portal Data Explorer, fönstret Lägg till behållare

  2. På sidan Lägg till behållare anger du inställningarna för den nya behållaren.

    Inställning Föreslaget värde Beskrivning
    Databas-ID ToDoList Ange Uppgifter som namn på den nya databasen. Databasnamn måste innehålla mellan 1 och 255 tecken och får inte innehålla /, \\, #, ? , eller ett avslutande blanksteg. Kontrollera alternativet Dela dataflöde mellan behållare så kan du dela dataflödet som är etablerat i databasen över alla behållare i databasen. Det här alternativet hjälper också till med kostnadsbesparingar.
    Dataflöde för databas Du kan tillhandahålla automatisk skalningeller manuellt dataflöde. Med manuellt dataflöde kan du skala RU/s själv medan automatiskt skalningsflöde gör att systemet kan skala RU/s baserat på användning. Välj Manuellt för det här exemplet.

    Lämna dataflödet på 400 begärandeenheter 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 behållare i ett serverlöst konto.
    Behållar-ID Artiklar Ange Objekt som namn på den nya behållaren. Behållar-ID har samma teckenkrav som databasnamn.
    Partitionsnyckel /kategori Exemplet som beskrivs i den här artikeln använder /kategori som partitionsnyckel.

    Lägg inte till Unika nycklar eller aktivera Analytical store för det här exemplet. Med unika nycklar kan du lägga till ett lager med dataintegritet i databasen genom att säkerställa att ett eller flera värden per partitionsnyckel är unika. Mer information finns i Unika nycklar i Azure Azure Azures DB.Analytisk lagring används för att möjliggöra omfattande analys mot driftdata utan någon inverkan på dina transaktionsarbetsbelastningar.

    Välj OK. Datautforskaren visar den nya databasen och behållaren.

Lägga till exempeldata

Nu kan du lägga till data i den nya behållaren med hjälp av Datautforskaren.

  1. Expandera uppgiftsdatabaseni Datautforskaren och expandera behållaren Objekt. Välj Objektoch välj sedan Nytt objekt.

    Skapa nya dokument i Datautforskaren i Azure-portalen

  2. Lägg till ett dokument i behållaren 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 i json data och välj Spara i Datautforskaren i Azure Portal

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

Skapa frågor för dina data

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

  1. Granska standardfrågan högst upp på fliken Objekt i Datautforskaren. Den här frågan hämtar och visar alla dokument från behållaren ordnade 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 och väljer sedan Använd filter.

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

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

    Ändrade frågan till ORDER BY c._ts DESC och klicka på Använd filter

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

Data Explorer ger enkel Azure Portal åtkomst till alla inbyggda programmässiga dataåtkomstfunktioner som är tillgängliga i API:er. Du kan även använda portalen för att skala dataflöde, hämta nycklar och anslutningssträngar samt granska mätvärden och SLA:er för ditt Azure Azure Azure Db-konto.

Klona exempelprogrammet

Nu ska vi klona en SQL API-app från GitHub, ange anslutningssträngen och köra den. Den här snabbstarten använder version 4 av Python SDK.

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

    md git-samples
    

    Om du använder en bash-fråga bör du i stället använda följande kommando:

    mkdir "git-samples"
    
  2. Öppna ett git terminal-fönster, till exempel git bash, och använd kommandot för att byta till cd den nya mappen för att installera exempelappen.

    cd "git-samples"
    
  3. Kör följande kommando för att klona exempelarkivet. Med det här kommandot skapas en kopia av exempelappen på datorn.

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

Uppdatera anslutningssträngen

Gå nu tillbaka till Azure Portal för att hämta information om anslutningssträngen och kopiera in den i appen.

  1. I ditt Azure Azures DB-konto i Azure-portalenväljer du Nycklar i det vänstra navigeringsfältet. Använd kopieringsknapparna till höger på skärmen för att kopiera URI-och primärnyckeln till filen cosmos_get_started.py i nästa steg.

    Få en snabbtangent och URI i tangentinställningarna i Azure Portal

  2. I Visual Studio öppnar du filen cosmos_get_started.py i \git-samples\azure-azure-azures-db-python-getting-started.

  3. Kopiera URI-värdet från portalen (med knappen Kopiera) och gör det till värdet på slutpunktsvariabeln i cosmos_get_started.py.

    endpoint = 'https://FILLME.documents.azure.com',

  4. Kopiera sedan PRIMÄRNYCKEL-värdet från portalen och gör det till nyckelns värde icosmos_get_started.py. Nu har du uppdaterat appen med all information som behövs för att kommunicera med Azure Azure Azures DB.

    key = 'FILLME'

  5. Spara filen cosmos_get_started.py.

Granska koden

Det här steget är valfritt. Lär dig mer om databasresurser som skapats med kod, eller gå vidare till Uppdatera anslutningssträngen.

Följande avsnitt är alla tagna från filen cosmos_get_started.py.

  • Så här initieras Hansson. Uppdatera värdena "slutpunkt" och "nyckel" enligt beskrivningen i avsnittet Uppdatera anslutningssträngen.

    client = CosmosClient(endpoint, key)
    
  • En ny databas skapas.

    database_name = 'AzureSampleFamilyDatabase'
    database = client.create_database_if_not_exists(id=database_name)
    
  • En ny behållare skapas med 400 RU/s av etablerat dataflöde. Vi väljer lastName som lastNamevilket gör att vi kan göra effektiva frågor som filtrerar på den här egenskapen.

    container_name = 'FamilyContainer'
    container = database.create_container_if_not_exists(
        id=container_name, 
        partition_key=PartitionKey(path="/lastName"),
        offer_throughput=400
    )
    
  • Vissa objekt läggs till i behållaren. Behållare är en samling objekt (JSON-dokument) som kan ha olika schema. Hjälpmetoderna get_[name]_family_item returnerar representationer av en familj som lagras i Azure Azure Azures DB som JSON-dokument.

    for family_item in family_items_to_create:
        container.create_item(body=family_item)
    
  • Point reads (key value lookups) utförs med read_item metoden. Vi skriver ut RU-debitering för varje åtgärd.

    for family in family_items_to_create:
        item_response = container.read_item(item=family['id'], partition_key=family['lastName'])
        request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
        print('Read item with id {0}. Operation consumed {1} request units'.format(item_response['id'], (request_charge)))
    
  • En fråga utförs med hjälp SQL frågesyntax. Eftersom vi använder partitionsnyckelvärden för i WHERE-satsen dirigerar Azure Azure Azures DB effektivt den här frågan till relevanta lastName partitioner, vilket förbättrar prestanda.

    query = "SELECT * FROM c WHERE c.lastName IN ('Wakefield', 'Andersen')"
    
    items = list(container.query_items(
        query=query,
        enable_cross_partition_query=True
    ))
    
    request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
    
    print('Query returned {0} items. Operation consumed {1} request units'.format(len(items), request_charge))
    

Köra appen

  1. I Visual Studio väljer du Visa kommandopalett.

  2. När du uppmanas till det anger du Python: Välj tolkar och väljer den version av Python som ska användas.

    Sidfoten i Visual Studio uppdateras för att ange vilken tolkar som valts.

  3. Välj Visaintegrerad terminal för att öppna Visual Studio kod integrerad terminal.

  4. Kontrollera att du befinner dig i mappen azure-azure-azures-db-python-getting-started i det integrerade terminalfönstret. Om inte, kör du följande kommando för att växla till exempelmappen.

    cd "\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. Kör följande kommando för att installera azure-azures-paketet.

    pip install --pre azure-cosmos
    

    Om du får ett felmeddelande om att åtkomst nekas när du försöker installera azure-azure-azure-enkels, måste du köra VS-kod som administratör.

  6. Kör följande kommando för att köra exemplet och skapa och lagra nya dokument i Azure Azure Azures DB.

    python cosmos_get_started.py
    
  7. Bekräfta att de nya objekten skapades och sparades genom att välja Data ExplorerAzureSampleFamilyDatabaseItems i Azure-portalen. Visa de objekt som har skapats. Här är till exempel ett JSON-exempeldokument för Andersen-familjen:

    {
        "id": "Andersen-1569479288379",
        "lastName": "Andersen",
        "district": "WA5",
        "parents": [
            {
                "familyName": null,
                "firstName": "Thomas"
            },
            {
                "familyName": null,
                "firstName": "Mary Kay"
            }
        ],
        "children": null,
        "address": {
            "state": "WA",
            "county": "King",
            "city": "Seattle"
        },
        "registered": true,
        "_rid": "8K5qAIYtZXeBhB4AAAAAAA==",
        "_self": "dbs/8K5qAA==/colls/8K5qAIYtZXc=/docs/8K5qAIYtZXeBhB4AAAAAAA==/",
        "_etag": "\"a3004d78-0000-0800-0000-5d8c5a780000\"",
        "_attachments": "attachments/",
        "_ts": 1569479288
    }
    

Granska SLA:er i Azure Portal

Azure Portal övervakar dataflödet för ditt Db-konto, lagring, tillgänglighet, svarstid och konsekvens. Diagram för mätvärden kopplade till azure Azures DB Service Level Agreement (SLA) visar SLA-värdet jämfört med faktiska prestanda. Den här uppsättning mätvärden gör att du kan övervaka dina SLA:er transparenta.

Så här granskar du mätvärden och SLA:er:

  1. Välj Mått i Db-kontots navigeringsmeny för ditt Db-konto.

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

    Azure Azure Azures DB metrics suite

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

Rensa resurser

När du är klar med appen och Azure Azure Azures DB-konto kan du ta bort de Azure-resurser du skapat så att du inte tillkommer fler avgifter. Så här tar du bort resurserna:

  1. Sök efter och välj Resursgrupper i Azure Portal-sökfältet.

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

    Markera den resursgrupp du vill ta bort

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

    Ta bort resursgruppen

  4. I nästa fönster anger du namnet på den resursgrupp du vill ta 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 Azure Azures DB-konto, skapar en behållare med datautforskaren och kör en Python-app i Visual Studio Kod. Nu kan du importera ytterligare data till ditt Azure Azure Azure Db-konto.

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