Quickstart: Node.js gebruiken om verbinding te maken en gegevens op te vragen uit Azure Cosmos DB SQL-API-account

Artikel
11/24/2021
8 minuten om te lezen

VAN TOEPASSING OP: SQL-API

In deze quickstart maakt en beheert u een SQL API-account van Azure Cosmos DB via de Azure-portal en met een Node.js-app die is gekloond van GitHub. Met Azure Cosmos DB, een databaseservice met meerdere modellen, kunt u snel databases met documenten, tabellen, sleutelwaarden en grafieken maken en hier query's op uitvoeren. Deze databases hebben wereldwijde distributie en horizontale schaalmogelijkheden.

Walkthrough-video

Bekijk deze video voor een volledig overzicht van de inhoud in dit artikel.

Vereisten

Een Azure-account met een actief abonnement. Maak er gratis een. Of probeer Azure Cosmos DB gratis zonder Azure-abonnement. U kunt ook de Azure Cosmos DB Emulator gebruiken met een URI van https://localhost:8081 en de sleutel C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==.
Node.js 6.0.0+.
Git.

Een Azure Cosmos-account maken

Voor deze quickstart kunt u de optie Azure Cosmos DB gratis uitproberen gebruiken om een Azure Cosmos-account te maken.

Ga naar de pagina Azure Cosmos DB gratis uitproberen.
Kies het SQL-API-account en selecteer Maken. Aanmelden met uw Microsoft-account.
Nadat het aanmelden is gelukt, moet uw Azure Cosmos-account gereed zijn. Selecteer Openen in het Azure-portal om het zojuist gemaakte account te openen.

Voor de optie "Probeer Azure Cosmos DB gratis" hebt u geen Azure-abonnement nodig en deze optie biedt u een Azure Cosmos-account voor een beperkte periode van 30 dagen. Als u de Azure Cosmos-account langer wilt gebruiken, moet u de account maken in uw Azure-abonnement.

Een container toevoegen

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

Selecteer Data Explorer > Nieuwe container.

Uiterst rechts wordt het gedeelte Container toevoegen weergegeven. Mogelijk moet u naar rechts scrollen om het te kunnen zien.

Geef op de pagina Container toevoegen de instellingen voor de nieuwe container op.

Instelling	Voorgestelde waarde	Beschrijving
Database-id	Takenlijst	Voer Taken in als de naam voor de nieuwe database. Databasenamen moeten tussen de 1 en 255 tekens zijn en mogen geen `/, \\, #, ?` bevatten en mogen niet eindigen met een spatie. Controleer de optie Doorvoer tussen containers delen. Hiermee kunt u de doorvoer die is ingericht op de database delen in alle containers in de database. Met deze optie bespaart u bovendien op de kosten.
Databasedoorvoer	U kunt automatisch schalen of handmatige doorvoer inrichten. Met handmatige doorvoer kunt u RU/s zelf schalen, terwijl de doorvoer automatisch schalen het systeem in staat stelt RU/s te schalen op basis van gebruik. Selecteer Handmatig voor dit voorbeeld. Wijzig de doorvoer in 400 aanvraageenheden per seconde (RU/s). Als u de latentie wilt verminderen, kunt u de doorvoer later omhoog schalen 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 de nieuwe container. Voor id's van containers gelden dezelfde tekenvereisten als voor databasenamen.
Partitiesleutel	/category	In het voorbeeld dat in dit artikel wordt beschreven, wordt /category als de partitiesleutel gebruikt.

Voeg voor dit voorbeeld geen unieke sleutels toe of schakel Analytische opslag niet in. Met unieke sleutels kunt u een laag van gegevensintegriteit toevoegen aan de database door de uniekheid van een of meer waarden per partitiesleutel te garanderen. Zie Unieke sleutels in Azure Cosmos DB. Analytische opslag wordt gebruikt om grootschalige analyses in te stellen op basis van operationele gegevens zonder dat dit van invloed is op uw transactionele workloads.

Selecteer OK. In Data Explorer worden de nieuwe database en container weergegeven.

Voorbeeldgegevens toevoegen

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

Vouw in Data Explorer de database Taken uit en vouw de container Items uit. Selecteer Items en vervolgens Nieuw item.

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

{
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}

Zodra u de JSON hebt toegevoegd aan het tabblad Documenten, selecteert u Opslaan.
Maak nog één document en sla dit op. In het document voegt u een unieke waarde toe voor de eigenschap id. Wijzig de andere eigenschappen naar eigen inzicht. De nieuwe documenten kunnen elke gewenste structuur hebben, omdat in Azure Cosmos DB uw gegevens geen schema krijgen opgelegd.

Uw gegevens opvragen

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

Controleer bovenaan het tabblad Items in Data Explorer de standaardquery SELECT * FROM c. Met deze query worden alle documenten opgehaald uit de container en weergegeven op volgorde van id.
Als u de query wilt wijzigen, selecteert u Filter bewerken, vervangt u de standaardquery door ORDER BY c._ts DESC en selecteert u Filter toepassen.

De gewijzigde query sorteert de documenten in aflopende volgorde op basis van hun tijdstempel. Uw tweede document wordt nu dus als eerste weergegeven.

Als u bekend bent met SQL-syntaxis, kunt u een van de ondersteunde SQL-query's in het vak Querypredicaat invoeren. U kunt Data Explorer ook gebruiken voor het maken van opgeslagen procedures, UDF's en triggers om bedrijfslogica aan de serverzijde uit te voeren.

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

De voorbeeldtoepassing klonen

We gaan nu een Node.js-app klonen vanuit GitHub, de verbindingsreeks instellen en de app uitvoeren.

Voer de volgende opdracht uit om de voorbeeldopslagplaats te klonen. Deze opdracht maakt een kopie van de voorbeeld-app op uw computer.
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
```

De code bekijken

Deze stap is optioneel. Als u wilt weten hoe de databaseresources van Azure Cosmos in de code worden gemaakt, kunt u de volgende codefragmenten bekijken. Als u deze stap wilt overslaan, kunt u verdergaan naar Uw verbindingsreeks bijwerken.

Als u bekend bent met de vorige versie van SQL JavaScript SDK, heeft u misschien de termen verzameling en document gezien terwijl u ermee werkte. Azure Cosmos DB ondersteunt meerdere API-modellen. Daarom maakt versie 2.0+ van de JavaScript SDK gebruik van de generieke termen verzameling, wat een collectie, een grafiek of tabel kan zijn, en item, om de inhoud van de container te beschrijven.

De Cosmos DB JavaScript SDK wordt "@azure/cosmos" genoemd en kan worden geïnstalleerd via NPM...

npm install @azure/cosmos

De volgende codefragmenten zijn allemaal afkomstig uit het bestand app.js.

De CosmosClient wordt geïmporteerd uit het @azure/cosmos NPM-pakket.
```
const CosmosClient = require("@azure/cosmos").CosmosClient;
```
Er wordt een nieuw CosmosClient-object geïnitialiseerd.
```
const client = new CosmosClient({ endpoint, key });
```

Selecteer de database "Taken".

const database = client.database(databaseId);

Selecteer de container/verzameling "Items".

const container = database.container(containerId);

Selecteer alle items in de container "Items".

// query to return all items
const querySpec = {
  query: "SELECT * from c"
};

const { resources: items } = await container.items
  .query(querySpec)
  .fetchAll();

Een nieuw item maken

const { resource: createdItem } = await container.items.create(newItem);

Een item bijwerken

const { id, category } = createdItem;

createdItem.isComplete = true;
const { resource: updatedItem } = await container
  .item(id, category)
  .replace(createdItem);

Een item verwijderen

const { resource: result } = await container.item(id, category).delete();

Notitie

In de methoden "Bijwerken" en "Verwijderen" moet het item worden geselecteerd in de database door het aanroepen van container.item(). De twee doorgegeven parameters zijn de id van het item en de partitiesleutel van het item. In dit geval is de partitiesleutel de waarde van het veld "Categorie".

Uw verbindingsreeks bijwerken

Ga nu terug naar de Azure-portal om de details van de verbindingsreeks van uw Azure Cosmos-account op te halen. Kopieer de verbindingsreeks in de app zodat deze verbinding kan maken met uw database.

Ga in de Azure-portal naar uw Azure Cosmos DB-account en klik in de linkernavigatie op Sleutels. Selecteer vervolgens Sleutels voor lezen/schrijven. Gebruik de knoppen voor kopiëren aan de rechterkant van het scherm om de URI en Primaire sleutel in het app.js-bestand in de volgende stap te kopiëren.
In Open het bestand config.js.
Kopieer uw URI-waarde vanaf de portal (met de kopieerknop) en geef deze als waarde aan de eindpuntsleutel in config.js.

endpoint: "<Your Azure Cosmos account URI>"
Kopieer vervolgens de waarde voor PRIMAIRE SLEUTEL vanuit de portal en geef deze op als waarde voor config.key in config.js. U hebt uw app nu bijgewerkt met alle informatie die nodig is voor de communicatie met Azure Cosmos DB.

key: "<Your Azure Cosmos account key>"

De app uitvoeren

Voer npm install uit op een terminal om het "@azure/cosmos" NPM-pakket te installeren
Voer node app.js uit op een terminal om uw knooppunttoepassing te starten.
De twee items die u eerder in deze quickstart hebt gemaakt, worden weergegeven. Er wordt een nieuw item gemaakt. De vlag "isComplete" voor dat item is bijgewerkt naar "true" en vervolgens wordt het item verwijderd.

U kunt doorgaan met het experimenteren met deze voorbeeldtoepassing of terugkeren naar Data Explorer, om verder te werken met uw data of deze te wijzigen.

SLA’s bekijken in Azure Portal

De doorvoer, opslag, beschikbaarheid, latentie en consistentie van uw Cosmos DB-account worden in Azure Portal bewaakt. Grafieken voor metrische gegevens die zijn gekoppeld aan een Azure Cosmos DB Service Level Agreement (SLA) tonen de SLA-waarde in vergelijking met de werkelijke prestaties. Deze suite van metrische gegevens zorgt voor een transparante bewaking van uw SLA's.

Metrische gegevens en SLA's weergeven:

Selecteer Metrische gegevens in het navigatiemenu van uw Cosmos DB-account.
Selecteer een tabblad, bijvoorbeeld Latentie, en selecteer aan de rechterkant een tijdsbestek. Vergelijk de lijnen Werkelijk en SLA in de grafieken met elkaar.
Bekijk de metrische gegevens op de andere tabbladen.

Volgende stappen

In deze snelstart hebt u geleerd hoe u een Azure Cosmos DB-account maakt, een container maakt met Data Explorer en een Node.js-app uitvoert. Nu kunt u aanvullende gegevens in uw Azure Cosmos DB-account importeren.

Probeert u capaciteitsplanning uit te 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 vCCPUs
Als u typische aanvraagsnelheden voor uw huidige databaseworkload kent, leest u over het schatten van aanvraageenheden met behulp Azure Cosmos DB capacity planner

gegevens importeren in azure cosmos db