Hızlı Başlangıç: Azure Cosmos DB Gremlin API hesabını kullanarak .NET Framework veya çekirdek uygulama oluşturmaQuickstart: Build a .NET Framework or Core application using the Azure Cosmos DB Gremlin 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ıçta Azure portal kullanılarak Azure Cosmos DB Gremlin API hesabı, veritabanı ve Graf (kapsayıcı) oluşturma gösterilmektedir.This quickstart demonstrates how to create an Azure Cosmos DB Gremlin API account, database, and graph (container) using the Azure portal. Daha sonra açık kaynaklı Gremlin.Net sürücüsünü kullanarak bir konsol uygulaması oluşturabilir ve çalıştırabilirsiniz.You then build and run a console app built using the open-source driver Gremlin.Net.

ÖnkoşullarPrerequisites

Zaten Visual Studio 2019 yüklü değilse, ücretsiz Visual Studio 2019 Community Edition' ı indirip kullanabilirsiniz.If you don't already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Visual Studio kurulumu sırasında Azure dağıtımını etkinleştirdiğinizden emin olun.Make sure that you enable Azure development during the Visual Studio setup.

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.

Veritabanı hesabı oluşturmaCreate a database account

  1. Yeni bir tarayıcı penceresinde Azure portalında oturum açın.In a new browser window, sign in to the Azure portal.

  2. Kaynak oluştur > Veritabanları > Azure Cosmos DB seçeneğine tıklayın.Click Create a resource > Databases > Azure Cosmos DB.

    Azure portaldaki “Veritabanları” bölmesi

  3. İçinde Azure Cosmos DB hesabı oluştur sayfasında, yeni Azure Cosmos DB hesabının ayarlarını girin.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    AyarSetting DeğerValue AçıklamaDescription
    AbonelikSubscription AboneliğinizYour subscription Bu Azure Cosmos DB hesabı için kullanmak istediğiniz Azure aboneliğini seçin.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Kaynak GrubuResource Group Yeni oluşturCreate new

    Ardından Kimlikte sağlanan benzersiz adın aynısını girinThen enter the same unique name as provided in ID
    Yeni oluştur’u seçin.Select Create new. Ardından hesabınız için yeni bir kaynak grubu adı girin.Then enter a new resource-group name for your account. Kolaylık olması için kimliğinizle aynı adı kullanın.For simplicity, use the same name as your ID.
    Hesap AdıAccount Name Benzersiz bir ad girinEnter a unique name Azure Cosmos DB hesabınızı tanımlayan benzersiz bir ad girin.Enter a unique name to identify your Azure Cosmos DB 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 kullanabilirsiniz.The ID can use only lowercase letters, numbers, and the hyphen (-) character. 3 ila 31 karakter uzunluğunda olmalıdır.It must be between 3 and 31 characters in length.
    APIAPI Gremlin (grafik)Gremlin (graph) API, oluşturulacak hesap türünü belirler.The API determines the type of account to create. Azure Cosmos DB, beş API sunar: Gremlin graf veritabanları, belge veritabanları, Azure tablosu ve Cassandra, MongoDB Core(SQL) belge veritabanları için.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, 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 Gremlin (graf) çünkü bu hızlı başlangıçta, Gremlin API'si ile birlikte çalışan bir tablo oluşturuluyor.Select Gremlin (graph) because in this quickstart you are creating a table that works with the Gremlin API.

    Graph API hakkında daha fazla bilgi.Learn more about the Graph 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. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.Use the location that's closest to your users to give them the fastest access to the data.

    Seçin gözden geçir + Oluştur.Select Review+Create. Atlayabilirsiniz ve etiketleri bölümü.You can skip the Network and Tags section.

    Azure Cosmos DB için yeni hesap dikey penceresi

  4. Hesabın oluşturulması birkaç dakika sürer.The account creation takes a few minutes. Portalın Tebrikler! Azure Cosmos DB hesabınız oluşturuldu sayfasını görüntülemesini bekleyin.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account was created page.

    Azure portalındaki Bildirimler bölmesi

Graf eklemeAdd a graph

Şimdi bir grafik veritabanı 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 graph database.

  1. Yeni Veri Gezgini > grafik' i seçin.Select Data Explorer > New Graph.

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

    Azure portalındaki Veri Gezgini, Grafik Ekle sayfası

  2. Grafik Ekle sayfasında, yeni grafik için ayarları girin.In the Add graph page, enter the settings for the new graph.

    AyarSetting Önerilen değerSuggested value AçıklamaDescription
    Veritabanı KimliğiDatabase ID sample-databasesample-database Yeni veritabanınızın adını sample-database olarak belirleyin.Enter sample-database as the name for the new database. Veritabanı adı 1 ile 255 karakter arasında olmalı, / \ # ? içermemeli ve boşlukla bitmemelidir.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    Aktarım hızıThroughput 400 RU400 RUs Aktarım hızını saniyede 400 istek birimi (RU/s) olarak değiştirin.Change the throughput to 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.
    Graf KimliğiGraph ID sample-graphsample-graph Yeni koleksiyonunuzun adını sample-graph olarak belirleyin.Enter sample-graph as the name for your new collection. Grafik adı karakter gereksinimleri, veritabanı kimliklerine ilişkin karakter gereksinimleri ile aynıdır.Graph names have the same character requirements as database IDs.
    Bölüm AnahtarıPartition Key /PK/pk Tüm Cosmos DB hesapları yatay olarak ölçeklendirmek için bir bölüm anahtarına ihtiyaç duyar.All Cosmos DB accounts need a partition key to horizontally scale. Grafik veri bölümlendirme makalesindeuygun bölüm anahtarını seçme hakkında bilgi edinin.Learn how to select an appropriate partition key in the Graph Data Partitioning article.
  3. Form doldurulduktan sonra Tamam' ı seçin.Once the form is filled out, select OK.

Örnek uygulamayı kopyalamaClone the sample application

Şimdi GitHub'dan bir Gremlin API'si uygulaması kopyalayalım, bağlantı dizesini ayarlayalım ve uygulamayı çalıştıralım.Now let's clone a Gremlin API app from GitHub, set the connection string, and run it. Verilerle program aracılığıyla çalışmanın ne kadar kolay olduğunu göreceksiniz.You'll see how easy it is to work with data programmatically.

  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-graph-gremlindotnet-getting-started.git
    
  4. Ardından Visual Studio’yu ve çözüm dosyasını açın.Then open Visual Studio and open the solution file.

  5. Projedeki NuGet paketlerini geri yükleyin.Restore the NuGet packages in the project. Bu Gremlin.Net sürücüsünü ve Newtonsoft.Json paketini içermelidir.This should include the Gremlin.Net driver, as well as the Newtonsoft.Json package.

  6. Ayrıca NuGet paket yöneticisi veya NuGet komut satırı yardımcı programını kullanarak Gremlin.Net sürücüsünü kendiniz de yükleyebilirsiniz:You can also install the Gremlin.Net driver manually using the Nuget package manager, or the nuget command-line utility:

    nuget install Gremlin.Net
    

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.

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

  • Yukarıda oluşturulan hesaba göre bağlantı parametrelerinizi ayarlayın (Satır 19):Set your connection parameters based on the account created above (Line 19):

    private static string hostname = "your-endpoint.gremlin.cosmosdb.azure.com";
    private static int port = 443;
    private static string authKey = "your-authentication-key";
    private static string database = "your-database";
    private static string collection = "your-graph-container";
    
  • Yürütülecek Gremlin komutları bir Sözlük içinde listelenir (Satır 26):The Gremlin commands to be executed are listed in a Dictionary (Line 26):

    private static Dictionary<string, string> gremlinQueries = new Dictionary<string, string>
    {
        { "Cleanup",        "g.V().drop()" },
        { "AddVertex 1",    "g.addV('person').property('id', 'thomas').property('firstName', 'Thomas').property('age', 44).property('pk', 'pk')" },
        { "AddVertex 2",    "g.addV('person').property('id', 'mary').property('firstName', 'Mary').property('lastName', 'Andersen').property('age', 39).property('pk', 'pk')" },
        { "AddVertex 3",    "g.addV('person').property('id', 'ben').property('firstName', 'Ben').property('lastName', 'Miller').property('pk', 'pk')" },
        { "AddVertex 4",    "g.addV('person').property('id', 'robin').property('firstName', 'Robin').property('lastName', 'Wakefield').property('pk', 'pk')" },
        { "AddEdge 1",      "g.V('thomas').addE('knows').to(g.V('mary'))" },
        { "AddEdge 2",      "g.V('thomas').addE('knows').to(g.V('ben'))" },
        { "AddEdge 3",      "g.V('ben').addE('knows').to(g.V('robin'))" },
        { "UpdateVertex",   "g.V('thomas').property('age', 44)" },
        { "CountVertices",  "g.V().count()" },
        { "Filter Range",   "g.V().hasLabel('person').has('age', gt(40))" },
        { "Project",        "g.V().hasLabel('person').values('firstName')" },
        { "Sort",           "g.V().hasLabel('person').order().by('firstName', decr)" },
        { "Traverse",       "g.V('thomas').out('knows').hasLabel('person')" },
        { "Traverse 2x",    "g.V('thomas').out('knows').hasLabel('person').out('knows').hasLabel('person')" },
        { "Loop",           "g.V('thomas').repeat(out()).until(has('id', 'robin')).path()" },
        { "DropEdge",       "g.V('thomas').outE('knows').where(inV().has('id', 'mary')).drop()" },
        { "CountEdges",     "g.E().count()" },
        { "DropVertex",     "g.V('thomas').drop()" },
    };
    
  • Yukarıda sağlanan parametreleri kullanarak bir GremlinServer bağlantı nesnesi oluşturun (Satır 52):Create a GremlinServer connection object using the parameters provided above (Line 52):

    var gremlinServer = new GremlinServer(hostname, port, enableSsl: true, 
                                                    username: "/dbs/" + database + "/colls/" + collection, 
                                                    password: authKey);
    
  • Yeni bir GremlinClient nesnesi oluşturun (Satır 56):Create a new GremlinClient object (Line 56):

    var gremlinClient = new GremlinClient(gremlinServer, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType);
    
  • Zaman uyumsuz bir görev içinde GremlinClient nesnesini kullanarak her bir Gremlin sorgusunu yürütün (Satır 63).Execute each Gremlin query using the GremlinClient object with an async task (Line 63). Bu yukarıda tanımlanan sözlükten Gremlin sorgularını okur (Satır 26):This will read the Gremlin queries from the dictionary defined above (Line 26):

    var results = await gremlinClient.SubmitAsync<dynamic>(query.Value);
    
  • Newtonsoft.Json öğesinden JsonSerializer sınıfını kullanarak sonucu alın ve sözlük olarak biçimlendirilen değerleri okuyun:Retrieve the result and read the values, which are formatted as a dictionary, using the JsonSerializer class from Newtonsoft.Json:

    foreach (var result in results)
    {
        // The vertex results are formed as dictionaries with a nested dictionary for their properties
        string output = JsonConvert.SerializeObject(result);
        Console.WriteLine(String.Format("\tResult:\n\t{0}", output));
    }
    

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 portalda graf veritabanı hesabınıza gidin.From the Azure portal, navigate to your graph database account. Genel Bakış sekmesinde iki uç nokta görebilirsiniz:In the Overview tab, you can see two endpoints-

    .NET SDK URI -bu değer, Graph hesabına Microsoft. Azure. Graf kitaplığı kullanarak bağlandığınızda kullanılır..NET SDK URI - This value is used when you connect to the graph account by using Microsoft.Azure.Graphs library.

    Gremlin Uç Noktası - Bu değer, Gremlin.Net kitaplığını kullanarak graf hesabına bağlandığınızda kullanılır.Gremlin Endpoint - This value is used when you connect to the graph account by using Gremlin.Net library.

    Uç noktayı kopyalama

    Bu örneği çalıştırmak için, Gremlin Uç Noktası değerini kopyalayın, sondaki bağlantı noktası numarasını silin. Böylelikle URI şuna dönüşür: https://<your cosmos db account name>.gremlin.cosmosdb.azure.comTo run this sample, copy the Gremlin Endpoint value, delete the port number at the end, that is the URI becomes https://<your cosmos db account name>.gremlin.cosmosdb.azure.com

  2. Program.cs içinde değeri satır 19’daki hostname değişkeninde your-endpoint üzerine yapıştırın.In Program.cs paste the value over your-endpoint in the hostname variable in line 19.

    "private static string hostname = "<your cosmos db account name>.gremlin.cosmosdb.azure.com";

    Uç nokta değeri şimdi şöyle görünmelidir:The endpoint value should now look like this:

    "private static string hostname = "testgraphacct.gremlin.cosmosdb.azure.com";

  3. Ardından, Anahtarlar sekmesine gidin, portaldan BİRİNCİL ANAHTAR değerinizi kopyalayın ve satır 21’de "your-authentication-key" yer tutucusunu değiştirerek authkey değişkeni içinde yapıştırın.Next, navigate to the Keys tab and copy PRIMARY KEY value from the portal, and paste it in the authkey variable, replacing the "your-authentication-key" placeholder in line 21.

    private static string authKey = "your-authentication-key";

  4. Yukarıda oluşturulan veritabanının bilgilerini kullanarak, veritabanı adını satır 22’de database değişkeni içinde yapıştırın.Using the information of the database created above, paste the database name inside of the database variable in line 22.

    private static string database = "your-database";

  5. Benzer şekilde, yukarıda oluşturulan kapsayıcının bilgilerini kullanarak, koleksiyonu (aynı zamanda grafik adı) satır 23’teki collection değişkeninin içinde yapıştırın.Similarly, using the information of the container created above, paste the collection (which is also the graph name) inside of the collection variable in line 23.

    private static string collection = "your-collection-or-graph";

  6. Program.cs dosyasını kaydedin.Save the Program.cs file.

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.

Konsol uygulamasını çalıştırmaRun the console app

Uygulamayı çalıştırmak için CTRL+F5 tuşlarına basın.Click CTRL + F5 to run the application. Uygulama hem Gremlin sorgu komutlarını hem de konsol sonuçlarını yazdırır.The application will print both the Gremlin query commands and results in the console.

Konsol penceresinde grafiğe eklenmekte olan kenarlar ve köşeler gösterilir.The console window displays the vertexes and edges being added to the graph. Betik tamamlandığında, ENTER tuşuna basarak konsol penceresini kapatın.When the script completes, press ENTER to close the console window.

Veri Gezgini'ni kullanarak göz atmaBrowse using the Data Explorer

Şimdi Azure portalındaki Veri Gezgini'ne dönerek yeni grafik verilerinize göz atıp sorgu gönderebilirsiniz.You can now go back to Data Explorer in the Azure portal and browse and query your new graph data.

  1. Yeni veritabanı, Veri Gezgini'nin Graflar bölmesinde görüntülenir.In Data Explorer, the new database appears in the Graphs pane. Veritabanını ve kapsayıcı düğümlerini genişletip Graf’a tıklayın.Expand the database and container nodes, and then click Graph.

  2. Graftaki tüm köşeleri görüntülemek üzere varsayılan sorguyu kullanmak için Filtre Uygula düğmesine tıklayın.Click the Apply Filter button to use the default query to view all the vertices in the graph. Örnek uygulama tarafından oluşturulan veriler Grafikler bölmesinde görüntülenir.The data generated by the sample app is displayed in the Graphs pane.

    Grafiği yakınlaştırıp uzaklaştırabilir, grafik görüntüleme alanını genişletebilir, başka köşeler ekleyebilir ve görüntüleme alanında köşeleri taşıyabilirsiniz.You can zoom in and out of the graph, you can expand the graph display space, add additional vertices, and move vertices on the display surface.

    Azure portalındaki Veri Gezgini'nde grafiği görüntüleme

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

Web uygulamanız ve Azure Cosmos DB hesabınızla işiniz bittiğinde, daha fazla ücret ödemeniz için 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. Sol menü daraltılmışsa, genişletmek için Genişlet düğmesini seçin.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, kaynak grubunu sil' i seçin.In the new window, select Delete resource group.

    Azure portalında ölçümler

  4. Sonraki pencerede, silinecek kaynak grubunun adını girin ve Sil' i seçin.In the next window, enter the name of the resource group to delete, and then select Delete.

Sonraki adımlarNext steps

Bu hızlı başlangıçta Azure Cosmos DB hesabı oluşturmayı, Veri Gezgini'ni kullanarak grafik oluşturmayı ve bir uygulamayı çalıştırmayı öğrendiniz.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a graph using the Data Explorer, and run an app. Artık daha karmaşık sorgular oluşturabilir ve Gremlin kullanarak güçlü grafik geçişi mantığını kullanabilirsiniz.You can now build more complex queries and implement powerful graph traversal logic using Gremlin.