Hızlı Başlangıç: Node.js için Azure SDK ile NoSQL için Azure Cosmos DB kullanma

2025-06-11
Şunlara uygulanır: ✅ NoSQL

Bu hızlı başlangıçta, Node.jsiçin Azure SDK'sını kullanarak NoSQL için temel bir Azure Cosmos DB uygulaması dağıtacaksınız. NoSQL için Azure Cosmos DB, uygulamaların yapılandırılmamış verileri bulutta depolamasına olanak sağlayan şemasız bir veri deposudur. kapsayıcılarınızdaki verileri sorgulayın ve Node.jsiçin Azure SDK'sını kullanarak tek tek öğeler üzerinde ortak işlemler gerçekleştirin.

API başvuru belgeleri | Kitaplık kaynak kodu | Paket (npm) | Azure Geliştirici CLI

Önkoşullar

Azure Geliştirici CLI
Docker Desktop
Node.js 22 veya üzeri

Azure hesabınız yoksa, başlamadan önce ücretsiz hesap oluşturun.

Projeyi başlatma

Azure Geliştirici CLI'sını (azd) kullanarak NoSQL 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.

Boş bir dizinde bir terminal açın.
Henüz kimlik doğrulaması yapmadıysanız, Azure Geliştirici CLI'sinde azd auth login kullanarak kimlik doğrulaması gerçekleştirin. 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
```

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

azd init --template cosmos-db-nosql-nodejs-quickstart

Başlatma sırasında benzersiz bir ortam adı yapılandırın.
Azure Cosmos DB hesabını azd up kullanarak dağıtın. Bicep şablonları ayrıca örnek bir web uygulaması dağıtır.
```
azd up
```
Sağlama işlemi sırasında aboneliğinizi, istediğiniz konumu ve hedef kaynak grubunu seçin. Sağlama işleminin tamamlanmasını bekleyin. İşlem yaklaşık beş dakika sürebilir.

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.

Tarayıcıda web uygulamanıza gitmek için konsoldaki URL'yi kullanın. Çalışmakta olan uygulamanın çıktısını gözlemleyin.

Çalışan web uygulamasının ekran görüntüsü.

İstemci kitaplığını yükleme

İstemci kitaplığı @azure/cosmos paketi olarak, Node Paket Yöneticisi (npm) aracılığıyla kullanılabilir.

Bir terminal açın ve klasöre /src gidin.
```
cd ./src
```
Henüz yüklü değilse, @azure/cosmos paketini npm install kullanarak yükleyin.
```
npm install --save @azure/cosmos
```
Ayrıca, henüz yüklü değilse paketi yükleyin @azure/identity .
```
npm install --save @azure/identity
```
src/package.json dosyasını açıp gözden geçirerek ve azure-cosmos girdilerinin her ikisinin de var olduğunu azure-identity doğrulayın.

Kitaplıkları içeri aktarma

DefaultAzureCredential ve CosmosClient türlerini uygulama kodunuz içine aktarın.

import { DefaultAzureCredential } from '@azure/identity';
import { CosmosClient } from '@azure/cosmos';

Tüm gerekli türleri uygulama kodunuz içine aktar.

import { PagedAsyncIterableIterator } from '@azure/core-paging';
import { DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Container, CosmosClient, Database, FeedResponse, ItemResponse, SqlQuerySpec } from '@azure/cosmos';

Nesne modeli

İsim	Açıklama
`CosmosClient`	Bu sınıf birincil istemci sınıfıdır ve hesap genelindeki meta verileri veya veritabanlarını yönetmek için kullanılır.
`Database`	Bu sınıf, hesaptaki bir veritabanını temsil eder.
`Container`	Bu sınıf öncelikli olarak kapsayıcıda veya kapsayıcıda depolanan öğelerde okuma, güncelleştirme ve silme işlemleri gerçekleştirmek için kullanılır.
`PartitionKey`	Bu sınıf mantıksal bölüm anahtarını temsil eder. Bu sınıf birçok yaygın işlem ve sorgu için gereklidir.
`SqlQuerySpec`	Bu arabirim bir SQL sorgusunu ve tüm sorgu parametrelerini temsil eder.

Şablondaki örnek kod, cosmicworks adlı bir veritabanı ve products adlı bir kapsayıcı kullanır. Kapsayıcı ad products , kategori, miktar, benzersiz tanımlayıcı ve her ürün için satış bayrağı gibi ayrıntıları içerir. Kapsayıcı, mantıksal bölüm anahtarı olarak özelliğini kullanır /category .

İstemcinin kimliğini doğrulama

Bu örnek türün CosmosClient yeni bir örneğini oluşturur ve bir DefaultAzureCredential örneği kullanarak kimlik doğrulaması yapar.

const credential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

const credential: TokenCredential = new DefaultAzureCredential();

const client = new CosmosClient({
    '<azure-cosmos-db-nosql-account-endpoint>',
    aadCredentials: credential
});

Veritabanı alma

client.database kullanarak cosmicworks adlı mevcut veritabanını alın.

const database = client.database('cosmicworks');

const database: Database = client.database('cosmicworks');

Bir kap al

products mevcut kapsayıcıyı database.container kullanarak alın.

const container = database.container('products');

const container: Container = database.container('products');

Öğe oluşturma

JSON'da seri hale getirmek istediğiniz tüm üyeleriyle yeni bir nesne oluşturun. Bu örnekte, türün benzersiz bir tanımlayıcısı ve kategori, ad, miktar, fiyat ve satış alanları vardır. kullanarak container.items.upsertkapsayıcıda bir öğe oluşturun. Bu yöntem, zaten mevcutsa öğeyi değiştirerek veya güncelleyerek etkili bir şekilde ekler.

const item = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response = await container.items.upsert(item);

const item: Product = {
    'id': 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

let response: ItemResponse<Product> = await container.items.upsert<Product>(item);

Bir öğe oku

Hem benzersiz tanımlayıcıyı (id) hem de bölüm anahtarı alanlarını kullanarak nokta okuma işlemi gerçekleştirin. ve belirli bir öğeyi verimli bir şekilde almak için kullanın.>

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response = await container.item(id, partitionKey).read();
let read_item = response.resource;

const id = 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb';
const partitionKey = 'gear-surf-surfboards';

let response: ItemResponse<Product> = await container.item(id, partitionKey).read<Product>();
let read_item: Product = response.resource!;

Sorgu öğeleri

kullanarak container.items.querybir kapsayıcıdaki birden çok öğe üzerinde sorgu gerçekleştirin. Bu parametreli sorguyu kullanarak belirtilen kategorideki tüm öğeleri bulun:

SELECT * FROM products p WHERE p.category = @category

kullanarak query.fetchAllsorgunun tüm sonuçlarını getirin. Sorgunun sonuçları arasında döngü yapın.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response = await container.items.query(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

const querySpec: SqlQuerySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

let response: FeedResponse<Product> = await container.items.query<Product>(querySpec).fetchAll();
for (let item of response.resources) {
    // Do something
}

Verilerinizi keşfetme

NoSQL verilerinizi keşfetmek için Azure Cosmos DB için Visual Studio Code uzantısını kullanın. Aşağıdakiler dahil ancak bunlarla sınırlı olmamak üzere temel veritabanı işlemleri gerçekleştirebilirsiniz:

Yapıştırma defteri veya sorgu düzenleyicisi kullanarak sorgu gerçekleştirme
Öğeleri değiştirme, güncelleştirme, oluşturma ve silme
Diğer kaynaklardan toplu verileri içeri aktarma
Veritabanlarını ve kapsayıcıları yönetme

Daha fazla bilgi için NoSQL verileri için Azure Cosmos DB’yi keşfetmek amacıyla Visual Studio Code uzantısını nasıl kullanacağınızı öğrenin.

Kaynakları temizleme

Örnek uygulamaya veya kaynaklara artık ihtiyacınız kalmadığında, ilgili dağıtımı ve tüm kaynakları kaldırın.

azd down

Aracılığıyla paylaş