Hızlı Başlangıç: Azure Cosmos DB SQL API hesabı kullanarak bir .NET web uygulaması derlemeQuickstart: Build a .NET web app using SQL API account in Azure Cosmos DB

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. Azure Cosmos DB, hızlı bir şekilde oluşturmak ve anahtar/değer veritabanları, belge veritabanları ve her biri genel dağıtım ve yatay ölçeklendirme özelliklerinden faydalanabilirsiniz Azure Cosmos DB'nin grafik veritabanlarını sorgulamak için kullanabilirsiniz.You can use Azure Cosmos DB to quickly create and query key/value databases, document databases, 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ıçta bir Azure Cosmos DB oluşturmak için Azure portalını kullanmayı gösteren SQL API hesabı, bir belge veritabanı ve koleksiyon oluşturma ve veri koleksiyonuna ekleyin.This quickstart demonstrates how to use the Azure portal to create an Azure Cosmos DB SQL API account, create a document database and collection, and add data to the collection. Daha sonra bir SQL .NET SDK'sı koleksiyona daha fazla veri eklemek için web uygulaması.You then use a SQL .NET SDK web app to add more data to the collection.

Bu hızlı başlangıçta, Veri Gezgini Azure Portalı'nda veritabanı ve koleksiyonunu oluşturmak için kullanın.In this quickstart, you use Data Explorer in the Azure portal to create the database and collection. .NET örnek kodu kullanarak veritabanı ve koleksiyonu da oluşturabilirsiniz.You can also create the database and collection by using the .NET sample code. Daha fazla bilgi için bkz. .NET kodu gözden.To learn more, see Review the .NET code.

ÖnkoşullarPrerequisites

Visual Studio 2019 yüklü Azure geliştirme iş akışı ileVisual Studio 2019 with the Azure development workflow installed

Bir Azure aboneliği veya ücretsiz Azure Cosmos DB deneme hesabıAn Azure subscription or free Azure Cosmos DB trial account

Azure Cosmos DB hesabı oluşturmaCreate an Azure Cosmos DB 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ı

Bir veritabanı ve koleksiyon EkleAdd a database and a collection

Azure portalında Veri Gezgini, veritabanı ve koleksiyon oluşturmak için kullanabilirsiniz.You can use the Data Explorer in the Azure portal to create a database and collection.

  1. Seçin Veri Gezgini Azure Cosmos DB üzerinde sol gezinti bölmesinden hesap sayfası ve ardından yeni kapsayıcı.Select Data Explorer from the left navigation on your Azure Cosmos DB account page, and then select New Container.

    Hemen görmek için kaydırmanız gerekebilir Ekle kapsayıcı penceresi.You may need to scroll right to see the Add Container window.

    Azure portalındaki Veri Gezgini, koleksiyon Ekle bölmesi

  2. İçinde kapsayıcısı Ekle bölmesinde, yeni bir koleksiyon için ayarları girin.In the Add container pane, enter the settings for the new collection.

    AyarSetting Önerilen değerSuggested value AçıklamaDescription
    Veritabanı KimliğiDatabase ID ToDoListToDoList 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 Yeni koleksiyonunuzun adı olarak Öğeler girin.Enter Items as the name for your new collection. Koleksiyon kimlikleri aynı karakter gereksinimleri veritabanı adlarına sahip.Collection 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.

    Ekleme benzersiz anahtarlar bu örneğin.Don't add Unique keys for this example. Benzersiz anahtarlar oluşturulduğunda, bölüm anahtarı başına bir veya daha fazla değer sağlayarak veritabanına bir veri bütünlüğü katmanı eklemenize olanak sağlar.Unique keys let you add a layer of data integrity to the database by ensuring the uniqueness of one or more values per partition key. Daha fazla bilgi için Azure Cosmos DB'de benzersiz anahtarlar.For more information, see Unique keys in Azure Cosmos DB.

  3. Tamam’ı seçin.Select OK. Veri Gezgini, yeni veritabanını ve oluşturduğunuz kapsayıcı görüntüler.The Data Explorer displays the new database and the container that you created.

Veritabanınıza veri eklemekAdd data to your database

Veri Gezgini'ni kullanarak yeni veritabanınıza veri ekleyin.Add data to your new database using Data Explorer.

  1. İçinde Veri Gezgini, genişletme ToDoList veritabanı ve genişletin öğeleri kapsayıcı.In Data Explorer, expand the ToDoList database, and expand the Items container. Ardından, öğelerive ardından yeni öğe.Next, select Items, and then select New Item.

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

  2. Aşağıdaki yapıya sağ alt tarafında belgeye eklediğiniz belgeleri bölmesi:Add the following structure to the document on the right side of the Documents pane:

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Kaydet’i seçin.Select Save.

    JSON verilerini kopyalayın ve kaydedin Azure Portalı'nda veri Gezgini'nde seçin

  4. Seçin yeni belge yeniden oluşturmak ve başka bir belgeyi benzersiz bir kaydetme idve diğer özellikler ve değerleri.Select New Document again, and create and save another document with a unique id, and any other properties and values you want. Azure Cosmos DB, verileriniz üzerinde herhangi bir şema koymaz çünkü belgelerinizi herhangi bir yapı olabilir.Your documents can have any structure, because 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.

.NET web uygulaması verileri yönetmek için kullanmaUse the .NET web app to manage data

Ne kadar kolay olduğunu, Azure Cosmos DB verilerle program aracılığıyla çalışmanın, örnek SQL API .NET web uygulaması kopyalayalım görmek için bağlantı dizesini güncelleştirin ve verilerinizi güncelleştirmek için uygulamayı çalıştırın.To see how easy it is to work with your Azure Cosmos DB data programmatically, clone the sample SQL API .NET web app from GitHub, update the connection string, and run the app to update your data.

Veritabanı ve kapsayıcı .NET örnek kodu kullanarak da oluşturabilirsiniz.You could also create the database and the container by using the .NET sample code. Daha fazla bilgi için bkz. .NET kodu gözden.To learn more, see Review the .NET code.

Örnek uygulamayı kopyalamaClone the sample app

İlk olarak, kopya bir C# SQL API'si uygulaması github'dan.First, clone a C# SQL API app from GitHub.

  1. Açık Git Bash gibi bir git terminal penceresi oluşturma adlı yeni bir dizin git-samplesve şekilde değiştirin:Open a git terminal window, such as Git Bash, create a new directory named git-samples, and change to it:

    mkdir /c/git-samples/
    cd /c/git-samples/
    
  2. Örnek depoyu kopyalamak ve bilgisayarınızda örnek uygulamanın bir kopyasını oluşturmak için aşağıdaki komutu çalıştırın:Run the following command to clone the sample repository and create a copy of the sample app on your computer:

    git clone https://github.com/Azure-Samples/documentdb-dotnet-todo-app.git
    

Bağlantı dizesini güncelleştirmeUpdate the connection string

  1. Gidin ve açmak todo.sln kopyalanan uygulamanızı Visual Studio'da dosya.Navigate to and open the todo.sln file of your cloned app in Visual Studio.

  2. Visual Studio'da Çözüm Gezginiaçın web.config dosya.In Visual Studio Solution Explorer, open the web.config file.

  3. Bağlantı dizesi bilgilerinizi kopyalayıp yapıştırabilirsiniz kopyalamak için Azure portalına dönün Git web.config.Go back to the Azure portal to copy your connection string information to paste into the web.config.

    1. Azure Cosmos DB hesabı sol gezinti bölmesinde anahtarları.In your Azure Cosmos DB account left navigation, select Keys.

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

    2. Altında okuma-yazma anahtarları, kopyalama URI sağ taraftaki Kopyala düğmesini kullanarak değer ve yapıştırın endpoint anahtarını web.config. Örneğin:Under Read-write Keys, copy the URI value using the copy button at the right, and paste it into the endpoint key in the web.config. For example:

      <add key="endpoint" value="https://mysqlapicosmosdb.documents.azure.com:443/" />

    3. Kopyalama birincil anahtar yapıştırın ve değer authKey anahtarını web.config. Örneğin:Copy the PRIMARY KEY value and paste it into the authKey key in the web.config. For example:

      <add key="authKey" value="19ZDNJAiYL26tmnRvoez6hmtIfBGwjun50PWRjNYMC2ig8Ob9hYk7Fq1RYSv8FcIYnh1TdBISvCh7s6yyb0000==" />

  4. Veritabanı olduğundan emin olun ve koleksiyon (kapsayıcı olarak da bilinir) değerleri web.config daha önce oluşturduğunuz adlarla eşleşir.Make sure the database and collection (also called container) values in the web.config match the names you created earlier.

    <add key="database" value="ToDoList"/>
    <add key="collection" value="Items"/>
    
  5. Kaydet web.config. Uygulamanız artık Azure Cosmos DB ile iletişim kurmak için gereken tüm bilgileri ile de güncelleştirdik.Save the web.config. You've now updated your app with all the information it needs to communicate with Azure Cosmos DB.

Web uygulamasını çalıştırmaRun the web app

  1. Visual Studio'da sağ todo projesi Çözüm Gezginive ardından NuGet paketlerini Yönet.In Visual Studio, right-click the todo project in Solution Explorer, and then select Manage NuGet Packages.

  2. NuGet Gözat kutusuna DocumentDB yazın.In the NuGet Browse box, type DocumentDB.

  3. Sonuçlardan yükleme 2.2.3 Sürüm , Microsoft.Azure.DocumentDB zaten yüklü değilse kitaplığı.From the results, install the 2.2.3 version of Microsoft.Azure.DocumentDB library if not already installed. Bu yükler Microsoft.Azure.DocumentDB paketi ve tüm bağımlılıklar.This installs the Microsoft.Azure.DocumentDB package and all dependencies.

    NuGet Paket Yöneticisi bazı paketler çözümden eksik olduğu bir ileti görüntülenirse, seçin geri iç kaynaklardan yüklenecek.If the NuGet Package Manager displays a message that some packages are missing from the solution, select Restore to install them from internal sources.

  4. Seçin Ctrl+F5 uygulamayı tarayıcınızda çalıştırın.Select Ctrl+F5 to run the app in your browser.

  5. Seçin Yeni Oluştur Yapılacaklar uygulamasında ve birkaç yeni görev oluşturun.Select Create New in the to-do app, and create a few new tasks.

    Yapılacaklar listesi uygulaması ve örnek veriler

Veri Gezgini, Azure portalında görmek için sorgulamak, değiştirmek ve yeni verilerinizle çalışmanıza geri dönebilirsiniz.You can go back to Data Explorer in the Azure portal to see, query, modify, and work with your new data.

.NET kodu gözden geçirinReview the .NET code

Bu adım isteğe bağlıdır.This step is optional. Bu hızlı başlangıçta, Azure portalında bir veritabanı ve kapsayıcı oluşturulur ve .NET örneği kullanarak örnek veriler eklenir.In this quickstart, you created a database and a container in the Azure portal and added sample data by using the .NET sample. Ancak, ayrıca veritabanı ve kapsayıcı .NET örneği kullanarak oluşturabilirsiniz.However, you can also create the database and the container by using the .NET sample. Veritabanı kaynaklarının kodda nasıl oluşturulduğunu ilgileniyorsanız aşağıdaki kod parçacıklarının gözden geçirin.Review the following snippets if you're interested in how database resources are created in the code. Kod parçacıklarının tümü alınmıştır DocumentDBRepository.cs dosyası todo proje.The snippets are all taken from the DocumentDBRepository.cs file in the todo project.

  • Bu kod başlatır DocumentClient:This code initializes the DocumentClient:

    client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
    
  • Bu kodu kullanarak yeni bir veritabanı oluşturur. CreateDatabaseAsync yöntemi:This code creates the new database by using the CreateDatabaseAsync method:

    await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
    
  • Aşağıdaki kodu kullanarak yeni bir koleksiyon oluşturur. CreateDocumentCollectionAsync yöntemi:The following code creates the new collection by using the CreateDocumentCollectionAsync method:

    private static async Task CreateCollectionIfNotExistsAsync(string partitionkey)
    {
       try
       {       
        await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId), new RequestOptions { PartitionKey = new PartitionKey(partitionkey) });
       }
        catch (DocumentClientException e)
        {
           if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                await client.CreateDocumentCollectionAsync(
                  UriFactory.CreateDatabaseUri(DatabaseId),
                   new DocumentCollection
                    {
                      Id = CollectionId,
                      PartitionKey = new PartitionKeyDefinition
                       {
                           Paths = new System.Collections.ObjectModel.Collection<string>(new List<string>() { partitionkey })
                        }
                    },
                      new RequestOptions { OfferThroughput = 400 });
            }
            else
            {
                throw;
            }
        }
    }
    

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, bir Azure Cosmos DB hesabı oluşturma, bir veritabanı ve Veri Gezgini'ni kullanarak kapsayıcı oluşturabilir ve verilerinizi güncelleştirmek için bir .NET web uygulamasını çalıştırmayı öğrendiniz.In this quickstart, you learned how to create an Azure Cosmos DB account, create a database and container using the Data Explorer, and run a .NET web app to update your data. Şimdi Azure Cosmos DB hesabınıza ek veriler aktarabilirsiniz.You can now import additional data to your Azure Cosmos DB account.