Share via

JavaScript kullanarak NoSQL için Azure Cosmos DB kullanmaya başlama

  • Makale

UYGULANANLAR: NoSQL

Bu makalede, JavaScript SDK'sını kullanarak NoSQL için Azure Cosmos DB'ye nasıl bağlanabileceğiniz gösterilmektedir. Bağlandıktan sonra veritabanları, kapsayıcılar ve öğeler üzerinde işlemler gerçekleştirebilirsiniz.

Paket (npm) | Örnekler | API başvurusu | Kitaplık kaynak kodu | Geri BildirimDeğer Ver

Ön koşullar

Yerel projenizi ayarlama

  1. Bash kabuğunda JavaScript projeniz için yeni bir dizin oluşturun.

    mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples

  2. konsol şablonuyla komutunu kullanarak npm init yeni bir JavaScript uygulaması oluşturun.

    npm init -y

  3. NoSQL için Azure Cosmos DB JavaScript SDK'sı için gerekli bağımlılığı yükleyin.

    npm install @azure/cosmos

NoSQL için Azure Cosmos DB'ye Bağlan

Azure Cosmos DB'nin NoSQL API'sine bağlanmak için sınıfının bir örneğini CosmosClient oluşturun. Bu sınıf, veritabanlarında tüm işlemleri gerçekleştirmek için başlangıç noktasıdır. CosmosClient sınıfını kullanarak NoSQL hesabına yönelik bir API'ye bağlanmanın üç temel yolu vardır:

Uç nokta ve anahtarla Bağlan

CosmosClient için en yaygın oluşturucunun iki parametresi vardır:

Parametre Örnek değer Tanım
accountEndpoint COSMOS_ENDPOINT ortam değişkeni Tüm istekler için kullanılacak NoSQL uç noktası API'si
authKeyOrResourceToken COSMOS_KEY ortam değişkeni Kimlik doğrulaması sırasında kullanılacak hesap anahtarı veya kaynak belirteci

Hesap uç noktanızı ve anahtarınızı alma

  1. resourceGroupName için bir kabuk değişkeni oluşturun.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. az cosmosdb list Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. komutunu kullanarak hesap için NoSQL uç nokta URI'sine yönelik API'yi az cosmosdb show alın.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. komutuyla hesabın anahtar listesinden BİRİnCİl ANAHTAR'ı az-cosmosdb-keys-list bulun.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. URI ve BİRİnCİl ANAHTAR değerlerini kaydedin. Bu kimlik bilgilerini daha sonra kullanacaksınız.

Kodunuzda URI ve BİRİnCİl ANAHTAR değerlerini kullanmak için, bunları uygulamayı çalıştıran yerel makinedeki yeni ortam değişkenlerinde kalıcı hale getirin.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Hesap uç noktası ve anahtarıyla CosmosClient oluşturma

ve ortam değişkenlerini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINTCOSMOS_KEY yeni bir örneğini oluşturun.

const client = new CosmosClient({ endpoint, key });

bağlantı dizesi ile Bağlan

CosmosClient için başka bir oluşturucu yalnızca tek bir parametre içerir:

Parametre Örnek değer Tanım
accountEndpoint COSMOS_ENDPOINT ortam değişkeni Tüm istekler için kullanılacak NoSQL uç noktası API'si
connectionString COSMOS_CONNECTION_STRING ortam değişkeni NoSQL hesabı için API'ye Bağlan dize

Hesap bağlantı dizesi alma

  1. az cosmosdb list Komutunu kullanarak kaynak grubunuzdaki ilk Azure Cosmos DB hesabının adını alın ve accountName kabuk değişkeninde depolayın.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. komutuyla hesabın bağlantı dizesi listesinden BİRİnCİl BAĞLANTI DIZESİ'niaz-cosmosdb-keys-list bulun.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Kodunuzda BİRİnCİl BAĞLANTI DIZESİ değerini kullanmak için, uygulamayı çalıştıran yerel makinede yeni bir ortam değişkeninde kalıcı hale getirmek.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

bağlantı dizesi ile CosmosClient oluşturma

Tek parametre olarak ortam değişkeniyle COSMOS_CONNECTION_STRING CosmosClient sınıfının yeni bir örneğini oluşturun.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Microsoft kimlik platformu kullanarak Bağlan

Microsoft kimlik platformu ve Microsoft Entra Id kullanarak NoSQL hesabına yönelik API'nize bağlanmak için bir güvenlik sorumlusu kullanın. Sorumlunun tam türü, uygulama kodunuzu nerede barındırdığınıza bağlıdır. Aşağıdaki tablo bir hızlı başvuru kılavuzu görevi görür.

Uygulamanın çalıştığı yer Güvenlik sorumlusu
Yerel makine (geliştirme ve test) Kullanıcı kimliği veya hizmet sorumlusu
Azure Yönetilen kimlik
Azure dışındaki sunucular veya istemciler Hizmet sorumlusu

Ithalat @azure/identity

@azure/identity npm paketi, tüm Azure SDK kitaplıkları arasında paylaşılan temel kimlik doğrulama işlevselliğini içerir.

  1. komutunu kullanarak @azure/identity npm paketini içeri aktarınnpm install.

    npm install @azure/identity

  2. Kod düzenleyicinizde bağımlılıkları ekleyin.

    const { DefaultAzureCredential } = require("@azure/identity");

Varsayılan kimlik bilgisi uygulamasıyla CosmosClient oluşturma

Yerel bir makinede test ediyorsanız veya uygulamanız yönetilen kimlikler için doğrudan destekle Azure hizmetlerinde çalışacaksa bir örnek oluşturarak OAuth DefaultAzureCredential belirteci alın. Ardından ortam değişkeni ve TokenCredential nesnesini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT yeni bir örneğini oluşturun.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Özel kimlik bilgisi uygulamasıyla CosmosClient oluşturma

Uygulamayı Azure dışına dağıtmayı planlıyorsanız JavaScript için @azure/kimlik istemci kitaplığındaki diğer sınıfları kullanarak bir OAuth belirteci alabilirsiniz. Bu diğer sınıflar da sınıfından TokenCredential türetilir.

Bu örnekte, istemci ve kiracı tanımlayıcılarının yanı sıra bir istemci gizli dizisi kullanarak bir örnek oluştururuz ClientSecretCredential .

Bir uygulamayı Microsoft Entra Id'ye kaydederken istemci kimliğini, kiracı kimliğini ve istemci gizli dizisini alabilirsiniz. Microsoft Entra uygulamalarını kaydetme hakkında daha fazla bilgi için bkz. Uygulamayı Microsoft kimlik platformu kaydetme.

Ortam değişkeni ve TokenCredential nesnesini parametre olarak kullanarak CosmosClient sınıfının COSMOS_ENDPOINT yeni bir örneğini oluşturun.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Uygulamanızı derleme

Uygulamanızı oluştururken kodunuz öncelikli olarak dört tür kaynakla etkileşim kurar:

  • Azure Cosmos DB verileriniz için benzersiz üst düzey ad alanı olan NoSQL hesabı için API.

  • Hesabınızdaki kapsayıcıları düzenleyen veritabanları.

  • Veritabanınızdaki tek tek öğeler kümesini içeren kapsayıcılar.

  • Kapsayıcınızdaki bir JSON belgesini temsil eden öğeler.

Aşağıdaki diyagramda bu kaynaklar arasındaki ilişki gösterilmektedir.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Her kaynak türü bir veya daha fazla ilişkili sınıfla temsil edilir. En yaygın sınıfların listesi aşağıdadır:

Sınıf Tanım
CosmosClient Bu sınıf, Azure Cosmos DB hizmeti 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.
Database Bu sınıf, hizmette henüz var olabilen veya var olmayan 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.
Container Bu sınıf, hizmette henüz mevcut olmayan bir kapsayıcıya başvurudur. Kapsayıcıyla çalışmaya çalıştığınızda sunucu tarafı doğrulanır.

Aşağıdaki kılavuzlarda, uygulamanızı derlemek için bu sınıfların her birinin nasıl kullanılacağı gösterilmektedir.

Kılavuz Tanım
Veritabanı oluşturma Veritabanları oluşturma
Kapsayıcı oluşturma Kapsayıcı oluşturma
Öğe oluşturma ve okuma Belirli bir öğeyi nokta okuma
Sorgu öğeleri Birden çok öğeyi sorgulama

Ayrıca bkz.

Sonraki adımlar

Artık NoSQL hesabı için bir API'ye bağlandığınıza göre, veritabanlarını oluşturmak ve yönetmek için sonraki kılavuzu kullanın.

JavaScript kullanarak NoSQL için Azure Cosmos DB'de veritabanı oluşturma