Snabbstart: Azure Cosmos DB för MongoDB-drivrutin för Node.js

GÄLLER FÖR: Mongodb

• .NET
• Python
• Java
• Node.js
• Kör

Kom igång med MongoDB npm-paketet för att skapa databaser, samlingar och dokument i din Azure Cosmos DB-resurs. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

Kommentar

Exempelkodfragmenten är tillgängliga på GitHub som ett JavaScript-projekt.

API för MongoDB-referensdokumentation | MongoDB-paket (NuGet) /Microsoft.Azure.Cosmos) | Azure Developer CLI

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• GitHub-konto

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Azure Developer CLI
• Docker Desktop

Konfigurera

Distribuera projektets utvecklingscontainer till din miljö. Använd sedan Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB för MongoDB-konto och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

Viktigt!

GitHub-konton innehåller en berättigande till lagring och kärntimmar utan kostnad. Mer information finns i inkluderade lagrings- och kärntimmar för GitHub-konton.

1. Öppna en terminal i projektets rotkatalog.

2. Autentisera till Azure Developer CLI med .azd auth login Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.

   azd auth login
   

3. Använd azd init för att initiera projektet.

   azd init
   

4. Under initieringen konfigurerar du ett unikt miljönamn.

   Dricks

   Miljönamnet används också som målresursgruppnamn. För den här snabbstarten bör du överväga att använda msdocs-cosmos-db.

5. Distribuera Azure Cosmos DB-kontot med .azd up Bicep-mallarna distribuerar också ett exempelwebbprogram.

   azd up
   

6. Under etableringsprocessen väljer du din prenumeration och önskad plats. Vänta tills etableringsprocessen har slutförts. Processen kan ta ungefär fem minuter.

7. När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

   

---

Installera -paketet

Lägg till MongoDB npm-paketet i JavaScript-projektet. npm install package Använd kommandot som anger namnet på npm-paketet. Paketet dotenv används för att läsa miljövariablerna från en .env fil under den lokala utvecklingen.

npm install mongodb dotenv

Objektmodell

Innan du börjar skapa programmet ska vi titta på resurshierarkin i Azure Cosmos DB. Azure Cosmos DB har en specifik objektmodell som används för att skapa och komma åt resurser. Azure Cosmos DB skapar resurser i en hierarki som består av konton, databaser, samlingar och dokument.

Hierarkiskt diagram som visar ett Azure Cosmos DB-konto högst upp. Kontot har två underordnade databasskärvor. En av databasskärvorna innehåller två underordnade samlingsshards. Den andra databassharden innehåller en enda underordnad samlingsnod. Den enda samlingssharden har tre underordnade dokumentskärvor.

Du använder följande MongoDB-klasser för att interagera med dessa resurser:

• MongoClient – Den här klassen ger en logisk representation på klientsidan för API:et för MongoDB-lagret i Azure Cosmos DB. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
• Db – Den här klassen är en referens till en databas som kanske, eller kanske inte finns i tjänsten ännu. Databasen verifieras på serversidan när du försöker komma åt den eller utföra en åtgärd mot den.
• Collection – Den här klassen är en referens till en samling som kanske inte heller finns i tjänsten ännu. Samlingen verifieras på serversidan när du försöker arbeta med den.

Kodexempel

• Autentisera klienten
• Hämta databasinstans
• Hämta samlingsinstans
• Länkade instanser
• Skapa ett index
• Skapa ett dokument
• Hämta ett dokument
• Frågedokument

Exempelkoden som beskrivs i den här artikeln skapar en databas med namnet adventureworks med en samling med namnet products. Samlingen products är utformad för att innehålla produktinformation som namn, kategori, kvantitet och en försäljningsindikator. Varje produkt innehåller också en unik identifierare.

För den här proceduren använder databasen inte horisontell partitionering.

Autentisera klienten

1. Skapa en index.js-fil från projektkatalogen. I redigeringsprogrammet lägger du till kravinstruktioner för att referera till MongoDB- och DotEnv npm-paketen.

   // Read .env file and set environment variables
   require('dotenv').config();
   const random = Math.floor(Math.random() * 100);
   
   // Use official mongodb driver to connect to the server
   const { MongoClient, ObjectId } = require('mongodb');
   

2. Definiera en ny instans av MongoClient, klassen med konstruktorn och process.env. för att läsa miljövariabeln som du skapade tidigare.

   // New instance of MongoClient with connection string
   // for Cosmos DB
   const url = process.env.COSMOS_CONNECTION_STRING;
   const client = new MongoClient(url);
   

Mer information om olika sätt att skapa en MongoClient instans finns i Snabbstart för MongoDB NodeJS-drivrutin.

Konfigurera asynkrona åtgärder

index.js Lägg till följande kod i filen för att stödja asynkrona åtgärder:

async function main(){

// The remaining operations are added here
// in the main function

}

main()
  .then(console.log)
  .catch(console.error)
  .finally(() => client.close());

Följande kodfragment bör läggas till i huvudfunktionen för att hantera syntaxen async/await.

Ansluta till databasen

MongoClient.connect Använd metoden för att ansluta till din Azure Cosmos DB for MongoDB-resurs. Connect-metoden returnerar en referens till databasen.

// Use connect method to connect to the server
await client.connect();

Hämta databasinstans

MongoClient.db Använd hämtar en referens till en databas.

// Database reference with creation if it does not already exist
const db = client.db(`adventureworks`);
console.log(`New database:\t${db.databaseName}\n`);

Hämta samlingsinstans

Hämtar MongoClient.Db.collection en referens till en samling.

// Collection reference with creation if it does not already exist
const collection = db.collection('products');
console.log(`New collection:\t${collection.collectionName}\n`);

Länkade instanser

Du kan länka klienten, databasen och samlingen tillsammans. Det är enklare att länka om du behöver komma åt flera databaser eller samlingar.

const db = await client.db(`adventureworks`).collection('products').updateOne(query, update, options)

Skapa ett index

Collection.createIndex Använd för att skapa ett index för dokumentets egenskaper som du tänker använda för sortering med MongoDB-metodenFindCursor.sort.

// create index to sort by name
const indexResult = await collection.createIndex({ name: 1 });
console.log(`indexResult: ${JSON.stringify(indexResult)}\n`);

Skapa ett dokument

Skapa ett dokument med produktegenskapernaadventureworks för databasen:

• En _id egenskap för produktens unika identifierare.
• En kategoriegenskap . Den här egenskapen kan användas som den logiska partitionsnyckeln.
• En namnegenskap .
• En lagerkvantitetsegenskap.
• En försäljningsfastighet som anger om produkten är till salu.

// Create new doc and upsert (create or replace) to collection
const product = {
    category: "gear-surf-surfboards",
    name: `Yamba Surfboard-${random}`,
    quantity: 12,
    sale: false
};
const query = { name: product.name};
const update = { $set: product };
const options = {upsert: true, new: true};

// Insert via upsert (create or replace) doc to collection directly
const upsertResult1 = await collection.updateOne(query, update, options);
console.log(`upsertResult1: ${JSON.stringify(upsertResult1)}\n`);

// Update via upsert on chained instance
const query2 = { _id: ObjectId(upsertResult1.upsertedId) };
const update2 = { $set: { quantity: 20 } };
const upsertResult2 = await client.db(`adventureworks`).collection('products').updateOne(query2, update2, options);
console.log(`upsertResult2: ${JSON.stringify(upsertResult2)}\n`);

Skapa ett dokument i samlingen genom att anropa Collection.UpdateOne. I det här exemplet väljer vi att öka i stället för att skapa ett nytt dokument om du kör den här exempelkoden mer än en gång.

Hämta ett dokument

I Azure Cosmos DB kan du utföra en billigare punktläsningsåtgärd med hjälp av både den unika identifieraren (_id) och partitionsnyckeln (category).

// Point read doc from collection:
// - without sharding, should use {_id}
// - with sharding,    should use {_id, partitionKey }, ex: {_id, category}
const foundProduct = await collection.findOne({
    _id: ObjectId(upsertResult1.upsertedId), 
    category: "gear-surf-surfboards"
});
console.log(`foundProduct: ${JSON.stringify(foundProduct)}\n`);

Frågedokument

När du har infogat ett dokument kan du köra en fråga för att hämta alla dokument som matchar ett visst filter. Det här exemplet hittar alla dokument som matchar en specifik kategori: gear-surf-surfboards. När frågan har definierats anropar du Collection.find för att få ett FindCursor resultat. Konvertera markören till en matris för att använda JavaScript-matrismetoder.

// select all from product category
const allProductsQuery = { 
    category: "gear-surf-surfboards" 
};

// get all documents, sorted by name, convert cursor into array
const products = await collection.find(allProductsQuery).sort({name:1}).toArray();
products.map((product, i ) => console.log(`${++i} ${JSON.stringify(product)}`));

Felsökning:

• Om du får ett fel, till exempel The index path corresponding to the specified order-by item is excluded., kontrollerar du att du har skapat indexet.

Kör koden

Den här appen skapar ett API för MongoDB-databas och samling och skapar ett dokument och läser sedan exakt samma dokument tillbaka. Slutligen utfärdar exemplet en fråga som bara ska returnera det enskilda dokumentet. Med varje steg matar exemplet ut information till konsolen om de steg som den har utfört.

Om du vill köra appen använder du en terminal för att navigera till programkatalogen och köra programmet.

node index.js

Utdata från appen bör likna det här exemplet:

New database:   adventureworks

New collection: products

upsertResult1: {"acknowledged":true,"modifiedCount":0,"upsertedId":"62b1f492ff69395b30a03169","upsertedCount":1,"matchedCount":0}

upsertResult2: {"acknowledged":true,"modifiedCount":1,"upsertedId":null,"upsertedCount":0,"matchedCount":1}

foundProduct: {"_id":"62b1f492ff69395b30a03169","name":"Yamba Surfboard-93","category":"gear-surf-surfboards","quantity":20,"sale":false}

indexResult: "name_1"

1 {"_id":"62b1f47dacbf04e86c8abf25","name":"Yamba Surfboard-11","category":"gear-surf-surfboards","quantity":20,"sale":false}
done

Rensa resurser

När du inte längre behöver Azure Cosmos DB för MongoDB-kontot kan du ta bort motsvarande resursgrupp.

Azure CLI

az group delete Använd kommandot för att ta bort resursgruppen.

az group delete --name $resourceGroupName

PowerShell

Använd cmdleten Remove-AzResourceGroup för att ta bort resursgruppen.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portal

1. Gå till den resursgrupp som du skapade tidigare i Azure-portalen.

   Dricks

   I den här snabbstarten rekommenderade vi namnet msdocs-cosmos-javascript-quickstart-rg.

2. Välj Ta bort resursgrupp.

   

3. I dialogrutan Är du säker på att du vill ta bort anger du namnet på resursgruppen 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 för MongoDB-konto, skapar en databas och skapar en samling med mongoDB-drivrutinen. Nu kan du fördjupa dig i Azure Cosmos DB for MongoDB för att importera mer data, utföra komplexa frågor och hantera dina Azure Cosmos DB MongoDB-resurser.

Migrera MongoDB till Azure Cosmos DB för MongoDB offline