Rövid útmutató: Azure Cosmos DB for MongoDB-illesztő Node.js

Cikk
08/15/2024

A KÖVETKEZŐKRE VONATKOZIK: MongoDB

Ismerkedjen meg a MongoDB npm-csomaggal, amely adatbázisokat, gyűjteményeket és dokumentumokat hoz létre az Azure Cosmos DB-erőforrásban. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

A MongoDB-hez készült API referenciadokumentációja | MongoDB Package (NuGet) csomagok/Microsoft.Azure.Cosmos) | Azure Developer CLI

Előfeltételek

Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
GitHub-fiók

Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
Azure Developer CLI
Docker Desktop

Beállítás

Helyezze üzembe a projekt fejlesztési tárolóját a környezetében. Ezután az Azure Developer CLI (azd) használatával hozzon létre egy Azure Cosmos DB-fiókot MongoDB-fiókhoz, és helyezzen üzembe egy tárolóalapú mintaalkalmazást. A mintaalkalmazás az ügyfélkódtárat használja a mintaadatok kezelésére, létrehozására, olvasására és lekérdezésére.

Fontos

A GitHub-fiókok magukban foglalják a tárterületre és az alapórákra való jogosultságot díjmentesen. További információkért tekintse meg a GitHub-fiókokhoz tartozó tárterületet és alapórákat.

Nyisson meg egy terminált a projekt gyökérkönyvtárában.
Hitelesítés az Azure Developer CLI-vel azd auth logina . Kövesse az eszköz által megadott lépéseket a parancssori felületre való hitelesítéshez az ön által előnyben részesített Azure-hitelesítő adatokkal.
```
azd auth login
```
A projekt inicializálására használható azd init .
```
azd init --template cosmos-db-mongodb-nodejs-quickstart
```
Feljegyzés

Ez a rövid útmutató az azure-samples/cosmos-db-mongodb-nodejs-quickstart sablon GitHub-adattárat használja. Az Azure Developer CLI automatikusan klónozza ezt a projektet a gépére, ha még nincs ott.
Az inicializálás során konfiguráljon egy egyedi környezetnevet.

Tipp.

A rendszer a környezet nevét is használja a célerőforráscsoport neveként. Ebben a rövid útmutatóban fontolja meg a használatát msdocs-cosmos-db.
Az Azure Cosmos DB-fiók üzembe helyezése a következő használatával azd up: . A Bicep-sablonok egy minta webalkalmazást is üzembe helyeznek.
```
azd up
```
A kiépítési folyamat során válassza ki az előfizetést és a kívánt helyet. Várja meg, amíg a kiépítési folyamat befejeződik. A folyamat körülbelül öt percet vehet igénybe.

Az Azure-erőforrások kiépítése után a kimenet tartalmazza a futó webalkalmazás URL-címét.

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.

A konzol URL-címével keresse meg a webalkalmazást a böngészőben. Figyelje meg a futó alkalmazás kimenetét.

Telepítse a(z) csomagot

Adja hozzá a MongoDB npm-csomagot a JavaScript-projekthez. Használja az npm install package npm-csomag nevét meghatározó parancsot. A dotenv csomag a környezeti változók fájlból való beolvasására szolgál a .env helyi fejlesztés során.

npm install mongodb dotenv

Objektummodell

Mielőtt elkezdené az alkalmazást, nézzük meg az Azure Cosmos DB-ben található erőforrások hierarchiáját. Az Azure Cosmos DB egy adott objektummodellt használ erőforrások létrehozásához és eléréséhez. Az Azure Cosmos DB olyan hierarchiában hoz létre erőforrásokat, amelyek fiókokból, adatbázisokból, gyűjteményekből és dokumentumokból állnak.

Az Azure Cosmos DB-hierarchia diagramja, beleértve a fiókokat, adatbázisokat, gyűjteményeket és dokumentumokat.

Az alábbi MongoDB-osztályokkal kezelheti ezeket az erőforrásokat:

MongoClient - Ez az osztály ügyféloldali logikai ábrázolást biztosít a MongoDB-réteg API-hoz az Azure Cosmos DB-ben. Az ügyfélobjektum a szolgáltatással kapcsolatos kérések konfigurálására és végrehajtására szolgál.
Db – Ez az osztály egy olyan adatbázisra mutató hivatkozás, amely lehet, hogy még létezik a szolgáltatásban. Az adatbázis kiszolgálóoldali érvényesítve van, amikor megpróbálja elérni, vagy műveletet hajt végre rajta.
Collection – Ez az osztály olyan gyűjteményre hivatkozik, amely még nem létezik a szolgáltatásban. A gyűjtemény kiszolgálóoldali érvényesítve lesz, amikor megpróbál dolgozni vele.

A cikkben ismertetett mintakód létrehoz egy adatbázist, amelynek neve adventureworks productsegy . A products gyűjtemény olyan termékadatokat tartalmaz, mint a név, a kategória, a mennyiség és az értékesítési mutató. Minden termék egyedi azonosítót is tartalmaz.

Ebben az eljárásban az adatbázis nem használ horizontális skálázást.

Az ügyfél hitelesítése

A projektkönyvtárból hozzon létre egy index.js fájlt. A szerkesztőben a hozzáadáshoz utasításokra van szükség a MongoDB- és a DotEnv npm-csomagokra való hivatkozáshoz.

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

Definiálja az osztály új példányát a MongoClient, konstruktor használatával, és process.env. olvassa el a korábban létrehozott környezeti változót.

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

A példányok létrehozásának MongoClient különböző módjairól a MongoDB NodeJS-illesztőprogram rövid útmutatója nyújt további információt.

Aszinkron műveletek beállítása

A fájlban index.js adja hozzá az alábbi kódot az aszinkron műveletek támogatásához:

async function main(){

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

}

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

Az aszinkron/várakozási szintaxis kezeléséhez a következő kódrészleteket kell hozzáadni a fő függvényhez.

Csatlakozás az adatbázishoz

Ezzel a MongoClient.connect módszerrel csatlakozhat a MongoDB-hez készült Azure Cosmos DB-erőforráshoz. A kapcsolódási módszer az adatbázisra mutató hivatkozást ad vissza.

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

Adatbázispéldány lekérése

Használja a MongoClient.db lekérdezett adatbázisra mutató hivatkozást.

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

Gyűjteménypéldány lekérése

A MongoClient.Db.collection lekéri a gyűjteményre mutató hivatkozást.

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

Láncolt példányok

Összekapcsolhatja az ügyfelet, az adatbázist és a gyűjteményt. A láncolás kényelmesebb, ha több adatbázishoz vagy gyűjteményhez kell hozzáférnie.

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

Index létrehozása

Ezzel indexet Collection.createIndex hozhat létre a mongoDB FindCursor.sort metódussal történő rendezéshez használni kívánt dokumentumtulajdonságokon.

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

Dokumentum létrehozása

Hozzon létre egy dokumentumot az adatbázis terméktulajdonságaivaladventureworks:

A termék egyedi azonosítójának _id tulajdonsága.
Kategóriatulajdonság. Ez a tulajdonság használható logikai partíciókulcsként.
Névtulajdonság.
Készletmennyiség tulajdonság.
Eladó ingatlan, amely jelzi, hogy a termék eladásra kerül-e.

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

Hozzon létre egy dokumentumot a gyűjteményben hívással Collection.UpdateOne. Ebben a példában úgy döntöttünk, hogy ahelyett, hogy létrehoznánk egy új dokumentumot, arra az esetre, ha többször futtatnánk ezt a mintakódot.

Dokumentum lekérése

Az Azure Cosmos DB-ben az egyedi azonosító (_id) és a partíciókulcs (category) használatával kevésbé költséges pontolvasási műveletet hajthat végre.

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

Lekérdezési dokumentumok

Miután beszúrt egy dokumentumot, egy lekérdezést futtatva lekérheti az adott szűrőnek megfelelő összes dokumentumot. Ez a példa megkeresi az összes dokumentumot, amely megfelel egy adott kategóriának: gear-surf-surfboards. A lekérdezés definiálása után hívja meg Collection.find az eredmény lekérését FindCursor . Alakítsa át a kurzort tömbté JavaScript-tömb metódusok használatához.

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

Hibaelhárítás:

Ha például The index path corresponding to the specified order-by item is excluded.hibaüzenetet kap, győződjön meg arról, hogy létrehozta az indexet.

A kód futtatása

Ez az alkalmazás létrehoz egy API-t a MongoDB-adatbázishoz és -gyűjteményhez, és létrehoz egy dokumentumot, majd pontosan ugyanazt a dokumentumot olvassa vissza. Végül a példa egy olyan lekérdezést ad ki, amely csak az adott dokumentumot adja vissza. A példa minden lépéssel adatokat ad ki a konzolnak az elvégzett lépésekről.

Az alkalmazás futtatásához egy terminál használatával lépjen az alkalmazás könyvtárára, és futtassa az alkalmazást.

node index.js

Az alkalmazás kimenetének az alábbi példához hasonlónak kell lennie:

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

Az erőforrások eltávolítása

Ha már nincs szüksége a MongoDB-hez készült Azure Cosmos DB-fiókra, törölheti a megfelelő erőforráscsoportot.

az group delete Az erőforráscsoport törléséhez használja a parancsot.

az group delete --name $resourceGroupName

Az erőforráscsoport törléséhez használja a Remove-AzResourceGroup parancsmagot.

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

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre Azure Cosmos DB for MongoDB-fiókot, hogyan hozhat létre adatbázist, és hogyan hozhat létre gyűjteményt a MongoDB-illesztőprogram használatával. Most részletesebben is megismerkedhet a MongoDB-hez készült Azure Cosmos DB-vel további adatok importálásához, összetett lekérdezések végrehajtásához és az Azure Cosmos DB MongoDB-erőforrások kezeléséhez.

MongoDB offline migrálása a MongoDB-hez készült Azure Cosmos DB-be

Megosztás a következőn keresztül: