Rychlý start: Ovladač Služby Azure Cosmos DB pro MongoDB pro Node.js

Článek
04/25/2024

PLATÍ PRO: MongoDB

Začněte s balíčkem npm MongoDB a vytvářejte databáze, kolekce a dokumenty v rámci prostředku služby Azure Cosmos DB. Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

Poznámka:

Ukázkové fragmenty kódu jsou k dispozici na GitHubu jako projekt JavaScriptu.

Referenční dokumentace k rozhraní API pro MongoDB Package (NuGet) s referenční dokumentací | k rozhraní API pro MongoDB / Microsoft.Azure.Cosmos) | Azure Developer CLI

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Účet GitHub

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Azure Developer CLI
Docker Desktop

Nastavení

Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd) vytvořte účet služby Azure Cosmos DB pro MongoDB a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.

Důležité

Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.

Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí azd auth loginrozhraní příkazového řádku . Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.
```
azd auth login
```
Slouží azd init k inicializaci projektu.
```
azd init
```
Během inicializace nakonfigurujte jedinečný název prostředí.

Tip

Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .msdocs-cosmos-db-
Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.
```
azd up
```
Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.

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.

Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

Nainstalujte balíček .

Přidejte balíček npm MongoDB do projektu JavaScriptu. npm install package Použijte příkaz určující název balíčku npm. Balíček dotenv se používá ke čtení proměnných prostředí ze .env souboru během místního vývoje.

npm install mongodb dotenv

Objektový model

Než začnete vytvářet aplikaci, podívejme se na hierarchii prostředků ve službě Azure Cosmos DB. Azure Cosmos DB má konkrétní objektový model, který se používá k vytváření a přístupu k prostředkům. Azure Cosmos DB vytváří prostředky v hierarchii, které se skládají z účtů, databází, kolekcí a dokumentů.

Diagram hierarchie služby Azure Cosmos DB, včetně účtů, databází, kolekcí a dokumentů

K interakci s těmito prostředky použijete následující třídy MongoDB:

MongoClient – Tato třída poskytuje logickou reprezentaci na straně klienta pro vrstvu rozhraní API pro MongoDB ve službě Azure Cosmos DB. Objekt klienta slouží ke konfiguraci a spouštění požadavků na službu.
Db – Tato třída je odkazem na databázi, která může nebo nemusí existovat ve službě ještě. Databáze je ověřena na straně serveru, když se pokusíte o přístup k databázi nebo provedete operaci s ní.
Collection – Tato třída je odkazem na kolekci, která ještě nemusí ve službě existovat. Kolekce se ověří na straně serveru, když se s ní pokusíte pracovat.

Vzorový kód popsaný v tomto článku vytvoří databázi s názvem adventureworks kolekce s názvem products. Kolekce products je navržená tak, aby obsahovala podrobnosti o produktu, jako je název, kategorie, množství a indikátor prodeje. Každý produkt obsahuje také jedinečný identifikátor.

Pro účely tohoto postupu nebude databáze používat horizontální dělení.

Ověření klienta

V adresáři projektu vytvořte soubor index.js . V editoru přidejte příkazy, které odkazují na balíčky MongoDB a DotEnv npm.

// 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');

Definujte novou instanci MongoClient, třídy pomocí konstruktoru a process.env. pro čtení proměnné prostředí, kterou jste vytvořili dříve.

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

Další informace o různých způsobech vytvoření MongoClient instance naleznete v tématu Rychlý start ovladače MongoDB NodeJS.

Nastavení asynchronních operací

index.js Do souboru přidejte následující kód, který podporuje asynchronní operace:

async function main(){

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

}

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

Následující fragmenty kódu by se měly přidat do hlavní funkce, aby bylo možné zpracovat syntaxi async/await.

Připojte se k databázi.

Použijte metodu MongoClient.connect pro připojení k prostředku Azure Cosmos DB for MongoDB. Metoda connect vrátí odkaz na databázi.

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

Získání instance databáze

MongoClient.db Použijte odkaz na databázi.

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

Získání instance kolekce

Získá MongoClient.Db.collection odkaz na kolekci.

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

Zřetězených instancí

Klienta, databázi a kolekci můžete zřetězovat dohromady. Řetězení je pohodlnější, pokud potřebujete získat přístup k více databázím nebo kolekcím.

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

Vytvoření indexu

Collection.createIndex Použijte k vytvoření indexu vlastností dokumentu, které chcete použít k řazení pomocí metody MongoDBFindCursor.sort.

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

Vytvoření dokumentu

Vytvořte dokument s vlastnostmi produktu pro adventureworks databázi:

Vlastnost _id pro jedinečný identifikátor produktu.
Vlastnost kategorie. Tuto vlastnost lze použít jako klíč logického oddílu.
Vlastnost name .
Vlastnost skladového množství .
Nemovitost prodeje označující, zda je produkt v prodeji.

// 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`);

Vytvořte v kolekci dokument voláním Collection.UpdateOne. V tomto příkladu jsme se rozhodli místovytvoření nového dokumentu vytvořit nový dokument pro případ, že tento ukázkový kód spustíte více než jednou.

Získání dokumentu

Ve službě Azure Cosmos DB můžete provést levnější operaci čtení bodů pomocí jedinečného identifikátoru (_id) i klíče oddílu (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`);

Dotazování na dokumenty

Po vložení dokumentu můžete spustit dotaz, abyste získali všechny dokumenty, které odpovídají určitému filtru. Tento příklad najde všechny dokumenty, které odpovídají určité kategorii: gear-surf-surfboards. Jakmile je dotaz definovaný, voláním Collection.find získáte FindCursor výsledek. Převeďte kurzor na pole tak, aby používaly javascriptové metody pole.

// 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)}`));

Řešení potíží:

Pokud se zobrazí například chyba The index path corresponding to the specified order-by item is excluded., ujistěte se, že jste vytvořili index.

Spuštění kódu

Tato aplikace vytvoří rozhraní API pro databázi a kolekci MongoDB a vytvoří dokument a pak přečte přesně stejný dokument. Příklad nakonec vydá dotaz, který by měl vrátit jenom tento jediný dokument. V každém kroku příklad vypíše informace do konzoly o krocích, které provedl.

Pokud chcete aplikaci spustit, přejděte pomocí terminálu do adresáře aplikace a spusťte aplikaci.

node index.js

Výstup aplikace by měl být podobný tomuto příkladu:

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

Vyčištění prostředků

Pokud už účet Azure Cosmos DB pro MongoDB nepotřebujete, můžete odstranit odpovídající skupinu prostředků.

az group delete Pomocí příkazu odstraňte skupinu prostředků.

az group delete --name $resourceGroupName

Pomocí rutiny Remove-AzResourceGroup odstraňte skupinu prostředků.

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

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet služby Azure Cosmos DB pro MongoDB, vytvořit databázi a vytvořit kolekci pomocí ovladače MongoDB. Teď se můžete hlouběji ponořit do služby Azure Cosmos DB pro MongoDB a importovat další data, provádět složité dotazy a spravovat prostředky MongoDB služby Azure Cosmos DB.

Offline migrace MongoDB do služby Azure Cosmos DB pro MongoDB