Hızlı Başlangıç: Azure Cosmos DB SQL API hesabı kullanarak bir Node. js uygulaması oluşturmaQuickstart: Build a Node.js app using Azure Cosmos DB SQL API account

Azure Cosmos DB, Microsoft'un genel olarak dağıtılmış çok modelli veritabanı hizmetidir.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. Bu hizmetle belge, anahtar/değer ve grafik veritabanlarını kolayca oluşturup sorgulayabilir ve tüm bunları yaparken Azure Cosmos DB'nin genel dağıtım ve yatay ölçeklendirme özelliklerinden faydalanabilirsiniz.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Bu hızlı başlangıç belgesinde Azure portalını kullanarak bir Azure Cosmos DB SQL API hesabını, belge veritabanını ve kapsayıcısını nasıl oluşturacağınız anlatılmıştır.This quickstart demonstrates how to create an Azure Cosmos DB SQL API account, document database, and container using the Azure portal. Bu adımların ardından SQL JavaScript SDK'sını kullanarak bir konsol uygulaması derleyebilir ve çalıştırabilirsiniz.You then build and run a console app built on the SQL JavaScript SDK. Bu hızlı başlangıçta JavaScript SDK 2.0 sürümü kullanılmaktadır.This quickstart uses version 2.0 of the JavaScript SDK.

ÖnkoşullarPrerequisites

Yoksa bir Azure aboneliği, oluşturun bir ücretsiz bir hesap başlamadan önce.If you don't have an Azure subscription, create a free account before you begin.

Azure Cosmos DB’yi ücretsiz olarak bir Azure aboneliği olmadan, ücretsiz ve herhangi bir taahhütte bulunmadan deneyebilirsiniz.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Dilerseniz https://localhost:8081 URI’si ile birlikte Azure Cosmos DB Emulator da kullanabilirsiniz.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. Birincil Anahtar, Kimlik doğrulama istekleri bölümünde sağlanır.The Primary Key is provided in Authenticating requests.

  • Buna ek olarak:In addition:

Veritabanı hesabı oluşturmaCreate a database account

  1. Azure Portal oturum açın.Sign in to the Azure portal.

  2. Kaynak oluştur > Veritabanları > Azure Cosmos DB seçeneğini belirleyin.Select Create a resource > Databases > Azure Cosmos DB.

    Azure portalındaki Veritabanları bölmesi

  3. Üzerinde Azure Cosmos DB hesabı oluştur sayfasında, yeni Azure Cosmos hesabı için temel ayarları girin.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    AyarSetting DeğerValue AçıklamaDescription
    AbonelikSubscription Abonelik adıSubscription name Bu Azure Cosmos hesap için kullanmak istediğiniz Azure aboneliğini seçin.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Kaynak GrubuResource Group Kaynak grubu adıResource group name Bir kaynak grubu seçin ya da seçin Yeni Oluştur, ardından yeni bir kaynak grubu için benzersiz bir ad girin.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Hesap AdıAccount Name Benzersiz bir ad girinEnter a unique name Azure Cosmos hesabınızı tanımlamak için bir ad girin.Enter a name to identify your Azure Cosmos account. Girdiğiniz kimliğe documents.azure.com eklenerek URI'niz oluşturulacağından benzersiz bir kimlik kullanın.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    Kimlik yalnızca küçük harf, sayı ve kısa çizgi (-) karakterini içerebilir.The ID can only contain lowercase letters, numbers, and the hyphen (-) character. 3-31 karakter uzunluğunda olmalıdır.It must be between 3-31 characters in length.
    APIAPI Çekirdek (SQL)Core (SQL) API, oluşturulacak hesap türünü belirler.The API determines the type of account to create. Azure Cosmos DB, beş API sunar: Çekirdek (SQL) ve MongoDB, Gremlin graf verilerini, Azure tablosu ve Cassandra belge veriler için.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Şu anda, her bir API için ayrı bir hesap oluşturmanız gerekir.Currently, you must create a separate account for each API.

    Seçin çekirdek (SQL) SQL söz dizimini kullanarak bir belge veritabanı ve sorgu oluşturmak için.Select Core (SQL) to create a document database and query by using SQL syntax.

    SQL API'si hakkında daha fazla bilgi.Learn more about the SQL API.
    KonumLocation Kullanıcılarınıza en yakın bölgeyi seçinSelect the region closest to your users Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin.Select a geographic location to host your Azure Cosmos DB account. Bunları verilere en hızlı erişim sağlamak için kullanıcılarınıza en yakın konumu kullanın.Use the location that is closest to your users to give them the fastest access to the data.

    Azure Cosmos DB için yeni hesap sayfası

  4. İncele ve oluştur’u seçin.Select Review + create. Atlayabilirsiniz ve etiketleri bölümler.You can skip the Network and Tags sections.

  5. Hesap ayarları gözden geçirin ve ardından Oluştur.Review the account settings, and then select Create. Hesabı oluşturmak için birkaç dakika sürer.It takes a few minutes to create the account. Portal sayfasında görüntülenecek bekleyin dağıtımınız tamamlandıktan.Wait for the portal page to display Your deployment is complete.

    Azure portalındaki Bildirimler bölmesi

  6. Seçin kaynağa Git Azure Cosmos DB hesap sayfasına gidin.Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB hesap sayfası

Kapsayıcı eklemeAdd a container

Artık, bir veritabanı ve kapsayıcı oluşturmak için Azure portalında Veri Gezgini aracını kullanabilirsiniz.You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. Seçin Veri Gezgini > yeni kapsayıcı.Select Data Explorer > New Container.

    Ekle kapsayıcı alanı en sağda görüntülenir, görmek için sağa kaydırmanız gerekebilir.The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Azure portalındaki Veri Gezgini, kapsayıcı Ekle bölmesi

  2. İçinde kapsayıcısı Ekle sayfasında, yeni bir kapsayıcı için ayarları girin.In the Add container page, enter the settings for the new container.

    AyarSetting Önerilen değerSuggested value AçıklamaDescription
    Veritabanı KimliğiDatabase ID GörevlerTasks Girin ToDoList yeni bir veritabanı adı olarak.Enter ToDoList as the name for the new database. Veritabanı adı 1 ila 255 karakter içermeli ve içeremezler /, \\, #, ?, veya bir boşluk.Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. Denetleme sağlama veritabanı aktarım hızını seçeneği, bu veritabanındaki tüm kapsayıcılar arasında veritabanına sağlanan işleme paylaşmak olanak tanır.Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. Bu seçenek ile maliyet tasarrufları da yardımcı olur.This option also helps with cost savings.
    Aktarım hızıThroughput 400400 Aktarım hızını 400 istek birimi (RU/sn) saniyede bırakılacak.Leave the throughput at 400 request units per second (RU/s). Daha sonra gecikme süresini azaltmak isterseniz aktarım hızının ölçeğini artırabilirsiniz.If you want to reduce latency, you can scale up the throughput later.
    Kapsayıcı kimliğiContainer ID ÖğelerItems Girin öğeleri yeni kapsayıcınız için adı.Enter Items as the name for your new container. Kapsayıcı kimlikleri aynı karakter gereksinimleri veritabanı adlarına sahip.Container IDs have the same character requirements as database names.
    Bölüm anahtarıPartition key /kategori/category Bu makalede açıklanan örnek kullanır /Category bölüm anahtarı olarak.The sample described in this article uses /category as the partition key.

    Önceki ayarlara ek olarak, isteğe bağlı olarak ekleyebilirsiniz benzersiz anahtarlar kapsayıcısı için.In addition to the preceding settings, you can optionally add Unique keys for the container. Bu örnekte bu alanı boş bırakalım.Let's leave the field empty in this example. Benzersiz anahtarlar sayesinde geliştiriciler veritabanına bir veri bütünlüğü katmanı ekleyebilir.Unique keys provide developers with the ability to add a layer of data integrity to the database. Bir kapsayıcı oluştururken bir benzersiz anahtar ilkesi oluşturarak, bölüm anahtarı başına bir veya daha fazla değerlerin benzersiz olmasını sağlamak.By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. Daha fazla bilgi edinmek için Azure Cosmos DB'de benzersiz anahtarlar makalesine bakın.To learn more, refer to the Unique keys in Azure Cosmos DB article.

    Tamam’ı seçin.Select OK. Veri Gezgini yeni veritabanını ve kapsayıcı görüntüler.The Data Explorer displays the new database and container.

Örnek verileri eklemeAdd sample data

Şimdi Veri Gezgini'ni kullanarak yeni koleksiyonunuza veri ekleyebilirsiniz.You can now add data to your new collection using Data Explorer.

  1. Yeni veritabanı, Veri Gezgini'nin Koleksiyonlar bölmesinde görüntülenir.In Data Explorer, the new database appears in the Collections pane. Görevler veritabanını genişletin, Öğeler koleksiyonunu genişletin, Belgeler'e ve ardından Yeni Belge'ye tıklayın.Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

    Azure portalındaki Veri Gezgini'nde yeni belge oluşturma

  2. Şimdi koleksiyona aşağıdaki yapıya sahip bir belge ekleyin.Now add a document to the collection with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. JSON öğesini Belgeler sekmesine ekledikten sonra Kaydet'e tıklayın.Once you've added the json to the Documents tab, click Save.

    Azure portalında JSON verilerini kopyalayın ve Veri Gezgini'ne kaydedin

  4. id özelliği için benzersiz bir değer eklediğiniz yerde bir veya daha fazla belge oluşturun ve kaydedin ve diğer özellikleri uygun şekilde değiştirin.Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Azure Cosmos DB, verilerinizin bir şemaya uygun olmasını şart koşmadığı için yeni belgelerinizin yapısını istediğiniz şekilde oluşturabilirsiniz.Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

Verilerinizi sorgulayınQuery your data

Almak ve verilerinizi filtrelemek için veri Gezgini'ndeki sorguları kullanabilirsiniz.You can use queries in Data Explorer to retrieve and filter your data.

  1. Üst kısmındaki belgeleri sekmesinde veri Gezgini'nde, varsayılan sorguyu inceleyin SELECT * FROM c.At the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. Bu sorguyu alır ve kimliği sırayla koleksiyondaki tüm belgeleri görüntüler.This query retrieves and displays all documents in the collection in ID order.

    Veri Gezgini’ndeki varsayılan sorgu: SELECT * FROM c

  2. Sorguyu değiştirmek için seçin filtreyi Düzenle, varsayılan sorguyla değiştirin ORDER BY c._ts DESCve ardından Filtre Uygula.To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    ORDER BY c._ts DESC ekleyerek ve Filtre Uygula’ya tıklayarak varsayılan sorguyu değiştirin

    Şimdi ikinci belgeniz, zaman damgası göre azalan sırayla düzenleyin belgeleri ilk listelenen değiştirilmiş sorguyu görüntüler.The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    ORDER BY c._ts DESC sorgu ve Filtre Uygula'i tıklatarak değiştirildi

Tanıdık SQL söz dizimi, desteklenen herhangi biri girebilirsiniz SQL sorguları sorgu koşulu kutusuna içinde.If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. Veri Gezgini, saklı yordamlar, UDF'ler ve Tetikleyiciler için sunucu tarafı iş mantığı oluşturma için de kullanabilirsiniz.You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

Veri Gezgini, apı'lerdeki tüm yerleşik programlı veri erişim özelliklere için kolayca Azure portal erişmenizi sağlar.Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. Portal ayrıca aktarım hızı ölçeklendirme, anahtarları ve bağlantı dizelerini almak ve ölçümleri ve SLA'ları, Azure Cosmos DB hesabınız için gözden geçirmek için kullanın.You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Örnek uygulamayı kopyalamaClone the sample application

Şimdi GitHub'dan bir SQL API uygulaması kopyalayalım, bağlantı dizesini ayarlayalım ve uygulamayı çalıştıralım.Now let's clone a SQL API app from GitHub, set the connection string, and run it.

  1. Bir komut istemini açın, git-samples adlı yeni bir klasör oluşturun ve komut istemini kapatın.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. Git Bash gibi bir Git terminal penceresi açın ve örnek uygulamayı yüklemek üzere yeni bir klasör olarak değiştirmek için cd komutunu kullanın.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Örnek depoyu kopyalamak için aşağıdaki komutu çalıştırın.Run the following command to clone the sample repository. Bu komut bilgisayarınızda örnek uygulamanın bir kopyasını oluşturur.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
    

Kodu gözden geçirinReview the code

Bu adım isteğe bağlıdır.This step is optional. Veritabanı kaynaklarının kodda nasıl oluşturulduğunu öğrenmekle ilgileniyorsanız aşağıdaki kod parçacıklarını gözden geçirebilirsiniz.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Aksi durumda, Bağlantı dizenizi güncelleştirme bölümüne atlayabilirsiniz.Otherwise, you can skip ahead to Update your connection string.

JavaScript SDK'sının eski sürümlerini kullandıysanız 'koleksiyon' ve 'belge' terimlerine aşina olabilirsiniz.Note, if you are familiar with the previous version of the JavaScript SDK, you may be used to seeing the terms 'collection' and 'document.' Azure Cosmos DB birden fazla API modelini desteklediğinden JavaScript SDK'sının 2.0 ve üzeri sürümlerinde kapsayıcının içeriğini tanımlamak için koleksiyon, grafik veya tablo olabilen 'kapsayıcı' ile 'öğe' terimleri kullanılmaktadır.Because Azure Cosmos DB supports multiple API models, version 2.0+ of the JavaScript SDK uses the generic terms 'container', which may be a collection, graph, or table and 'item' to describe the content of the container.

Aşağıdaki kod parçacıklarının tamamı, app.js dosyasından alınmıştır.The following snippets are all taken from the app.js file.

  • CosmosClient başlatılır.The CosmosClient is initialized.

    const client = new CosmosClient({ endpoint: endpoint, auth: { masterKey: masterKey } });
    
  • Yeni bir veritabanı oluşturulur.A new database is created.

    const { database } = await client.databases.createIfNotExists({ id: databaseId });
    
  • Yeni bir kapsayıcı (koleksiyon) oluşturulur.A new container (collection) is created.

    const { container } = await client.database(databaseId).containers.createIfNotExists({ id: containerId });
    
  • Bir öğe (belge) oluşturulur.An item (document) is created.

    const { item } = await client.database(databaseId).container(containerId).items.create(itemBody);
    
  • JSON üzerinden bir SQL sorgusu gerçekleştirilir.A SQL query over JSON is performed.

    const querySpec = {
        query: "SELECT VALUE r.children FROM root r WHERE r.lastName = @lastName",
        parameters: [
            {
                name: "@lastName",
                value: "Andersen"
            }
        ]
    };
    
    const { result: results } = await client.database(databaseId).container(containerId).items.query(querySpec).toArray();
    for (var queryResult of results) {
        let resultString = JSON.stringify(queryResult);
        console.log(`\tQuery returned ${resultString}\n`);
    }
    

Bağlantı dizenizi güncelleştirmeUpdate your connection string

Bu adımda Azure portalına dönerek bağlantı dizesi bilgilerinizi kopyalayıp uygulamaya ekleyin.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. Azure PortalAzure Cosmos hesabınızda, sol gezinti bölmesinde anahtarlar' a ve ardından okuma-yazma anahtarları' na tıklayın.In the Azure portal, in your Azure Cosmos account, in the left navigation click Keys, and then click Read-write Keys. Ekranın sağ tarafındaki kopyalama düğmelerini kullanarak URI ve Birincil Anahtar değerlerini kopyalayarak sonraki adımda config.js dosyasına yapıştırın.You'll use the copy buttons on the right side of the screen to copy the URI and Primary Key into the config.js file in the next step.

    Azure portalında erişim anahtarı görüntüleme ve kopyalama, Anahtarlar dikey penceresi

  2. config.js dosyasını açın.In Open the config.js file.

  3. Portaldaki URI değerinizi kopyalayın (kopyalama düğmesini kullanarak) ve config.js dosyasına uç nokta değeri olarak yapıştırın.Copy your URI value from the portal (using the copy button) and make it the value of the endpoint key in config.js.

    config.endpoint = "https://FILLME.documents.azure.com"

  4. Ardından portaldaki BİRİNCİL ANAHTAR değerinizi kopyalayıp config.js dosyasına config.primaryKey değeri olarak yapıştırın.Then copy your PRIMARY KEY value from the portal and make it the value of the config.primaryKey in config.js. Bu adımlarla uygulamanıza Azure Cosmos DB ile iletişim kurması için gereken tüm bilgileri eklemiş oldunuz.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

    config.primaryKey = "FILLME"

Uygulamayı çalıştırmaRun the app

  1. Gerekli npm modüllerini yüklemek için bir terminalde npm install komutunu çalıştırınRun npm install in a terminal to install required npm modules

  2. Node.js uygulamanızı başlatmak için bir terminalde node app.js komutunu çalıştırın.Run node app.js in a terminal to start your node application.

Şimdi Veri Gezgini'ne dönüp bu yeni verileri görebilir, sorgulayabilir, değiştirebilir ve onlarla çalışabilirsiniz.You can now go back to Data Explorer and see query, modify, and work with this new data.

Azure portalında SLA'ları gözden geçirmeReview SLAs in the Azure portal

Azure portalı, Cosmos DB hesabı aktarım hızını, depolama, kullanılabilirlik, gecikme süresi ve tutarlılık izler.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Grafikler ile ilgili ölçümler için bir Azure Cosmos DB hizmet düzeyi sözleşmesi (SLA) gerçek performans karşılaştırıldığında SLA değeri gösterir.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Bu paketi ölçümleri saydam, SLA izleme sağlar.This suite of metrics makes monitoring your SLAs transparent.

Ölçümler ve SLA'ları gözden geçirmek için:To review metrics and SLAs:

  1. Seçin ölçümleri Cosmos DB hesabınızın Gezinti menüsünde.Select Metrics in your Cosmos DB account's navigation menu.

  2. Bir sekme gibi seçin gecikme, sağ taraftaki bir zaman çerçevesi'ni seçin.Select a tab such as Latency, and select a timeframe on the right. Karşılaştırma gerçek ve SLA grafikleri satırlarda.Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB ölçüm paketi

  3. Diğer sekmelerdeki ölçümleri gözden geçirin.Review the metrics on the other tabs.

Kaynakları temizlemeClean up resources

Azure Cosmos DB hesabı ve web uygulaması ile işiniz bittiğinde, daha fazla ücret ödememeniz oluşturduğunuz Azure kaynaklarını silebilirsiniz.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Kaynakları silmek için:To delete the resources:

  1. Azure portalının en sol tarafındaki Kaynak gruplarını seçin.In the Azure portal, select Resource groups on the far left. Soldaki menü daraltılmışsa, seçin genişletme düğmesi genişletin.If the left menu is collapsed, select Expand button to expand it.

  2. Bu Hızlı Başlangıç için oluşturduğunuz kaynak grubunu seçin.Select the resource group you created for this quickstart.

    Azure portalında ölçümler

  3. Yeni pencerede seçin kaynak grubunu Sil.In the new window, select Delete resource group.

    Azure portalında ölçümler

  4. Sonraki penceresinde adını, kaynak grubunu silin ve ardından Sil.In the next window, type the name of the resource group to delete, and then select Delete.

Sonraki adımlarNext steps

Bu hızlı başlangıçta Azure Cosmos hesabı oluşturmayı, Veri Gezgini kullanarak bir kapsayıcı oluşturmayı ve bir uygulamayı çalıştırmayı öğrendiniz.In this quickstart, you've learned how to create an Azure Cosmos account, create a container using the Data Explorer, and run an app. Şimdi Cosmos DB hesabınıza ek veri aktarabilirsiniz.You can now import additional data to your Cosmos DB account.