Snelstart: een Python-toepassing maken met een Azure Cosmos DB SQL API-account

VAN TOEPASSING OP: SQL API

In deze quickstart maakt en beheert u een Azure Cosmos DB SQL API-account vanuit de Azure-portal en van Visual Studio Code met een Python-app die is gekloond vanuit GitHub. Azure Cosmos DB is een databaseservice met meerdere modellen waarmee u snel document-, tabel-, sleutel-waarde- en grafiekdatabases kunt maken en query's kunt maken met globale distributie- en horizontale schaalmogelijkheden.

Vereisten

Belangrijke update voor Ondersteuning voor Python 2.x

Nieuwe versies van deze SDK ondersteunen Python 2.x vanaf 1 januari 2022 niet. Controleer de CHANGELOG voor meer informatie.

Een databaseaccount maken

  1. Selecteer in het menu Azure Portal of de startpaginade optie Een resource maken.

  2. Zoek op de pagina Nieuw naar Azure Cosmos DBen selecteer deze.

  3. Selecteer op de pagina Azure Cosmos DB de optie Maken.

  4. Voer op de pagina Azure Cosmos DB-account maken de basisinstellingen in voor het nieuwe Azure Cosmos-account.

    Instelling Waarde Beschrijving
    Abonnement Abonnementsnaam Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos-account.
    Resourcegroep Naam van resourcegroep Selecteer een resourcegroep of selecteer Nieuw makenen voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Accountnaam Een unieke naam Voer een naam in om uw Azure Cosmos-account te identificeren. Omdat documents.azure.com wordt toegevoegd aan de naam die u op geeft om uw URI te maken, gebruikt u een unieke naam.

    De naam kan alleen kleine letters, cijfers en het afbreekstreester (-) bevatten. De lengte moet tussen de 3 en 44 tekens zijn.
    API Het type account dat u wilt maken Selecteer Kern (SQL) om een documentdatabase en query te maken met behulp van SQL syntaxis.

    De API bepaalt het type account dat u wilt maken. Azure Cosmos DB biedt vijf API's: Core (SQL) en MongoDB voor documentgegevens, Gremlin voor grafiekgegevens, Azure Table en Cassandra. Op dit moment moet u voor elke API een afzonderlijk account maken.

    Meer informatie over de SQL API.
    Locatie De regio die het dichtst bij uw gebruikers staat Selecteer een geografische locatie om uw Azure Cosmos DB-account te hosten. Gebruik de locatie die het dichtst bij uw gebruikers staat om ze de snelste toegang tot de gegevens te geven.
    Capaciteitsmodus Inrichtende doorvoer of Serverless Selecteer Inrichtende doorvoer om een account te maken in de inrichtende doorvoermodus. Selecteer Serverloos om een account te maken in de serverloze modus.
    Azure Cosmos DB free tier discount toepassen Toepassen of Niet toepassen Met de gratis Azure Cosmos DB-laag krijgt u de eerste 1000 RU/s en 25 GB opslagruimte gratis in een account. Meer informatie over de gratis laag.

    Opmerking

    U kunt maximaal één gratis Azure Cosmos DB-account per Azure-abonnement hebben en u moet zich opgeven wanneer u het account maakt. Als u de optie voor het toepassen van de gratis laagkorting niet ziet, betekent dit dat een ander account in het abonnement al is ingeschakeld met een gratis laag.

    De nieuwe accountpagina voor Azure Cosmos DB

  5. Configureer de volgende details op het tabblad Globale distributie. U kunt de standaardwaarden laten voor het doel van deze snelstart:

    Instelling Waarde Beschrijving
    Geo-Redundancy Uitschakelen Schakel de globale distributie van uw account in of uit door uw regio te koppelen aan een paarregio. U kunt later meer regio's aan uw account toevoegen.
    Schrijft in meerdere regio's Uitschakelen Met de functie voor schrijven in meerdere regio's kunt u profiteren van de inrichtende doorvoer voor uw databases en containers over de hele wereld.

    Opmerking

    De volgende opties zijn niet beschikbaar als u Serverless selecteert als de capaciteitsmodus:

    • Gratis laagkorting toepassen
    • Geo-redundantie
    • Schrijft in meerdere regio's
  6. Desgewenst kunt u aanvullende details configureren op de volgende tabbladen:

  7. Selecteer Controleren + maken.

  8. Controleer de accountinstellingen en selecteer vervolgens Maken. Het maken van het account duurt enkele minuten. Wacht totdat de portalpagina wordt weergegeven Uw implementatie is voltooid.

    Het deelvenster Meldingen van Azure Portal

  9. Selecteer Ga naar resource om naar de accountpagina van Azure Cosmos DB te gaan.

    De pagina Azure Cosmos DB-account

Een container toevoegen

U kunt nu het hulpprogramma Gegevensverkenner in de Azure-portal gebruiken om een database en container te maken.

  1. Selecteer Nieuwe container voor Gegevensverkenner.

    Het gebied Container toevoegen wordt rechts weergegeven, mogelijk moet u naar rechts schuiven om het te zien.

    Het deelvenster Container toevoegen in de Azure Portal Data Explorer

  2. Voer op de pagina Container toevoegen de instellingen in voor de nieuwe container.

    Instelling Voorgestelde waarde Beschrijving
    Database-id ToDoList Voer Taken in als de naam voor de nieuwe database. Databasenamen moeten 1 tot 255 tekens bevatten en mogen geen /, \\, #, ? achterruimte bevatten. Controleer de optie Doorvoer tussen containers delen, zodat u de doorvoer in de database kunt delen in alle containers in de database. Deze optie helpt ook bij het besparen van kosten.
    Databasedoorvoer U kunt autoschaal of handmatige doorvoer inrichten. Met handmatige doorvoer kunt u ru/s zelf schalen, terwijl met de autoscale-doorvoer het systeem ru/s kan schalen op basis van gebruik. Selecteer Handmatig voor dit voorbeeld.

    Laat de doorvoer bij 400 aanvraageenheden per seconde (RU/s) achter. Als u de latentie wilt verminderen, kunt u de doorvoer later opschalen door de vereiste RU/s te schatten met de capaciteitscalculator.

    Opmerking:Deze instelling is niet beschikbaar bij het maken van een nieuwe container in een serverloos account.
    Container-id Items Voer Items in als de naam voor uw nieuwe container. Container-ID's hebben dezelfde tekenvereisten als databasenamen.
    Partitietoets /categorie In het voorbeeld dat in dit artikel wordt beschreven, wordt /categorie als partitiesleutel gebruikt.

    Voeg voor dit voorbeeld geen unieke sleutels toe of schakel Analytisch winkel in. Met unieke sleutels kunt u een laag gegevensintegriteit toevoegen aan de database door ervoor te zorgen dat een of meer waarden per partitiesleutel uniek zijn. Zie Unieke sleutels in Azure Cosmos DB voor meer informatie. Analytical Store wordt gebruikt om grootschalige analyses in te stellen tegen operationele gegevens zonder dat dit gevolgen heeft voor uw transactionele werkbelastingen.

    Selecteer OK. In de Gegevensverkenner worden de nieuwe database en container weergegeven.

Voorbeeldgegevens toevoegen

U kunt nu gegevens toevoegen aan uw nieuwe container met Data Explorer.

  1. Vouw in de Gegevensverkennerde database Taken uit en vouw de container Items uit. Selecteer Itemsen selecteer vervolgens Nieuw item.

    Nieuwe documenten maken in Data Explorer in de Azure-portal

  2. Voeg nu een document toe aan de container met de volgende structuur.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Nadat u het json hebt toegevoegd aan het tabblad Documenten, selecteert u Opslaan.

    Kopieer in json-gegevens en selecteer Opslaan in Gegevensverkenner in de Azure-portal

  4. Maak en sla nog een document op waar u een unieke waarde voor de eigenschap invoegt en wijzig de andere eigenschappen naar eigen id goedheid. Uw nieuwe documenten kunnen elke structuur hebben die u wilt, omdat Azure Cosmos DB geen schema voor uw gegevens oplegt.

Query's uitvoeren op uw gegevens

U kunt query's in Gegevensverkenner gebruiken om uw gegevens op te halen en te filteren.

  1. Controleer de standaardquery boven aan het tabblad Items in Gegevensverkenner. Met deze query worden alle documenten opgehaald en weergegeven uit de container die op id is besteld.

    Standaardquery in Gegevensverkenner is SELECT * VAN c

  2. Als u de query wilt wijzigen, selecteert u Filter bewerken,vervangt u de standaardquery door en selecteert u Filter toepassen.

    De standaardquery wijzigen door ORDER BY toe te voegen c._ts DESC en op Filter toepassen te klikken

    Met de gewijzigde query worden de documenten in aflopende volgorde weergegeven op basis van hun tijdstempel, zodat uw tweede document nu eerst wordt weergegeven.

    Query gewijzigd in ORDER BY c._ts DESC en klik op Filter toepassen

Als u bekend bent met SQL syntaxis, kunt u ondersteunde SQL query's in het vak querypredicaat invoeren. U kunt Gegevensverkenner ook gebruiken om opgeslagen procedures, UDF's en triggers te maken voor bedrijfslogica aan de serverzijde.

Data Explorer biedt eenvoudige toegang tot de Azure-portal tot alle ingebouwde programmatische functies voor gegevenstoegang die beschikbaar zijn in de API's. U gebruikt de portal ook om de doorvoer te schalen, sleutels en verbindingsreeksen op te halen en meetgegevens en SLA's voor uw Azure Cosmos DB-account te bekijken.

De voorbeeldtoepassing kloonen

Laten we nu een api-app SQL van GitHub, de verbindingsreeks instellen en uitvoeren. Deze quickstart maakt gebruik van versie 4 van de Python SDK.

  1. Open een opdrachtprompt, maak een nieuwe map met de naam git-samples en sluit de opdrachtprompt.

    md git-samples
    

    Als u een bashprompt gebruikt, gebruikt u in plaats daarvan de volgende opdracht:

    mkdir "git-samples"
    
  2. Open een git terminal-venster, zoals git bash, en gebruik de opdracht om over te gaan naar de cd nieuwe map om de voorbeeld-app te installeren.

    cd "git-samples"
    
  3. Voer de volgende opdracht uit om de voorbeeldopslagplaats te kloonen. Met deze opdracht maakt u een kopie van de voorbeeld-app op uw computer.

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

De verbindingsreeks bijwerken

Ga nu terug naar de Azure-portal om de verbindingsreeksgegevens op te halen en naar de app te kopiëren.

  1. Selecteer in uw Azure Cosmos DB-account in de Azure-portalde optie Sleutels in de linkernavigatie. Gebruik de kopieerknoppen aan de rechterkant van het scherm om de URI en primaire sleutel in het cosmos_get_started.py-bestand te kopiëren in de volgende stap.

    Een toegangssleutel en URI downloaden in de instellingen voor sleutels in de Azure-portal

  2. Open in Visual Studio Code het cosmos_get_started.py-bestand in \git-samples\azure-cosmos-db-python-getting-started.

  3. Kopieer de URI-waarde vanuit de portal (met behulp van de kopieerknop) en maak deze de waarde van de eindpuntvariabele in cosmos_get_started.py.

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

  4. Kopieer vervolgens de PRIMAIRE SLEUTEL-waarde vanuit de portal en maak deze de waarde van de sleutel in cosmos_get_started.py. U hebt de app nu bijgewerkt met alle informatie die nodig is om te communiceren met Azure Cosmos DB.

    key = 'FILLME'

  5. Sla het cosmos_get_started.py-bestand op.

De code controleren

Deze stap is optioneel. Lees meer over de databasebronnen die in code zijn gemaakt of ga verder met De verbindingsreeks bijwerken.

De volgende fragmenten worden allemaal uit het cosmos_get_started.py-bestand genomen.

  • De CosmosClient wordt ge initialiseerd. Zorg ervoor dat u de waarden 'eindpunt' en 'sleutel' bij werk, zoals beschreven in de sectie Verbindingsreeks bijwerken.

    client = CosmosClient(endpoint, key)
    
  • Er wordt een nieuwe database gemaakt.

    database_name = 'AzureSampleFamilyDatabase'
    database = client.create_database_if_not_exists(id=database_name)
    
  • Er wordt een nieuwe container gemaakt, met 400 RU/s van de inrichtende doorvoer. We kiezen lastName als de lastNamewaarmee we efficiënte query's kunnen uitvoeren die filteren op deze eigenschap.

    container_name = 'FamilyContainer'
    container = database.create_container_if_not_exists(
        id=container_name, 
        partition_key=PartitionKey(path="/lastName"),
        offer_throughput=400
    )
    
  • Sommige items worden toegevoegd aan de container. Containers zijn een verzameling items (JSON-documenten) die een gevarieerd schema kunnen hebben. Met de helpermethoden get_[name]_family_item worden afbeeldingen van een gezin dat is opgeslagen in Azure Cosmos DB als JSON-documenten, als retourneert.

    for family_item in family_items_to_create:
        container.create_item(body=family_item)
    
  • Point reads (key value lookups) worden uitgevoerd met behulp van de read_item methode. De ru-kosten van elke bewerking worden afgedrukt.

    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)))
    
  • Een query wordt uitgevoerd met SQL query-syntaxis. Omdat we partitiesleutelwaarden van de WHERE-component gebruiken, wordt deze query efficiënt door Azure Cosmos DB naar de relevante partities gerouteerd, waardoor de prestaties lastName worden verbeterd.

    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))
    

De app uitvoeren

  1. Selecteer Visual Studio Opdrachtpaletweergeven in Visual Studio code.

  2. Voer bij de prompt Python: Selecteer Tolk en selecteer vervolgens de versie van Python die u wilt gebruiken.

    De voettekst in Visual Studio code wordt bijgewerkt om aan te geven welke tolk is geselecteerd.

  3. Selecteer Geïntegreerdeterminal weergeven om de geïntegreerde Visual Studio code te openen.

  4. Zorg ervoor dat u zich in het geïntegreerde terminalvenster in de map azure-cosmos-db-python-getting-started kunt vinden. Zo niet, voer dan de volgende opdracht uit om over te schakelen naar de voorbeeldmap.

    cd "\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. Voer de volgende opdracht uit om het azure-cosmos-pakket te installeren.

    pip install --pre azure-cosmos
    

    Als u een foutmelding krijgt over toegang die wordt geweigerd bij het installeren van azure-cosmos, moet u VS-codeuitvoeren als een beheerder.

  6. Voer de volgende opdracht uit om het voorbeeld uit te voeren en nieuwe documenten te maken en op te slaan in Azure Cosmos DB.

    python cosmos_get_started.py
    
  7. Als u wilt bevestigen dat de nieuwe items zijn gemaakt en opgeslagen, selecteert u in de Azure-portal GegevensverkennerAzureSampleFamilyDatabase-items. Bekijk de items die zijn gemaakt. Hier is bijvoorbeeld een voorbeeld JSON-document voor de andersen-familie:

    {
        "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
    }
    

SLA's controleren in de Azure-portal

De Azure-portal controleert de doorvoer, opslag, beschikbaarheid, latentie en consistentie van uw Cosmos DB-account. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) geven de SLA-waarde weer ten opzichte van de werkelijke prestaties. Deze suite met metrische gegevens maakt het bewaken van uw SLA's transparant.

Metrische gegevens en SLA's bekijken:

  1. Selecteer Metrische gegevens in het navigatiemenu van uw Cosmos DB-account.

  2. Selecteer een tabblad, zoals Latentie,en selecteer een tijdsbestek aan de rechterkant. Vergelijk de regels Werkelijke en SLA in de grafieken.

    Azure Cosmos DB metrics suite

  3. Bekijk de metrische gegevens op de andere tabbladen.

Resources ops schonen

Wanneer u klaar bent met uw app en Azure Cosmos DB-account, kunt u de Azure-resources verwijderen die u hebt gemaakt, zodat u niet meer kosten hoeft te maken. De resources verwijderen:

  1. Zoek in de zoekbalk van de Azure Portal naar Resourcegroepen en selecteer deze.

  2. Selecteer in de lijst de resourcegroep die u voor deze quickstart hebt gemaakt.

    Selecteer de resourcegroep die u wilt verwijderen

  3. Selecteer op de pagina Overzicht van de resourcegroep de optie Resourcegroep verwijderen.

    De resourcegroep verwijderen

  4. Voer in het volgende venster de naam in van de resourcegroep die u wilt verwijderen en selecteer Vervolgens Verwijderen.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB-account kunt maken, een container kunt maken met de Gegevensverkenner en een Python-app kunt uitvoeren in Visual Studio Code. U kunt nu extra gegevens importeren in uw Azure Cosmos DB-account.

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.

  • Als u alleen het aantal vcores en servers in uw bestaande databasecluster weet, leest u over het schatten van aanvraageenheden met vCores of vCPUs
  • Als u de gebruikelijke aanvraagtarieven voor uw huidige databasewerkbelasting kent, leest u meer over het schatten van aanvraageenheden met behulp van De capaciteitsplanner van Azure Cosmos DB