Öğretici: Azure Cosmos DB'de NoSQL hesabı api'sini yönetmek için JavaScript SDK'sını kullanarak Node.js bir web uygulaması oluşturma

  • Makale

UYGULANANLAR: NOSQL

Geliştirici olarak, NoSQL belge verilerini kullanan uygulamalarınız olabilir. Bu belge verilerini depolamak ve bunlara erişmek için Azure Cosmos DB'de NoSQL için API kullanabilirsiniz. Bu Node.js öğreticisi, Azure Cosmos DB'de NoSQL hesabı için bir API'den verileri depolamayı ve bunlara erişmeyi gösterir. Öğreticide, Microsoft Azure App Service'nin Web Apps özelliğinde barındırılan bir Node.js Express uygulaması kullanılır. Bu öğreticide, görevleri oluşturmanıza, almanıza ve tamamlamanıza olanak tanıyan web tabanlı bir uygulama (Todo uygulaması) oluşturursunuz. Görevler, JSON belgeleri olarak Azure Cosmos DB'de depolanır.

Bu öğreticide, Azure portal kullanarak Azure Cosmos DB'de NoSQL hesabı için API oluşturma adımları gösterilmektedir. Kredi kartı veya Azure aboneliği olmadan şunları yapabilirsiniz:

  • Ücretsiz bir Azure Cosmos DB deneyin hesabı ayarlayın.
  • Veritabanı ve kapsayıcı oluşturmak için Node.js SDK'sı üzerinde oluşturulmuş bir web uygulaması derleyin ve çalıştırın.
  • Kapsayıcıya öğe ekleyin.

Bu öğreticide JavaScript SDK'sı sürüm 3.0 kullanılır ve aşağıdaki görevler yer alır:

  • Azure Cosmos DB hesabı oluşturma
  • Yeni bir Node.js uygulaması oluşturma
  • Uygulamayı Azure Cosmos DB’ye bağlama
  • Uygulamayı Azure'da çalıştırma ve dağıtma

Önkoşullar

Bu makaledeki yönergeleri izlemeden önce aşağıdaki kaynaklara sahip olduğunuzdan emin olun:

Azure Cosmos DB hesabı oluşturma

Bir Azure Cosmos DB hesabı oluşturarak başlayın. Zaten bir hesabınız varsa veya bu öğretici için Azure Cosmos DB Öykünücüsü kullanıyorsanız Yeni Node.js uygulaması oluşturma bölümüne atlayabilirsiniz.

  1. Azure portal menüsünden veya Giriş sayfasındaKaynak oluştur'u seçin.

  2. Azure Cosmos DB için arama. Azure Cosmos DB Oluştur'u> seçin.

  3. Azure Cosmos DB hesabı oluşturma sayfasında, NoSQL için Azure Cosmos DB bölümünde Oluştur seçeneğini belirleyin.

    Azure Cosmos DB çeşitli API'ler sağlar:

    • Belge verileri için NoSQL
    • PostgreSQL
    • Belge verileri için MongoDB
    • Apache Cassandra
    • Tablo
    • Grafik verileri için Apache Gremlin

    NoSQL API'si hakkında daha fazla bilgi edinmek için bkz. Azure Cosmos DB'ye Hoş Geldiniz.

  4. Azure Cosmos DB Hesabı Oluştur sayfasında yeni Azure Cosmos DB hesabının temel ayarlarını girin.

    Ayar Değer Açıklama
    Abonelik Abonelik adı Bu Azure Cosmos DB hesabı için kullanmak istediğiniz Azure aboneliğini seçin.
    Kaynak Grubu Kaynak grubu adı Bir kaynak grubu seçin veya Yeni oluştur seçeneğini belirleyin ve yeni kaynak grubu için benzersiz bir ad girin.
    Hesap Adı Benzersiz bir ad Azure Cosmos DB hesabınızı tanımlamak için bir ad girin. URI’nizi oluşturmak için sağladığınız ada documents.azure.com ekleneceği için benzersiz bir ad kullanın. Ad yalnızca küçük harf, sayı ve kısa çizgi (-) karakteri içerebilir. 3-44 karakter uzunluğunda olmalıdır.
    Konum Kullanıcılarınıza en yakın bölge Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.
    Kapasite modu Sağlanan aktarım hızı veya Sunucusuz Sağlanan aktarım hızı modunda hesap oluşturmak için Sağlanan aktarım hızı'na tıklayın. Sunucusuz modda hesap oluşturmak için Sunucusuz'u seçin.
    Azure Cosmos DB ücretsiz katman indirimi uygulama Uygula veya Uygulama Azure Cosmos DB ücretsiz katmanı ile bir hesapta ilk 1000 RU/sn ve 25 GB depolama alanını ücretsiz olarak alırsınız. Ücretsiz katman hakkında daha fazla bilgi edinin.
    Toplam hesap aktarım hızını sınırla Seçili veya değil Bu hesapta sağlanacak toplam aktarım hızı miktarını sınırlayın. Bu sınır, sağlanan aktarım hızıyla ilgili beklenmeyen ücretleri engeller. Hesabınız oluşturulduktan sonra bu sınırı güncelleştirebilir veya kaldırabilirsiniz.

    Azure aboneliği başına en fazla bir ücretsiz katman Azure Cosmos DB hesabınız olabilir ve hesabı oluştururken bunu kabul etmeniz gerekir. Ücretsiz katman indirimini uygulama seçeneğini görmüyorsanız abonelikteki başka bir hesap ücretsiz katmanla zaten etkinleştirilmiştir.

    Azure Cosmos DB Hesabı Oluştur sayfasını gösteren ekran görüntüsü.

    Not

    Kapasite modu olarak Sunucusuz seçeneğini belirlediğinizde aşağıdaki seçenekler kullanılamaz:

    • Ücretsiz Katman İndirimi Uygula
    • Toplam hesap aktarım hızını sınırla

  5. Genel Dağıtım sekmesinde aşağıdaki ayrıntıları yapılandırın. Bu hızlı başlangıç için varsayılan değerleri bırakabilirsiniz:

    Ayar Değer Açıklama
    Coğrafi Yedeklilik Devre Dışı Bırak Bölgenizi bir çift bölgeyle eşleştirerek hesabınızda genel dağıtımı etkinleştirin veya devre dışı bırakın. Daha sonra hesabınıza daha fazla bölge ekleyebilirsiniz.
    Birden Çok Bölgeli Yazmalar Devre Dışı Bırak Çok bölgeli yazma özelliği, dünya genelindeki veritabanlarınız ve kapsayıcılarınız için sağlanan aktarım hızını kullanmanıza olanak tanır.
    Kullanılabilirlik Alanları Devre Dışı Bırak Kullanılabilirlik Alanları uygulamanızın kullanılabilirliğini ve dayanıklılığını daha da artırmanıza yardımcı olur.

    Not

    Önceki Temel Bilgiler sayfasında Kapasite modu olarak Sunucusuz seçeneğini belirlediğinizde aşağıdaki seçenekler kullanılamaz:

    • Coğrafi yedeklilik
    • Birden Çok Bölgeli Yazmalar

  6. İsteğe bağlı olarak, aşağıdaki sekmelerde daha fazla ayrıntı yapılandırabilirsiniz:

    • Ağ iletişimi. Sanal ağdan erişimi yapılandırma.
    • Yedekleme İlkesi. Düzenli veya sürekli yedekleme ilkesi yapılandırın.
    • Şifreleme. Hizmet tarafından yönetilen anahtar veya müşteri tarafından yönetilen anahtar kullanın.
    • Etiketler'i seçin. Etiketler, birden çok kaynağa ve kaynak grubuna aynı etiketi uygulayarak kaynakları kategorilere ayırmanızı ve birleştirilmiş faturalamayı görüntülemenizi sağlayan ad/değer çiftleridir.

  7. Gözden geçir ve oluştur’u seçin.

  8. Hesap ayarlarını gözden geçirip Oluştur seçeneğini belirleyin. Hesabın oluşturulması birkaç dakika sürer. Portal sayfasında Dağıtımınız tamamlandı iletisinin görüntülenmesini bekleyin.

    Dağıtımınızın tamamlandığını gösteren ekran görüntüsü.

  9. Azure Cosmos DB hesabı sayfasına gitmek için Kaynağa git seçeneğini belirleyin.

    Azure Cosmos DB hesap sayfasını gösteren ekran görüntüsü.

Azure Cosmos DB hesabı sayfasına gidin ve Anahtarlar'ı seçin. Daha sonra oluşturduğunuz web uygulamasında kullanılacak değerleri kopyalayın.

Azure Cosmos DB hesap sayfasında Anahtarlar düğmesinin vurgulandığı Azure portal ekran görüntüsü

Yeni bir Node.js uygulaması oluşturma

Şimdi Express çerçevesini kullanarak temel bir Merhaba Dünya Node.js projesi oluşturmayı öğrenin.

  1. Node.js komut istemi gibi istediğiniz bir terminal uygulamasını açın.

  2. Yeni uygulamanın depolanmasını istediğiniz dizine gidin.

  3. Express oluşturucuyu kullanarak todo adlı yeni bir uygulama oluşturun.

    express todo

  4. todo dizinini açın ve bağımlılıkları yükleyin.

    cd todo
npm install

  5. Yeni uygulamayı çalıştırın.

    npm start

  6. Yeni uygulamanızı tarayıcıda görüntülemek için adresine http://localhost:3000gidin.

    Tarayıcı penceresindeki Merhaba Dünya uygulamasının ekran görüntüsü.

    Terminal penceresinde CTRL+C tuşlarını kullanarak uygulamayı durdurun ve toplu işi sonlandırmak için y'yi seçin.

Gerekli modülleri yükleme

Package.json dosyası, projenin kökünde oluşturulan dosyalardan biridir. Bu dosya, Node.js uygulamanız için gereken diğer modüllerin listesini içerir. Bu uygulamayı Azure'a dağıttığınızda uygulamanızı desteklemek amacıyla Azure'a hangi modüllerin yüklenmesi gerektiğini belirlemek için bu dosya kullanılır. Bu öğretici için iki paket daha yükleyeceksiniz.

  1. npm aracılığıyla @azure/cosmos modülünü yükleyin.

    npm install @azure/cosmos

Node.js uygulamasını Azure Cosmos DB'ye bağlama

İlk kurulumu ve yapılandırmayı tamamladıktan sonra, yapılacaklar uygulamasının Azure Cosmos DB ile iletişim kurması için gereken kodu yazmayı öğrenin.

Modeli oluşturma

  1. Proje dizininizin kökünde models adlı yeni bir dizin oluşturun.

  2. models dizininde taskDao.js adında yeni bir dosya oluşturun. Bu dosya, veritabanını ve kapsayıcıyı oluşturmak için gereken kodu içerir. Ayrıca Azure Cosmos DB'de görevleri okuma, güncelleştirme, oluşturma ve bulma yöntemlerini de tanımlar.

  3. Aşağıdaki kodu taskDao.js dosyasına kopyalayın:

     // @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

  4. taskDao.js dosyasını kaydedin ve kapatın.

Denetleyiciyi oluşturma

  1. Projenizin routes dizininde tasklist.js adlı yeni bir dosya oluşturun.

  2. Aşağıdaki kodu tasklist.js'ye ekleyin. Bu kod, tasklist.js tarafından kullanılan CosmosClient ve async modüllerini yükler. Bu kod, daha önce tanımladığımız TaskDao nesnesinin bir örneği olarak geçirilmiş TaskList sınıfını da tanımlar:

     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;

  3. tasklist.js dosyasını kaydedin ve kapatın.

Config.js ekleme

  1. Projenizin kök dizininde config.js adlı yeni bir dosya oluşturun.

  2. config.js dosyasına aşağıdaki kodu ekleyin. Bu kod, uygulamamız için gereken yapılandırma ayarlarını ve değerlerini tanımlar.

    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;

  3. config.js dosyasında, Azure portal Azure Cosmos DB hesabınızın Anahtarlar sayfasında bulunan değerleri kullanarak HOST ve AUTH_KEY değerlerini güncelleştirin.

  4. config.js dosyasını kaydedin ve kapatın.

App.js'yi değiştirme

  1. Proje dizininde app.js dosyasını açın. Bu dosya daha önce Express web uygulaması oluşturulduğu zaman oluşturulmuştur.

  2. app.js dosyasına aşağıdaki kodu ekleyin. Bu kod, kullanılacak yapılandırma dosyasını tanımlar ve değerleri sonraki bölümlerde kullanacağınız bazı değişkenlere yükler.

     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

  3. Son olarak, app.js dosyasını kaydedip kapatın.

Kullanıcı arabirimi oluşturma

Şimdi kullanıcının uygulamayla etkileşim kurabilmesi için kullanıcı arabirimini oluşturun. Önceki bölümlerde oluşturduğunuz Express uygulaması, görünüm altyapısı olarak Jade kullanır.

  1. views dizinindeki layout.jade dosyası diğer .jade dosyaları için genel bir şablon olarak kullanılır. Bu adımda, web sitesi tasarlamak için kullanılan bir araç seti olan Twitter Bootstrap'ı kullanacak şekilde değiştirirsiniz.

  2. views klasöründe bulunan layout.jade dosyasını açın ve içeriğini aşağıdaki kodla değiştirin:

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

    Bu kod Jade altyapısına uygulama için bazı HTML'leri işlemesini söyler ve içerik sayfalarının düzenini sağlayabildiğiniz content adlı bir blok oluşturur. layout.jade dosyasını kaydedin ve kapatın.

  3. Uygulama tarafından kullanılan görünüm olan index.jade dosyasını açın. Dosyanın içeriğini aşağıdaki kodla değiştirin:

    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

Bu kod düzeni genişletir ve layout.jade dosyasında gördüğünüz içerik yer tutucusu için içerik sağlar. Bu düzende iki HTML formu oluşturdunuz.

İlk form, verileriniz için bir tablo ve denetleyicinin /completeTask yöntemine göndererek öğeleri güncelleştirmenizi sağlayan bir düğme içerir.

İkinci form, iki giriş alanı ve denetleyicinin /addtask yöntemine göndererek yeni bir öğe oluşturmanıza olanak tanıyan bir düğme içerir. Bu, uygulamanın çalışması için tek ihtiyacınız olan yöntemdir.

Uygulamanızı yerel olarak çalıştırma

Uygulamayı derledikten sonra aşağıdaki adımları kullanarak yerel olarak çalıştırabilirsiniz:

  1. Uygulamayı yerel makinenizde test etmek için terminalde komutunu çalıştırarak npm start uygulamanızı başlatın ve sayfayı http://localhost:3000 yenileyin. Sayfa artık aşağıdaki ekran görüntüsüne benzemelidir:

    Tarayıcıda Yapılacaklar Listem uygulamasının ekran görüntüsü.

    İpucu

    layout.jade dosyasındaki veya index.jade dosyasındaki girintiyle ilgili bir hata alırsanız, her iki dosyadaki ilk iki satırın boşluk olmadan sola yaslandığından emin olun. İlk iki satırdan önce boşluklar varsa, bunları kaldırın, her iki dosyayı da kaydedin ve tarayıcı pencerenizi yenileyin.

  2. Yeni bir görev girmek için Öğe Adı ve Öğe Kategorisi alanlarını kullanın ve ardından Öğe Ekle'yi seçerek Azure Cosmos DB'de bu özelliklere sahip bir belge oluşturun.

  3. Sayfa, ToDo listesinde yeni oluşturulan öğeyi görüntüleyecek şekilde güncelleştirilir.

    Yapılacaklar listesinde yeni bir öğe bulunan uygulamanın ekran görüntüsü.

  4. Görevi tamamlamak için Tamamla sütunundaki onay kutusunu seçin ve ardından Görevleri güncelleştir'i seçerek önceden oluşturduğunuz belgeyi güncelleştirin ve görünümden kaldırın.

  5. Uygulamayı durdurmak için terminal penceresinde CTRL+C tuşlarına basın ve ardından toplu işi sonlandırmak için y'yi seçin.

Uygulamanızı App Service dağıtma

Uygulamanız yerel olarak başarılı olduktan sonra Azure App Service dağıtabilirsiniz. Terminalde todo uygulama dizininde olduğunuzdan emin olun. Aşağıdaki az webapp up komutunu kullanarak kodu yerel klasörünüzde (todo) dağıtın:

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

app_name> değerini tüm Azure'da benzersiz bir adla değiştirin <(geçerli karakterler a-z, 0-9 ve -'dır). İyi bir desen, şirketinizin adıyla uygulama tanımlayıcısının bir bileşimini kullanmaktır. Uygulama dağıtımı hakkında daha fazla bilgi edinmek için bkz. Azure'da uygulama dağıtımıNode.js.

Komutun tamamlanması birkaç dakika sürebilir. komutu kaynak grubunu, App Service planını ve uygulama kaynağını oluşturma, günlüğe kaydetmeyi yapılandırma ve ZIP dağıtımı yapma hakkında iletiler sağlar. komutu çalışırken bu iletileri sağlar. Ardından, uygulamanın Azure'daki URL'si olan konumunda http://<app-name>.azurewebsites.netuygulamayı başlatmanız için bir URL verir.

Kaynakları temizleme

Bu kaynaklar artık gerekli olmadığında kaynak grubunu, Azure Cosmos DB hesabını ve tüm ilgili kaynakları silebilirsiniz. Bunu yapmak için Azure Cosmos DB hesabı için kullandığınız kaynak grubunu seçin, Sil'i seçin ve silinecek kaynak grubunun adını onaylayın.

Sonraki adımlar

Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.

Xamarin ve Azure Cosmos DB ile mobil uygulamalar derleme