Oktatóanyag: Node.js-webalkalmazás létrehozása a JavaScript SDK használatával a NoSQL-fiók API-jának kezeléséhez az Azure Cosmos DB-ben

Cikk
03/31/2023

A KÖVETKEZŐKRE VONATKOZIK: NoSQL

Fejlesztőként előfordulhat, hogy noSQL-dokumentumadatokat használó alkalmazásokkal rendelkezik. Az Azure Cosmos DB-ben a NoSQL-fiókhoz készült API-val tárolhatja és érheti el ezeket a dokumentumadatokat. Ez a Node.js oktatóanyag bemutatja, hogyan tárolhat és érhet el adatokat egy API for NoSQL-fiókból az Azure Cosmos DB-ben. Az oktatóanyag a Microsoft Azure App Service Web Apps szolgáltatásában üzemeltetett Node.js Express-alkalmazást használja. Ebben az oktatóanyagban egy webalapú alkalmazást (Todo-alkalmazást) hoz létre, amely lehetővé teszi feladatok létrehozását, lekérését és befejezését. A feladatokat JSON-dokumentumok formájában tárolja az Azure Cosmos DB.

Ez az oktatóanyag bemutatja, hogyan hozhat létre API-t NoSQL-fiókhoz az Azure Cosmos DB-ben a Azure Portal használatával. Hitelkártya vagy Azure-előfizetés nélkül a következőket teheti:

Állítson be egy ingyenes Try Azure Cosmos DB-fiókot.
Adatbázis és tároló létrehozásához hozzon létre és futtasson egy Node.js SDK-ra épülő webalkalmazást.
Elemek hozzáadása a tárolóhoz.

Ez az oktatóanyag a JavaScript SDK 3.0-s verzióját használja, és a következő feladatokat ismerteti:

Azure Cosmos DB-fiók létrehozása
Új Node.js-alkalmazás létrehozása
Az alkalmazás csatlakoztatása az Azure Cosmos DB-hez
Az alkalmazás futtatása és üzembe helyezése az Azure-ban

Előfeltételek

A jelen cikkben lévő utasítások követése előtt győződjön meg arról, hogy rendelkezik az alábbi erőforrásokkal:

Azure-előfizetés, hitelkártya vagy Azure-előfizetés nélkül beállíthat egy ingyenes Try Azure Cosmos DB-fiókot.

Az Azure Cosmos DB ingyenesen, Azure-előfizetés nélkül, kötelezettségvállalás nélkül is kipróbálható. Másik lehetőségként létrehozhat egy ingyenes szintű Azure Cosmos DB-fiókot, amely az első 1000 RU/s- és 25 GB-os tárterülettel rendelkezik ingyenesen. Az Azure Cosmos DB emulátort a URI-jával is használhatja https://localhost:8081. Az emulátorral használható kulcsért lásd: Kérések hitelesítése.
A Node.js 6.10-es vagy újabb verziója.
Express generator (az Expresst az npm install express-generator -g segítségével telepítheti)
Telepítse a Git szoftvert a helyi munkaállomáson.

Azure Cosmos DB-fiók létrehozása

Először hozzon létre egy Azure Cosmos DB-fiókot. Ha már rendelkezik fiókkal, vagy ha ehhez az oktatóanyaghoz az Azure Cosmos DB Emulatort használja, ugorjon az Új Node.js alkalmazás létrehozása című szakaszra.

A Azure Portal menüben vagy a Kezdőlapon válassza az Erőforrás létrehozása lehetőséget.
Keresse meg az Azure Cosmos DB-t. Válassza azAzure Cosmos DBlétrehozása> lehetőséget.
Az Azure Cosmos DB-fiók létrehozása lapon válassza a Létrehozás lehetőséget az Azure Cosmos DB for NoSQL szakaszban.

Az Azure Cosmos DB számos API-t biztosít:
- NoSQL, dokumentumadatokhoz
- PostgreSQL
- MongoDB, dokumentumadatokhoz
- Apache Cassandra
- Tábla
- Apache Gremlin, gráfadatokhoz
A NoSQL API-val kapcsolatos további információkért lásd: Üdvözöljük az Azure Cosmos DB-ben.

Az Azure Cosmos DB-fiók létrehozása lapon adja meg az új Azure Cosmos DB-fiók alapvető beállításait.

Beállítás	Érték	Leírás
Előfizetés	Előfizetés neve	Válassza ki az Azure Cosmos DB-fiókhoz használni kívánt Azure-előfizetést.
Erőforráscsoport	Erőforráscsoport neve	Válasszon ki egy erőforráscsoportot, vagy válassza az Új létrehozása lehetőséget, majd adjon meg egy egyedi nevet az új erőforráscsoportnak.
Fiók neve	Egyedi név	Adjon meg egy nevet az Azure Cosmos DB-fiók azonosításához. Mivel a documents.azure.com hozzá van fűzve az URI létrehozásához megadott névhez, használjon egyedi nevet. A név csak kisbetűket, számokat és kötőjelet (-) tartalmazhat. 3–44 karakter hosszúságúnak kell lennie.
Hely	A felhasználókhoz legközelebb eső régió	Válassza ki az Azure Cosmos DB-fiókot üzemeltetéséhez használni kívánt földrajzi helyet. Használja a felhasználókhoz legközelebbi helyet, hogy a lehető leggyorsabb hozzáférést biztosítsa számukra az adatokhoz.
Kapacitásmód	Kiosztott átviteli sebesség vagy kiszolgáló nélküli	A Kiosztott átviteli sebesség lehetőséget választva hozzon létre egy fiókot kiosztott átviteli módban. A Kiszolgáló nélküli lehetőséget választva kiszolgáló nélküli módban hozhat létre fiókot.
Azure Cosmos DB ingyenes szintű kedvezmény alkalmazása	Alkalmaz vagy Nem alkalmazható	Az Ingyenes Azure Cosmos DB-szinttel az első 1000 RU/s és 25 GB tárterületet kapja ingyenesen egy fiókban. További információ az ingyenes szintről.
Fiók teljes átviteli sebességének korlátozása	Kijelölve vagy nem	Korlátozza az ezen a fiókon kiosztható átviteli sebesség teljes mennyiségét. Ez a korlát megakadályozza a kiosztott átviteli sebességhez kapcsolódó váratlan díjakat. A fiók létrehozása után frissítheti vagy eltávolíthatja ezt a korlátot.

Azure-előfizetésenként legfeljebb egy ingyenes szintű Azure Cosmos DB-fiókkal rendelkezhet, és a fiók létrehozásakor be kell jelentkeznie. Ha nem látja az ingyenes szintű kedvezmény alkalmazásának lehetőségét, az előfizetés egy másik fiókja már engedélyezve van az ingyenes szinttel.

Megjegyzés

A következő beállítások nem érhetők el, ha a Kiszolgáló nélküli lehetőséget választja Kapacitás módként:

Az ingyenes szint árengedményének alkalmazása
Fiók teljes átviteli sebességének korlátozása

A Globális terjesztés lapon konfigurálja az alábbi adatokat. Ebben a rövid útmutatóban meghagyhatja az alapértelmezett értékeket:

Beállítás	Érték	Leírás
Georedundancia	Letiltás	Engedélyezze vagy tiltsa le a globális terjesztést a fiókjában a régió párosításával egy párosított régióval. Később további régiókat is hozzáadhat a fiókjához.
Többrégiós írók	Letiltás	A többrégiós írási képesség lehetővé teszi, hogy kihasználja a kiosztott átviteli sebességet az adatbázisok és tárolók számára világszerte.
Rendelkezésre állási zónák	Letiltás	Availability Zones segítségével tovább javíthatja az alkalmazás rendelkezésre állását és rugalmasságát.

Megjegyzés

A következő beállítások nem érhetők el, ha a Kiszolgáló nélküli lehetőséget választja kapacitás módként az előző Alapszintű beállítások lapon:

Georedundancia
Többrégiós írók

Igény szerint további részleteket is konfigurálhat a következő lapokon:
- Hálózatkezelés. Virtuális hálózatról való hozzáférés konfigurálása.
- Biztonsági mentési szabályzat. Konfigurálja az időszakos vagy folyamatos biztonsági mentési szabályzatot.
- Titkosítás. Használjon szolgáltatás által felügyelt kulcsot vagy ügyfél által felügyelt kulcsot.
- Címkék. A címkék név-érték párok, amelyek lehetővé teszik az erőforrások kategorizálását és a konszolidált számlázás megtekintését úgy, hogy ugyanazt a címkét több erőforrásra és erőforráscsoportra alkalmazza.
Válassza az Áttekintés + létrehozás lehetőséget.
Tekintse át a fiókbeállításokat, majd válassza a Létrehozás lehetőséget. A fiók létrehozása eltarthat néhány percig. Várja meg, amíg a portáloldal megjelenik Az üzembe helyezés befejeződött.
Válassza az Erőforrás megnyitása lehetőséget az Azure Cosmos DB-fiók oldalának megtekintéséhez.

Lépjen az Azure Cosmos DB-fiók oldalára, és válassza a Kulcsok lehetőséget. Másolja ki a következőként létrehozott webalkalmazásban használni kívánt értékeket.

Képernyőkép a Azure Portal az Azure Cosmos DB-fiók oldalán kiemelt Kulcsok gombbal

Új Node.js-alkalmazás létrehozása

Most megtudhatja, hogyan hozhat létre alapszintű "Helló világ!" alkalmazás Node.js projektet az Express keretrendszer használatával.

Nyissa meg kedvenc terminálját, például a Node.js parancssort.
Keresse meg azt a könyvtárat, amelyben tárolni szeretné az új alkalmazást.
Az Express generátor használatával hozzon létre egy új alkalmazást todo (teendők) néven.
```
express todo
```
Nyissa meg a todo könyvtárat, és telepítse a függőségeket.
```
cd todo
npm install
```
Futtassa az új alkalmazást.
```
npm start
```
Az új alkalmazás böngészőben való megtekintéséhez nyissa meg a következőt http://localhost:3000: .

Állítsa le az alkalmazást a ctrl+C billentyűkombinációval a terminálablakban, és válassza az y lehetőséget a kötegelt feladat leállításához.

A szükséges modulok telepítése

A package.json fájl egyike azon fájloknak, amelyek a projekt gyökérmappájában létrejönnek. Ez a fájl a Node.js alkalmazáshoz szükséges egyéb modulok listáját tartalmazza. Amikor az Azure-ba telepíti az alkalmazást, a rendszer ennek a fájlnak a segítségével határozza meg, hogy melyik modulokat kell az Azure-ban telepíteni ahhoz, hogy működjön az alkalmazás. A jelen oktatóanyagban telepítsen még két csomagot.

Telepítse a @azure/cosmos modult az npm használatával.
```
npm install @azure/cosmos
```

Az Node.js alkalmazás csatlakoztatása az Azure Cosmos DB-hez

A kezdeti beállítás és konfigurálás befejezése után megtudhatja, hogyan írhatja meg azt a kódot, amelyet a teendőalkalmazásnak az Azure Cosmos DB-vel való kommunikációhoz szüksége van.

A modell létrehozása

A projektkönyvtár gyökerében hozzon létre egy modellek nevű új könyvtárat.
A models könyvtárban hozzon létre egy új fájlt taskDao.js néven. Ez a fájl az adatbázis és a tároló létrehozásához szükséges kódot tartalmazza. Emellett az Azure Cosmos DB-ben olvasási, frissítési, létrehozási és keresési módszereket is definiál.

Másolja a következő kódot a taskDao.js fájlba:

 // @ts-check
 const CosmosClient = require('@azure/cosmos').CosmosClient
 const debug = require('debug')('todo:taskDao')

 // For simplicity we'll set a constant partition key
 const partitionKey = undefined
 class TaskDao {
   /**
    * Manages reading, adding, and updating Tasks in Azure Cosmos DB
    * @param {CosmosClient} cosmosClient
    * @param {string} databaseId
    * @param {string} containerId
    */
   constructor(cosmosClient, databaseId, containerId) {
     this.client = cosmosClient
     this.databaseId = databaseId
     this.collectionId = containerId

     this.database = null
     this.container = null
   }

   async init() {
     debug('Setting up the database...')
     const dbResponse = await this.client.databases.createIfNotExists({
       id: this.databaseId
     })
     this.database = dbResponse.database
     debug('Setting up the database...done!')
     debug('Setting up the container...')
     const coResponse = await this.database.containers.createIfNotExists({
       id: this.collectionId
     })
     this.container = coResponse.container
     debug('Setting up the container...done!')
   }

   async find(querySpec) {
     debug('Querying for items from the database')
     if (!this.container) {
       throw new Error('Collection is not initialized.')
     }
     const { resources } = await this.container.items.query(querySpec).fetchAll()
     return resources
   }

   async addItem(item) {
     debug('Adding an item to the database')
     item.date = Date.now()
     item.completed = false
     const { resource: doc } = await this.container.items.create(item)
     return doc
   }

   async updateItem(itemId) {
     debug('Update an item in the database')
     const doc = await this.getItem(itemId)
     doc.completed = true

     const { resource: replaced } = await this.container
       .item(itemId, partitionKey)
       .replace(doc)
     return replaced
   }

   async getItem(itemId) {
     debug('Getting an item from the database')
     const { resource } = await this.container.item(itemId, partitionKey).read()
     return resource
   }
 }

 module.exports = TaskDao

Mentse és zárja be a taskDao.js fájlt.

A vezérlő létrehozása

A projekt routes könyvtárában hozzon létre egy új fájlt tasklist.js néven.

Adja hozzá a következő kódot a tasklist.js fájlhoz. Ez a kód betölti a tasklist.js fájl által használt CosmosClient és async modult. A kód a TaskList (Feladatlista) osztályt is meghatározza, amelyet a rendszer a korábban definiált TaskDao objektum példányába továbbít:

 const TaskDao = require("../models/TaskDao");

 class TaskList {
   /**
    * Handles the various APIs for displaying and managing tasks
    * @param {TaskDao} taskDao
    */
   constructor(taskDao) {
     this.taskDao = taskDao;
   }
   async showTasks(req, res) {
     const querySpec = {
       query: "SELECT * FROM root r WHERE r.completed=@completed",
       parameters: [
         {
           name: "@completed",
           value: false
         }
       ]
     };

     const items = await this.taskDao.find(querySpec);
     res.render("index", {
       title: "My ToDo List ",
       tasks: items
     });
   }

   async addTask(req, res) {
     const item = req.body;

     await this.taskDao.addItem(item);
     res.redirect("/");
   }

   async completeTask(req, res) {
     const completedTasks = Object.keys(req.body);
     const tasks = [];

     completedTasks.forEach(task => {
       tasks.push(this.taskDao.updateItem(task));
     });

     await Promise.all(tasks);

     res.redirect("/");
   }
 }

 module.exports = TaskList;

Mentse és zárja be a tasklist.js fájlt.

A config.js fájl hozzáadása

A projektkönyvtár gyökerében hozzon létre egy új fájlt config.js néven.

Adja hozzá a következő kódot a config.js fájlhoz. Ez a kód határozza meg az alkalmazáshoz szükséges konfigurációs beállításokat és értékeket.

const config = {};

config.host = process.env.HOST || "[the endpoint URI of your Azure Cosmos DB account]";
config.authKey =
  process.env.AUTH_KEY || "[the PRIMARY KEY value of your Azure Cosmos DB account";
config.databaseId = "ToDoList";
config.containerId = "Items";

if (config.host.includes("https://localhost:")) {
  console.log("Local environment detected");
  console.log("WARNING: Disabled checking of self-signed certs. Do not have this code in production.");
  process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
  console.log(`Go to http://localhost:${process.env.PORT || '3000'} to try the sample.`);
}

module.exports = config;

A config.js fájlban frissítse a HOST és a AUTH_KEY értékeit az Azure Cosmos DB-fiók Kulcsok lapján található értékekkel a Azure Portal.
Mentse és zárja be a config.js fájlt.

Az app.js fájl módosítása

A projekt könyvtárában nyissa meg az app.js fájlt. Ez a fájl korábban, az Express-webalkalmazás létrehozásakor jött létre.

Adja hozzá a következő kódot az app.js fájlhoz. Ez a kód határozza meg a használni kívánt konfigurációs fájlt, és betölti az értékeket néhány változóba, amelyeket a következő szakaszokban fog használni.

 const CosmosClient = require('@azure/cosmos').CosmosClient
 const config = require('./config')
 const TaskList = require('./routes/tasklist')
 const TaskDao = require('./models/taskDao')

 const express = require('express')
 const path = require('path')
 const logger = require('morgan')
 const cookieParser = require('cookie-parser')
 const bodyParser = require('body-parser')

 const app = express()

 // view engine setup
 app.set('views', path.join(__dirname, 'views'))
 app.set('view engine', 'jade')

 // uncomment after placing your favicon in /public
 //app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')));
 app.use(logger('dev'))
 app.use(bodyParser.json())
 app.use(bodyParser.urlencoded({ extended: false }))
 app.use(cookieParser())
 app.use(express.static(path.join(__dirname, 'public')))

 //Todo App:
 const cosmosClient = new CosmosClient({
   endpoint: config.host,
   key: config.authKey
 })
 const taskDao = new TaskDao(cosmosClient, config.databaseId, config.containerId)
 const taskList = new TaskList(taskDao)
 taskDao
   .init(err => {
     console.error(err)
   })
   .catch(err => {
     console.error(err)
     console.error(
       'Shutting down because there was an error settinig up the database.'
     )
     process.exit(1)
   })

 app.get('/', (req, res, next) => taskList.showTasks(req, res).catch(next))
 app.post('/addtask', (req, res, next) => taskList.addTask(req, res).catch(next))
 app.post('/completetask', (req, res, next) =>
   taskList.completeTask(req, res).catch(next)
 )
 app.set('view engine', 'jade')

 // catch 404 and forward to error handler
 app.use(function(req, res, next) {
   const err = new Error('Not Found')
   err.status = 404
   next(err)
 })

 // error handler
 app.use(function(err, req, res, next) {
   // set locals, only providing error in development
   res.locals.message = err.message
   res.locals.error = req.app.get('env') === 'development' ? err : {}

   // render the error page
   res.status(err.status || 500)
   res.render('error')
 })

 module.exports = app

Végül mentse és zárja be az app.js fájlt.

Felhasználói felület létrehozása

Most hozza létre a felhasználói felületet, hogy a felhasználó interakcióba léphessenek az alkalmazással. Az előző szakaszokban létrehozott Express-alkalmazás a Jade nézetmotort használja.

A rendszer a views (nézetek) könyvtárban található layout.jade fájlt használja a többi .jade fájl globális sablonjaként. Ebben a lépésben úgy módosítja, hogy a Twitter Bootstrapot használja, amely egy webhely tervezéséhez használt eszközkészlet.

Nyissa meg a views (nézetek) mappában található layout.jade fájlt, és cserélje ki annak tartalmát az alábbi kódra:

doctype html
html
  head
    title= title
    link(rel='stylesheet', href='//ajax.aspnetcdn.com/ajax/bootstrap/3.3.2/css/bootstrap.min.css')
    link(rel='stylesheet', href='/stylesheets/style.css')
  body
    nav.navbar.navbar-inverse.navbar-fixed-top
      div.navbar-header
        a.navbar-brand(href='#') My Tasks
    block content
    script(src='//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.11.2.min.js')
    script(src='//ajax.aspnetcdn.com/ajax/bootstrap/3.3.2/bootstrap.min.js')

Ez a kód arra utasítja a Jade-motort, hogy rendereljen egy HTML-t az alkalmazáshoz, és létrehoz egy tartalom nevű blokkot, ahol megadhatja a tartalomoldalak elrendezését. Mentse és zárja be a layout.jade fájlt.

Nyissa meg az alkalmazás által használt index.jade fájlt. Cserélje le a fájl tartalmát a következő kódra:

extends layout
block content
     h1 #{title}
     br

     form(action="/completetask", method="post")
      table.table.table-striped.table-bordered
         tr
           td Name
           td Category
           td Date
           td Complete
         if (typeof tasks === "undefined")
           tr
             td
         else
           each task in tasks
             tr
               td #{task.name}
               td #{task.category}
               - var date  = new Date(task.date);
               - var day   = date.getDate();
               - var month = date.getMonth() + 1;
               - var year  = date.getFullYear();
               td #{month + "/" + day + "/" + year}
               td
                if(task.completed) 
                 input(type="checkbox", name="#{task.id}", value="#{!task.completed}", checked=task.completed)
                else
                 input(type="checkbox", name="#{task.id}", value="#{!task.completed}", checked=task.completed)
       button.btn.btn-primary(type="submit") Update tasks
     hr
     form.well(action="/addtask", method="post")
       label Item Name:
       input(name="name", type="textbox")
       label Item Category:
       input(name="category", type="textbox")
       br
       button.btn(type="submit") Add item

Ez a kód kibővíti az elrendezést, és tartalmat biztosít a layout.jade fájlban látott tartalomhelyőrző számára. Ebben az elrendezésben két HTML-űrlapot hozott létre.

Az első űrlap tartalmaz egy táblát az adatokhoz, és egy gombot, amely lehetővé teszi az elemek frissítését a vezérlő /completeTask metódusának közzétételével.

A második űrlap két beviteli mezőt és egy gombot tartalmaz, amely lehetővé teszi, hogy új elemet hozzon létre a vezérlő /addtask metódusában való közzététellel, ami csak az alkalmazás működéséhez szükséges.

Az alkalmazás helyi futtatása

Az alkalmazás létrehozása után a következő lépésekkel futtathatja helyileg:

Az alkalmazás helyi gépen való teszteléséhez futtassa a parancsot npm start a terminálon az alkalmazás elindításához, majd frissítse az http://localhost:3000 oldalt. A lapnak most az alábbi képernyőképhez hasonlóan kell kinéznie:

Tipp

Ha hibaüzenetet kap a layout.jade fájl vagy az index.jade fájl behúzásával kapcsolatban, győződjön meg arról, hogy mindkét fájl első két sora balra, szóközök nélkül van behúzva. Ha az első két sor előtt szóközök vannak, távolítsa el őket, mentse mindkét fájlt, majd frissítse a böngészőablakot.
Az Elem neve és az Elemkategória mezők használatával adjon meg egy új feladatot, majd az Elem hozzáadása lehetőséget választva hozzon létre egy dokumentumot az Azure Cosmos DB-ben ezekkel a tulajdonságokkal.
A lap frissül, hogy az újonnan létrehozott elem megjelenjen a Teendők listában.
Egy feladat befejezéséhez jelölje be a Kész oszlop jelölőnégyzetét, majd válassza a Tevékenységek frissítése lehetőséget a már létrehozott dokumentum frissítéséhez és a nézetből való eltávolításához.
Az alkalmazás leállításához nyomja le a CTRL+C billentyűkombinációt a terminálablakban, majd válassza az y billentyűt a kötegelt feladat leállításához.

Az alkalmazás üzembe helyezése a App Service

Miután az alkalmazás helyileg sikeres volt, üzembe helyezheti Azure App Service. A terminálban győződjön meg arról, hogy a teendőalkalmazás könyvtárában van. Helyezze üzembe a kódot a helyi mappában (teendő) az alábbi az webapp up paranccsal:

az webapp up --sku F1 --name <app-name>

Cserélje le <app_name> egy olyan névre, amely az összes Azure-ban egyedi (az érvényes karakterek a-z, 0-9 és -). Jó példa a cég nevének és egy alkalmazásazonosítónak a kombinációjára. Az alkalmazás üzembe helyezésével kapcsolatos további információkért lásd: Node.js alkalmazás üzembe helyezése az Azure-ban.

A parancs végrehajtása eltarthat néhány percig. A parancs üzeneteket biztosít az erőforráscsoport, a App Service csomag és az alkalmazáserőforrás létrehozásáról, a naplózás konfigurálásáról és a ZIP-telepítés elvégzéséről. A parancs futtatás közben biztosítja ezeket az üzeneteket. Ezután megad egy URL-címet az alkalmazás elindításához a címen http://<app-name>.azurewebsites.net, amely az alkalmazás Azure-beli URL-címe.

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

Ha ezekre az erőforrásokra már nincs szükség, törölheti az erőforráscsoportot, az Azure Cosmos DB-fiókot és az összes kapcsolódó erőforrást. Ehhez válassza ki az Azure Cosmos DB-fiókhoz használt erőforráscsoportot, válassza a Törlés lehetőséget, majd erősítse meg a törölni kívánt erőforráscsoport nevét.

Következő lépések

A kapacitástervezéshez használhatja a meglévő adatbázisfürt adatait.

Mobilalkalmazások létrehozása a Xamarin és az Azure Cosmos DB használatával