Aracılığıyla paylaş

Hızlı Başlangıç: Node.js için Apache Cassandra istemci kitaplığı için Azure Cosmos DB

  • Şunlara uygulanır: ✅ Apache Cassanda

Yapılandırılmamış verileri depolamak, yönetmek ve sorgulamak için Node.js için Apache Cassandra için Azure Cosmos DB istemci kitaplığını kullanmaya başlayın. Yeni bir hesap oluşturmak, Node.js istemci kitaplığı yüklemek, hesaba bağlanmak, yaygın işlemler gerçekleştirmek ve son örnek verilerinizi sorgulamak için bu kılavuzdaki adımları izleyin.

API başvuru belgeleri | Kitaplık kaynak kodu | Paketi (npm)

Önkoşullar

  • Azure aboneliği

  • Azure Cloud Shell'deAzure CLI'nın en son sürümü.

    • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız komutunu kullanarak az login Azure CLI'da oturum açın.
  • Node.js 22 veya üzeri

Kurulum

İlk olarak, bu kılavuz için hesap ve geliştirme ortamını ayarlayın. Bu bölümde hesap oluşturma, kimlik bilgilerini alma ve geliştirme ortamınızı hazırlama işlemi boyunca size yol gösterilir.

Hesap oluştur

Apache Cassandra hesabı için bir API oluşturarak başlayın. Hesap oluşturulduktan sonra anahtar alanını ve tablo kaynaklarını oluşturun.

  1. Henüz bir hedef kaynak grubunuz yoksa, aboneliğinizde yeni bir kaynak grubu oluşturmak için komutunu kullanın az group create .

    az group create \
    --name "<resource-group-name>" \
    --location "<location>"

  2. Varsayılan ayarlarla az cosmosdb create Apache Cassandra için yeni bir Azure Cosmos DB hesabı oluşturmak için komutunu kullanın.

    az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

  3. az cosmosdb cassandra keyspace create kullanarak cosmicworks adlı yeni bir anahtar alanı oluşturun.

    az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

  4. Çok satırlı bash komutunu kullanarak şemanızı temsil eden yeni bir JSON nesnesi oluşturun. Ardından komutunu kullanarak az cosmosdb cassandra table create adlı productsyeni bir tablo oluşturun.

    schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

    az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Kimlik bilgilerini alma

Şimdi, son oluşturulan hesaba bağlantı oluşturmak için kullanılacak istemci kitaplığının parolasını alın.

  1. Hesabın iletişim noktası ve kullanıcı adını almak için az cosmosdb show kullanın.

    az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

  2. Önceki komutların çıkışındaki contactPoint ve username özelliklerinin değerlerini kaydedin. Bu özelliklerin değerleri, bu kılavuzun devamında kitaplığa bağlanmak için kullandığınız kişi noktası ve kullanıcı adıdır .

  3. az cosmosdb keys list, hesabın anahtarlarını almak için kullanın.

    az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

  4. Önceki komutların çıkışından primaryMasterKey özelliğinin değerini kaydedin. Bu özelliğin değeri, bu kılavuzun ilerleyen bölümlerinde kitaplığa bağlanmak için kullandığınız paroladır .

Geliştirme ortamını hazırlama

Ardından geliştirme ortamınızı yeni bir proje ve istemci kitaplığıyla yapılandırın. Bu adım, bu kılavuzun geri kalanına geçmeden önce gereken son önkoşuldur.

  1. Boş bir klasörden başlayın.

  2. Yeni bir modül başlatın.

    npm init es6 --yes

  3. cassandra-driver Node Package Manager'dan (npm) paketi yükleyin.

    npm install --save cassandra-driver

  4. index.js dosyasını oluşturun.

  1. Boş bir klasörde başlayın.

  2. Yeni bir modül başlatın.

    npm init es6 --yes

  3. typescript Node Package Manager'dan (npm) paketi yükleyin.

    npm install --save-dev typescript

  4. tsx Paketi npm'den yükleyin.

    npm install --save-dev tsx

  5. cassandra-driver Paketi npm'den yükleyin.

    npm install --save cassandra-driver

  6. Derleyiciyi ()tsc kullanarak TypeScript projesini başlatın.

    npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

  7. index.ts dosyasını oluşturun.

Nesne modeli

Açıklama
Client Kümeye belirli bir bağlantıyı temsil eder
Mapper Sorgu çalıştırmak için kullanılan Cassandra Sorgu Dili (CQL) istemcisi

Kod örnekleri

İstemcinin kimliğini doğrulama

Bu kılavuzda daha önce toplanan kimlik bilgilerini kullanarak istemcinin kimliğini doğrulayarak başlayın.

  1. tümleşik geliştirme ortamınızda (IDE) index.js dosyasını açın.

  2. Modülden aşağıdaki türleri içeri aktarın cassandra-driver :

    • cassandra
    • cassandra.Client
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

  3. Bu kılavuzun önceki bölümlerinde toplanan kimlik bilgileri için dize sabit değişkenleri oluşturun. Değişkenleri username, passwordve contactPointolarak adlandırın.

    const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';

  4. Apache Cassandra için Azure Cosmos DB hesabınızı oluşturduğunuz bölge için başka bir dize değişkeni oluşturun. Bu değişkene adını verin region.

    const region = '<azure-region>';

  5. Önceki adımlarda belirtilen kimlik bilgileriyle yeni PlainTextAuthProvider bir nesne oluşturun.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Önceki adımlarda oluşturulan kimlik bilgilerini ve yapılandırma değişkenlerini kullanarak bir Client nesne oluşturun.

    let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

  7. Kümeye eş zamansız olarak bağlanın.

    await client.connect();

  8. cosmicworks anahtar uzayını ve product tabloyu hedefleyen yeni bir eşleyici oluşturun. Eşleyiciyi Product olarak adlandırın.

    const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  9. forModel işlevini ve Product eşleyici adını kullanarak bir eşleyici örneği oluşturun.

    const productMapper = mapper.forModel('Product');

  1. tümleşik geliştirme ortamınızda (IDE) index.ts dosyasını açın.

  2. Modülden aşağıdaki türleri içeri aktarın cassandra-driver :

    • cassandra.auth
    • cassandra.mapping
    • cassandra.types
    • cassandra.Client
    • cassandra.ClientOptions
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;

  3. Bu kılavuzun önceki bölümlerinde toplanan kimlik bilgileri için dize sabit değişkenleri oluşturun. Değişkenleri username, passwordve contactPointolarak adlandırın.

    const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';

  4. Apache Cassandra için Azure Cosmos DB hesabınızı oluşturduğunuz bölge için başka bir dize değişkeni oluşturun. Bu değişkene adını verin region.

    const region: string = '<azure-region>';

  5. Önceki adımlarda belirtilen kimlik bilgileriyle yeni PlainTextAuthProvider bir nesne oluşturun.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Aktarım katmanı güvenliği (TLS) 1.2 protokolunu kullanmanızı sağlayan seçeneklerle anonim bir nesne oluşturun.

    let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};

  7. Önceki adımlarda oluşturulan kimlik bilgilerini ve yapılandırma değişkenlerini kullanarak bir ClientOptions nesne oluşturun.

    let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

  8. Oluşturucudaki değişkenini Client kullanarak bir clientOptions nesne oluşturun.

    let client = new Client(clientOptions);

  9. Kümeye eş zamansız olarak bağlanın.

    await client.connect();

  10. cosmicworks anahtar uzayını ve product tabloyu hedefleyen yeni bir eşleyici oluşturun. Eşleyiciyi Product olarak adlandırın.

    const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  11. forModel işlevini ve Product eşleyici adını kullanarak bir eşleyici örneği oluşturun.

    const productMapper = mapper.forModel('Product');

Uyarı

Kimlik doğrulamasını basitleştirmek için bu kılavuzda tam aktarım katmanı güvenliği (TLS) doğrulaması devre dışı bırakılmıştır. Üretim dağıtımları için doğrulamayı tam olarak etkinleştirin.

Verileri ekleme ve güncelleme

Ardından, yeni verileri bir tabloya ekle. Yükseltme, aynı verilerin tabloda zaten var olup olmadığına bağlı olarak verilerin uygun şekilde oluşturulmasını veya değiştirilmesini sağlar.

  1. adlı productdeğişkende yeni bir nesne oluşturun.

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

  2. Önceki adımda oluşturulan insert değişkenini geçirerek product işlevini zaman uyumsuz olarak çağırın.

    await productMapper.insert(product);

  1. Bu kılavuzun önceki bölümlerinde oluşturulan tabloya karşılık gelen alanlarla adlı Product yeni bir arabirim tanımlayın.

    Türü
    Id string
    Name string
    Category string
    Quantity int
    Price decimal
    Clearance bool 
    interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}

    Tip

    Node.jsiçinde, bu türü başka bir dosyada veya var olan dosyanın sonunda oluşturabilirsiniz.

  2. türünde Productyeni bir nesne oluşturun. nesnesini adlı productbir değişkende depolayın.

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

  3. Önceki adımda oluşturulan insert değişkenini geçirerek product işlevini zaman uyumsuz olarak çağırın.

    await productMapper.insert(product);

Veriyi oku

Ardından, tabloya daha önce yüklenmiş olan verileri okuyun.

  1. adlı filteranonim bir nesne oluşturun. Bu nesneye, bu kılavuzda daha önce oluşturulan ürünle aynı değere sahip adlı id bir özellik ekleyin.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. değişkenini get geçiren eşleyicinin işlevini çağırın filter . Sonucu adlı matchedProductbir değişkende depolayın.

    let matchedProduct = await productMapper.get(filter);

  1. adlı filteranonim bir nesne oluşturun. Bu nesneye, bu kılavuzda daha önce oluşturulan ürünle aynı değere sahip adlı id bir özellik ekleyin.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. değişkenini get geçiren eşleyicinin işlevini çağırın filter . Sonucu matchedProducttüründe Product adlı bir değişkende depolayın.

    let matchedProduct: Product = await productMapper.get(filter);

Sorgu verileri

Son olarak, tablodaki belirli bir filtreyle eşleşen tüm verileri bulmak için bir sorgu kullanın.

  1. Aynı query alana sahip öğelerle eşleşen bir CQL sorgusuyla adlı category yeni bir dize değişkeni oluşturun.

    const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. adlı paramsanonim bir nesne oluşturun. Bu nesneye, bu kılavuzda daha önce oluşturulan ürünle aynı değere sahip adlı category bir özellik ekleyin.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. execute ve query değişkenlerini argüman olarak geçirerek params işlevini zaman uyumsuz olarak çağırın. Sonucun rows özelliğini adlı matchedProductsbir değişken olarak depolayın.

    let { rows: matchedProducts } = await client.execute(query, params);

  4. Yöntemini ürün dizisinde çağırarak foreach sorgu sonuçları üzerinde yineleme yapın.

    matchedProducts.forEach(product => {
    // Do something here with each result
});

  1. Aynı query alana sahip öğelerle eşleşen bir CQL sorgusuyla adlı category yeni bir dize değişkeni oluşturun.

    const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. adlı paramsanonim bir nesne oluşturun. Bu nesneye, bu kılavuzda daha önce oluşturulan ürünle aynı değere sahip adlı category bir özellik ekleyin.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. execute ve query değişkenlerini argüman olarak geçirerek params işlevini zaman uyumsuz olarak çağırın. Sonucu resulttüründe types.ResultSet adlı bir değişkende depolayın.

    let result: types.ResultSet = await client.execute(query, params);

  4. Sonucun rows özelliğini, türü matchedProducts olan ve Product[] adlı bir değişken olarak depolayın.

    let matchedProducts: Product[] = result.rows;

  5. Yöntemini ürün dizisinde çağırarak foreach sorgu sonuçları üzerinde yineleme yapın.

    matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});

Kodu çalıştır

Uygulama dizininizde bir terminal kullanarak yeni oluşturulan uygulamayı çalıştırın.

node index.js

npx tsx index.ts

Kaynakları temizle

Hesaba artık ihtiyacınız kalmadığında, kaynağı silerek hesabı Azure aboneliğinizden kaldırın.

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Sonraki adım

Apache Cassandra için Azure Cosmos DB'ye genel bakış

  • Last updated on