Hızlı Başlangıç: Node.js için MongoDB için Azure Cosmos DB sürücüsü

ŞUNLAR IÇIN GEÇERLIDIR: MongoDB

• .NET
• Python
• Java
• Node.js
• Git

Azure Cosmos DB kaynağınızda veritabanları, koleksiyonlar ve belgeler oluşturmak için MongoDB npm paketini kullanmaya başlayın. Paketi yüklemek için bu adımları izleyin ve temel görevler için örnek kodu deneyin.

Not

Örnek kod parçacıkları GitHub'da JavaScript projesi olarak kullanılabilir.

MongoDB için API başvuru belgeleri | MongoDB Paketi (NuGet) paketleri/Microsoft.Azure.Cosmos) | Azure Geliştirici CLI'sı

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
• GitHub hesabı

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.
• Azure Geliştirici CLI'sı
• Docker Desktop

Ayarlama

Bu projenin geliştirme kapsayıcısını ortamınıza dağıtın. Ardından Azure Geliştirici CLI'sını (azd) kullanarak MongoDB için Azure Cosmos DB hesabı oluşturun ve kapsayıcılı örnek bir uygulama dağıtın. Örnek uygulama örnek verileri yönetmek, oluşturmak, okumak ve sorgulamak için istemci kitaplığını kullanır.

Önemli

GitHub hesapları, hiçbir ücret ödemeden depolama ve çekirdek saat yetkilendirmesi içerir. Daha fazla bilgi için bkz . GitHub hesapları için dahil edilen depolama ve çekirdek saatler.

1. Projenin kök dizininde bir terminal açın.

2. kullanarak azd auth loginAzure Geliştirici CLI'sinde kimlik doğrulaması Tercih ettiğiniz Azure kimlik bilgilerini kullanarak CLI'da kimlik doğrulaması yapmak için araç tarafından belirtilen adımları izleyin.

   azd auth login
   

3. Projeyi başlatmak için kullanın azd init .

   azd init
   

4. Başlatma sırasında benzersiz bir ortam adı yapılandırın.

   İpucu

   Ortam adı, hedef kaynak grubu adı olarak da kullanılır. Bu hızlı başlangıç için kullanmayı msdocs-cosmos-db-göz önünde bulundurun.

5. Kullanarak azd upAzure Cosmos DB hesabını dağıtın. Bicep şablonları ayrıca örnek bir web uygulaması dağıtır.

   azd up
   

6. Sağlama işlemi sırasında aboneliğinizi ve istediğiniz konumu seçin. Sağlama işleminin tamamlanmasını bekleyin. İşlem yaklaşık beş dakika sürebilir.

7. Azure kaynaklarınızın sağlanması tamamlandıktan sonra, çalışan web uygulamasının URL'si çıktıya eklenir.

   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. Tarayıcıda web uygulamanıza gitmek için konsoldaki URL'yi kullanın. Çalışan uygulamanın çıkışını gözlemleyin.

   

---

paketini yükleyin

JavaScript projesine MongoDB npm paketini ekleyin. npm install package npm paketinin adını belirten komutunu kullanın. Paket dotenv , yerel geliştirme sırasında bir .env dosyadan ortam değişkenlerini okumak için kullanılır.

npm install mongodb dotenv

Nesne modeli

Uygulamayı oluşturmaya başlamadan önce Azure Cosmos DB'deki kaynak hiyerarşisini inceleyelim. Azure Cosmos DB'de kaynak oluşturmak ve kaynaklara erişmek için kullanılan belirli bir nesne modeli vardır. Azure Cosmos DB, hesaplar, veritabanları, koleksiyonlar ve belgelerden oluşan bir hiyerarşide kaynaklar oluşturur.

En üstte bir Azure Cosmos DB hesabını gösteren hiyerarşik diyagram. Hesapta iki alt veritabanı parçası vardır. Veritabanı parçalarından biri iki alt koleksiyon parçası içerir. Diğer veritabanı parçası tek bir alt koleksiyon düğümü içerir. Bu tek koleksiyon parçası üç alt belge parçasına sahiptir.

Bu kaynaklarla etkileşime geçmek için aşağıdaki MongoDB sınıflarını kullanacaksınız:

• MongoClient - Bu sınıf, Azure Cosmos DB'de MongoDB için API katmanı için istemci tarafı mantıksal gösterimi sağlar. İstemci nesnesi, hizmette istekleri yapılandırmak ve yürütmek için kullanılır.
• Db - Bu sınıf, hizmette henüz var olabilen veya bulunmayabilecek bir veritabanına başvurudur. Veritabanına erişmeye veya ona karşı bir işlem gerçekleştirmeye çalıştığınızda veritabanı sunucu tarafında doğrulanır.
• Collection - Bu sınıf, hizmette henüz mevcut olmayan bir koleksiyona başvurudur. Koleksiyon, onunla çalışmaya çalıştığınızda sunucu tarafında doğrulanır.

Kod örnekleri

• İstemcinin kimliğini doğrulama
• Veritabanı örneğini alma
• Koleksiyon örneğini alma
• Zincirlenmiş örnekler
• Dizin oluşturma
• Belge oluşturma
• Belge alma
• Belgeleri sorgulama

Bu makalede açıklanan örnek kod adlı bir koleksiyonla adlı adventureworksproductsbir veritabanı oluşturur. Koleksiyon products ad, kategori, miktar ve satış göstergesi gibi ürün ayrıntılarını içerecek şekilde tasarlanmıştır. Her ürün benzersiz bir tanımlayıcı da içerir.

Bu yordam için veritabanı parçalama kullanmaz.

İstemcinin kimliğini doğrulama

1. Proje dizininden bir index.js dosyası oluşturun. Düzenleyicinizde add, MongoDB ve DotEnv npm paketlerine başvurmak için deyimleri gerektirir.

   // 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. Oluşturucuyu MongoClient, kullanarak sınıfının yeni bir örneğini tanımlayın ve process.env. daha önce oluşturduğunuz ortam değişkenini okuyun.

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

Örnek oluşturmanın MongoClient farklı yolları hakkında daha fazla bilgi için bkz . MongoDB NodeJS Sürücüsü Hızlı Başlangıç.

Zaman uyumsuz işlemleri ayarlama

index.js Dosyasına, zaman uyumsuz işlemleri desteklemek için aşağıdaki kodu ekleyin:

async function main(){

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

}

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

Async/await söz dizimini işlemek için ana işleve aşağıdaki kod parçacıkları eklenmelidir.

Veritabanına bağlanın

MongoClient.connect MongoDB için Azure Cosmos DB kaynağınıza bağlanmak için yöntemini kullanın. connect yöntemi veritabanına bir başvuru döndürür.

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

Veritabanı örneğini alma

MongoClient.db komutunu kullanarak bir veritabanına başvuru alır.

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

Koleksiyon örneğini alma

bir MongoClient.Db.collection koleksiyona başvuru alır.

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

Zincirlenmiş örnekler

İstemciyi, veritabanını ve koleksiyonu birbirine zincirleyebilirsiniz. Birden çok veritabanına veya koleksiyona erişmeniz gerekiyorsa zincirleme daha kullanışlıdır.

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

Dizin oluşturma

Collection.createIndex MongoDB'nin FindCursor.sort yöntemiyle sıralamak için kullanmayı planladığınız belgenin özelliklerinde dizin oluşturmak için öğesini kullanın.

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

Belge oluşturma

Veritabanının ürün özelliklerine adventureworks sahip bir belge oluşturun:

• Ürünün benzersiz tanımlayıcısı için bir _id özelliği.
• Kategori özelliği. Bu özellik mantıksal bölüm anahtarı olarak kullanılabilir.
• Ad özelliği.
• Stok miktarı özelliği.
• Ürünün satışta olup olmadığını gösteren bir satış özelliği.

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

çağrısı Collection.UpdateOneyaparak koleksiyonda bir belge oluşturun. Bu örnekte, bu örnek kodu birden çok kez çalıştırmanız durumunda yeni bir belge oluşturmak yerine upsert'i seçtik.

Belge alma

Azure Cosmos DB'de hem benzersiz tanımlayıcıyı () hem de bölüm anahtarınıcategory (_id) kullanarak daha ucuz bir nokta okuma işlemi gerçekleştirebilirsiniz.

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

Belgeleri sorgulama

Belge ekledikten sonra, belirli bir filtreyle eşleşen tüm belgeleri almak için bir sorgu çalıştırabilirsiniz. Bu örnek, belirli bir kategoriyle eşleşen tüm belgeleri bulur: gear-surf-surfboards. Sorgu tanımlandıktan sonra bir sonuç almak FindCursor için çağrısında Collection.find bulunur. JavaScript dizi yöntemlerini kullanmak için imleci bir diziye dönüştürün.

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

Sorun Giderme:

• gibi The index path corresponding to the specified order-by item is excluded.bir hata alırsanız dizini oluşturduğunuzdan emin olun.

Kodu çalıştırma

Bu uygulama MongoDB veritabanı ve koleksiyonu için bir API oluşturur, bir belge oluşturur ve tam olarak aynı belgeyi okur. Son olarak, örnek yalnızca bu tek belgeyi döndürmesi gereken bir sorgu oluşturur. Her adımda örnek, konsola gerçekleştirdiği adımlarla ilgili bilgiler gönderir.

Uygulamayı çalıştırmak için bir terminal kullanarak uygulama dizinine gidin ve uygulamayı çalıştırın.

node index.js

Uygulamanın çıkışı şu örneğe benzer olmalıdır:

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

Kaynakları temizleme

MongoDB için Azure Cosmos DB hesabına artık ihtiyacınız kalmadığında ilgili kaynak grubunu silebilirsiniz.

Azure CLI

az group delete Kaynak grubunu silmek için komutunu kullanın.

az group delete --name $resourceGroupName

PowerShell

Remove-AzResourceGroup Kaynak grubunu silmek için cmdlet'ini kullanın.

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

Portal

1. Azure portalında daha önce oluşturduğunuz kaynak grubuna gidin.

   İpucu

   Bu hızlı başlangıçta adını msdocs-cosmos-javascript-quickstart-rgöneririz.

2. Kaynak grubunu sil'i seçin.

   

3. Silmek istediğinizden emin misiniz iletişim kutusunda kaynak grubunun adını girin ve Sil'i seçin.

   

Sonraki adımlar

Bu hızlı başlangıçta MongoDB hesabı için Azure Cosmos DB oluşturmayı, veritabanı oluşturmayı ve MongoDB sürücüsünü kullanarak koleksiyon oluşturmayı öğrendiniz. Artık daha fazla veri içeri aktarmak, karmaşık sorgular gerçekleştirmek ve Azure Cosmos DB MongoDB kaynaklarınızı yönetmek için MongoDB için Azure Cosmos DB'ye daha ayrıntılı bir şekilde bakabilirsiniz.

MongoDB'yi MongoDB için Azure Cosmos DB'ye çevrimdışı geçirme