Hızlı Başlangıç: Azure .NET Framework DB Gremlin API hesabını kullanarak Cosmos veya Core uygulaması derleme

  • Makale
  • Okumak için 9 dakika

Uygulama hedefı: Gremlin API

Azure Cosmos DB, Microsoft'un genel olarak dağıtılmış çok modelli veritabanı hizmetidir. 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.

Bu hızlı başlangıçta, azure Cosmos DB Gremlin API hesabı, veritabanı ve grafiği (kapsayıcı) oluşturmak için Azure portal. Daha sonra açık kaynaklı Gremlin.Net sürücüsünü kullanarak bir konsol uygulaması oluşturabilir ve çalıştırabilirsiniz.

Önkoşullar

2019'Visual Studio henüz yüklü değilse, ücretsiz Visual Studio 2019 Community Sürümünü indirip kullanabilirsiniz. Visual Studio kurulumu sırasında Azure dağıtımını etkinleştirdiğinizden emin olun.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Veritabanı hesabı oluşturma

  1. Yeni bir tarayıcı penceresinde Azure portalında oturum açın.

  2. Sol menüde Kaynak oluştur'a tıklayın.

    Azure portalında kaynak oluşturma

  3. Yeni sayfasında Veritabanları Azure veritabanı > veritabanı'Cosmos seçin.

    Azure portalındaki Veritabanları bölmesi

  4. Azure veritabanı Cosmos veritabanı hesabı oluştur sayfasında, yeni Azure Cosmos DB hesabının ayarlarını girin.

    Ayar Değer Açıklama
    Abonelik Abonelik adı Bu Azure Cosmos hesabı için kullanmak istediğiniz Azure aboneliğini seçin.
    Kaynak Grubu Kaynak grubu adı Bir kaynak grubu seçin veya Yeni oluştur seçeneğini belirleyin ve yeni kaynak grubu için benzersiz bir ad girin.
    Hesap Adı Benzersiz bir ad girin Azure Cosmos DB hesabınızı tanımlayan benzersiz bir ad girin. Hesap URI'niz gremlin.azure.com benzersiz hesap adınıza eklenir.

    Hesap adı yalnızca küçük harf, rakam ve kısa çizgi (-) kullanabilir ve 3 ile 44 karakter uzunluğunda olmalıdır.
    API Gremlin (graf) API, oluşturulacak hesap türünü belirler. Azure Cosmos DB beş API sağlar: Belge veritabanları için çekirdek (SQL), graf veritabanları için Gremlin, belge veritabanları için MongoDB, Azure Tablosu ve Cassandra. Her API için ayrı bir hesap oluşturmanız gerekir.

    Gremlin (graf) öğesini seçin çünkü bu hızlı başlangıçta Gremlin API'si ile çalışan bir tablo oluşturuyoruz.

    Gremlin API hakkında daha fazla bilgi edinin.
    Konum Kullanıcılarınıza en yakın bölge Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.
    Kapasite modu Sağlanan aktarım hızı veya Sunucusuz Sağlanan aktarım hızı modunda hesap oluşturmak için Sağlanan aktarım hızı'ı seçin. Sunucusuz modda bir hesap oluşturmak için Sunucusuz'ı seçin.
    Azure Cosmos DB ücretsiz katmanı indirimini uygulama Uygula veya Uygula Azure Cosmos DB ücretsiz katmanı ile bir hesapta ilk 1000 RU/sn ve 25 GB depolama alanı ücretsiz olarak elde edilir. Ücretsiz katman hakkında daha fazla bilgi.

    Not

    Azure aboneliği başına en fazla bir ücretsiz azure Cosmos DB hesabına sahip olabilir ve hesabı oluştururken kabul etmek zorundasınız. Ücretsiz katman indirimi uygulama seçeneğini görmüyorsanız bu, abonelikte başka bir hesabın ücretsiz katmanla zaten etkinleştirilmiştir anlamına gelir.

    Azure Cosmos DB için yeni hesap sayfası

  5. Genel Dağıtım sekmesinde aşağıdaki ayrıntıları yapılandırabilirsiniz. Bu hızlı başlangıç için varsayılan değerleri bırakın:

    Ayar Değer Açıklama
    Coğrafi Yedeklilik Devre Dışı Bırak Bölgenizi bir çift bölgeyle eşleştirerek hesabınız üzerinde genel dağıtımı etkinleştirin veya devre dışı bırakma. Hesabınıza daha sonra daha fazla bölge ekebilirsiniz.
    Birden Çok Bölgeli Yazmalar Devre Dışı Bırak Çok bölgeli yazma özelliği, dünya genelindeki veritabanlarınız ve kapsayıcılar için sağlanan aktarım hızından yararlanmanızı sağlar.

    Not

    Kapasite modu olarak Sunucusuz seçeneğini belirtirsanız aşağıdaki seçenekler kullanılamaz:

    • Ücretsiz Katman İndirimi Uygula
    • Coğrafi yedeklilik
    • Birden Çok Bölgeli Yazmalar

  6. İsteğe bağlı olarak, aşağıdaki sekmelerde ek ayrıntıları yapılandırabilirsiniz:

    • Ağ - Sanal ağdan erişimi yapılandırma.
    • Yedekleme İlkesi - Düzenli veya sürekli yedekleme ilkesi yapılandırma.
    • Şifreleme - Hizmet tarafından yönetilen anahtar veya müşteri tarafından yönetilen bir anahtar kullanın.
    • Etiketler- Etiketler, birden çok kaynağa ve kaynak gruplarına aynı etiketi uygulayarak kaynakları kategorilere ayırmanız ve birleştirilmiş faturalamayı görüntülemenizi sağlayan ad/değer çiftleridir.

  7. Gözden geçir ve oluştur’u seçin.

  8. Hesabın oluşturulması birkaç dakika sürer. Portalda Tebrikler! Azure Cosmos DB hesabınız oluşturuldu sayfası.

    Azure Cosmos DB hesabı oluşturuldu sayfası

Graf ekleme

Şimdi bir grafik veritabanı oluşturmak için Azure portalında Veri Gezgini aracını kullanabilirsiniz.

  1. yeni Veri Gezgini > Graph seçin.

    Grafik Ekle alanı en sağda görüntülenir, görmek için sağa kaydırmanız gerekebilir.

    Azure portalındaki Veri Gezgini, Grafik Ekle sayfası

  2. Grafik Ekle sayfasında, yeni grafik için ayarları girin.

    Ayar Önerilen değer Açıklama
    Veritabanı Kimliği sample-database Yeni veritabanınızın adı olarak sample-database girin. Veritabanı adı 1 ile 255 karakter arasında olmalı, / \ # ? içermemeli ve boşlukla bitmemelidir.
    Aktarım hızı 400 RU Aktarım hızını saniyede 400 istek birimi (RU/s) olarak değiştirin. Daha sonra gecikme süresini azaltmak isterseniz işlem hızının ölçeğini artırabilirsiniz.
    Graf Kimliği sample-graph Yeni koleksiyonunuzun adı olarak sample-graph girin. Graf adı karakter gereksinimleri, veritabanı kimliklerine ilişkin karakter gereksinimleri ile aynıdır.
    Bölüm Anahtarı /PK tüm Cosmos DB hesapları yatay olarak ölçeklendirmek için bir bölüm anahtarına ihtiyaç duyar. Graph veri bölümlendirme makalesindeuygun bölüm anahtarını seçme hakkında bilgi edinin.

  3. Form doldurulduktan sonra Tamam' ı seçin.

Örnek uygulamayı kopyalama

Şimdi GitHub'dan bir Gremlin API'si uygulaması kopyalayalım, bağlantı dizesini ayarlayalım ve uygulamayı çalıştıralım. Verilerle program aracılığıyla çalışmanın ne kadar kolay olduğunu göreceksiniz.

  1. Bir komut istemini açın, git-samples adlı yeni bir klasör oluşturun ve komut istemini kapatın.

    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.

    cd "C:\git-samples"

  3. Örnek depoyu kopyalamak için aşağıdaki komutu çalıştırın. Bu komut bilgisayarınızda örnek uygulamanın bir kopyasını oluşturur.

    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.

  5. Projedeki NuGet paketlerini geri yükleyin. Bu Gremlin.Net sürücüsünü ve Newtonsoft.Json paketini içermelidir.

  6. Nuget paket yöneticisini veya nuget komut satırı yardımcı programını kullanarak sürücüyü Gremlin.Net@v3.4.6 el ile de yükleyebilirsiniz:

    nuget install Gremlin.NET -Version 3.4.6

Not

Gremlin API şu anda yalnızca v3.4.6'yakadar Gremlin.Net için destek sağlar. En son sürümü yüklürsanız, hizmeti kullanırken hata alırsınız.

Kodu gözden geçirin

Bu adım isteğe bağlıdır. 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. Aksi durumda, Bağlantı dizenizi güncelleştirme bölümüne atlayabilirsiniz.

Aşağıdaki kod parçacıklarının tamamı, Program.cs dosyasından alınır.

  • Bağlantı parametrelerinizi yukarıda oluşturulan hesaba göre ayarlayın:

    private static string Host => Environment.GetEnvironmentVariable("Host") ?? throw new ArgumentException("Missing env var: Host");
private static string PrimaryKey => Environment.GetEnvironmentVariable("PrimaryKey") ?? throw new ArgumentException("Missing env var: PrimaryKey");
private static string Database => Environment.GetEnvironmentVariable("DatabaseName") ?? throw new ArgumentException("Missing env var: DatabaseName");
private static string Container => Environment.GetEnvironmentVariable("ContainerName") ?? throw new ArgumentException("Missing env var: ContainerName");

private static bool EnableSSL
{
    get
    {
        if (Environment.GetEnvironmentVariable("EnableSSL") == null)
        {
            return true;
        }

        if (!bool.TryParse(Environment.GetEnvironmentVariable("EnableSSL"), out bool value))
        {
            throw new ArgumentException("Invalid env var: EnableSSL is not a boolean");
        }

        return value;
    }
}

private static int Port
{
    get
    {
        if (Environment.GetEnvironmentVariable("Port") == null)
        {
            return 443;
        }

        if (!int.TryParse(Environment.GetEnvironmentVariable("Port"), out int port))
        {
            throw new ArgumentException("Invalid env var: Port is not an integer");
        }

        return port;
    } 
}

  • Yürütülecek Gremlin komutları bir Sözlükte listelenir:

    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 GremlinServer parametreleri kullanarak yeni ve bağlantı nesneleri GremlinClient oluşturun:

    string containerLink = "/dbs/" + Database + "/colls/" + Container;
Console.WriteLine($"Connecting to: host: {Host}, port: {Port}, container: {containerLink}, ssl: {EnableSSL}");
var gremlinServer = new GremlinServer(Host, Port, enableSsl: EnableSSL, 
                                        username: containerLink, 
                                        password: PrimaryKey);

ConnectionPoolSettings connectionPoolSettings = new ConnectionPoolSettings()
{
    MaxInProcessPerConnection = 10,
    PoolSize = 30, 
    ReconnectionAttempts= 3,
    ReconnectionBaseDelay = TimeSpan.FromMilliseconds(500)
};

var webSocketConfiguration =
    new Action<ClientWebSocketOptions>(options =>
    {
        options.KeepAliveInterval = TimeSpan.FromSeconds(10);
    });


using (var gremlinClient = new GremlinClient(
    gremlinServer, 
    new GraphSON2Reader(), 
    new GraphSON2Writer(), 
    GremlinClient.GraphSON2MimeType, 
    connectionPoolSettings, 
    webSocketConfiguration))
{

  • Nesnesini zaman uyumsuz bir görevle kullanarak her Gremlin GremlinClient sorgusunu yürütün. Önceki adımda tanımlanan sözlükten Gremlin sorgularını okuyabilir ve yürütülür. Daha sonra sonucu elde eder ve Newtonsoft.Json paketinden sınıfını kullanarak sözlük olarak JsonSerializer biçimlendirilmiş değerleri okur:

    foreach (var query in gremlinQueries)
{
    Console.WriteLine(String.Format("Running this query: {0}: {1}", query.Key, query.Value));

    // Create async task to execute the Gremlin query.
    var resultSet = SubmitRequest(gremlinClient, query).Result;
    if (resultSet.Count > 0)
    {
        Console.WriteLine("\tResult:");
        foreach (var result in resultSet)
        {
            // The vertex results are formed as Dictionaries with a nested dictionary for their properties
            string output = JsonConvert.SerializeObject(result);
            Console.WriteLine($"\t{output}");
        }
        Console.WriteLine();
    }

    // Print the status attributes for the result set.
    // This includes the following:
    //  x-ms-status-code            : This is the sub-status code which is specific to Cosmos DB.
    //  x-ms-total-request-charge   : The total request units charged for processing a request.
    //  x-ms-total-server-time-ms   : The total time executing processing the request on the server.
    PrintStatusAttributes(resultSet.StatusAttributes);
    Console.WriteLine();
}

Bağlantı dizenizi güncelleştirme

Bu adımda Azure portalına dönerek bağlantı dizesi bilgilerinizi kopyalayıp uygulamaya ekleyin.

  1. Azure portalda graf veritabanı hesabınıza gidin. Genel Bakış sekmesinde iki uç nokta görebilirsiniz:

    .NET SDK URI'si - Bu değer, Microsoft.Azure.Graphs kitaplığını kullanarak graf hesabına bağlanıyorsanız kullanılır.

    Gremlin Uç Noktası - Bu değer, Gremlin.Net kitaplığını kullanarak graf hesabına bağlandığınızda kullanılır.

    Uç noktayı kopyalama

    Bu örneği çalıştırmak için Gremlin Uç Noktası değerini kopyalayın, sonundaki bağlantı noktası numarasını silin, yani URI https://<your cosmos db account name>.gremlin.cosmosdb.azure.com olur. Uç nokta değeri şuna benzer olmalıdır: testgraphacct.gremlin.cosmosdb.azure.com

  2. Ardından Anahtarlar sekmesine gidin ve birincil anahtar değerini Azure portal.

  3. Hesabınıza URI ve PRIMARY KEY kopyaladikten sonra, bunları uygulamayı çalıştıran yerel makinede yeni bir ortam değişkenine kaydedin. Ortam değişkenlerini ayarlamak için bir komut istemi penceresi açın ve aşağıdaki komutu çalıştırın. Değerleri ve değerleri <Your_Azure_Cosmos_account_URI> <Your_Azure_Cosmos_account_PRIMARY_KEY> olun.

    setx Host "<your Azure Cosmos account name>.gremlin.cosmosdb.azure.com"
setx PrimaryKey "<Your_Azure_Cosmos_account_PRIMARY_KEY>"

  4. Program.cs dosyasını açın ve "veritabanı ve "kapsayıcı" değişkenlerini yukarıda oluşturulan veritabanı ve kapsayıcı (aynı zamanda graf adı) adlarla güncelleştirin.

    private static string database = "your-database-name"; private static string container = "your-container-or-graph-name";

  5. Program.cs dosyasını kaydedin.

Bu adımlarla uygulamanıza Azure Cosmos DB ile iletişim kurması için gereken tüm bilgileri eklemiş oldunuz.

Konsol uygulamasını çalıştırma

Uygulamayı çalıştırmak için CTRL+F5 tuşlarına basın. Uygulama hem Gremlin sorgu komutlarını hem de konsol sonuçlarını yazdırır.

Konsol penceresinde grafiğe eklenmekte olan kenarlar ve köşeler gösterilir. Betik tamamlandığında, ENTER tuşuna basarak konsol penceresini kapatın.

Veri Gezgini'ni kullanarak göz atma

Şimdi Azure portalındaki Veri Gezgini'ne dönerek yeni grafik verilerinize göz atıp sorgu gönderebilirsiniz.

  1. Yeni veritabanı, Veri Gezgini'nin Graflar bölmesinde görüntülenir. Veritabanını ve kapsayıcı düğümlerini genişletip Graf’a tıklayın.

  2. Graftaki tüm köşeleri görüntülemek üzere varsayılan sorguyu kullanmak için Filtre Uygula düğmesine tıklayın. Örnek uygulama tarafından oluşturulan veriler Grafikler bölmesinde görüntülenir.

    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.

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

Azure portalında SLA'ları gözden geçirme

Bu Azure portal, Cosmos DB aktarım hızı, depolama alanı, kullanılabilirlik, gecikme süresi ve tutarlılığı izler. Bir Azure Cosmos DB Hizmet Düzeyi Sözleşmesi (SLA) ile ilişkili ölçümler, gerçek performansla karşılaştırıldığında SLA değerini gösterir. Bu ölçüm paketi, SLA'larınızı izlemenizi saydam hale gelir.

Ölçümleri ve SLA'ları gözden geçirmek için:

  1. Hesap gezinti Cosmos DB Ölçümler'i seçin.

  2. Gecikme süresi gibi bir sekme seçin ve sağdan bir zaman çerçevesi seçin. Grafiklerde Gerçek ve SLA çizgilerini karşılaştırın.

    Azure Cosmos DB ölçüm paketi

  3. Diğer sekmelerde ölçümleri gözden geçirme.

Kaynakları temizleme

Uygulama ve hesap hesabınızla Azure Cosmos DB, daha fazla ücret ödemeden oluşturduğunuz Azure kaynaklarını silebilirsiniz. Kaynakları silmek için:

  1. Arama Azure portal kaynak grupları için arama ve seçimlerini kullanın.

  2. Listeden bu hızlı başlangıç için oluşturduğunuz kaynak grubunu seçin.

    Silinecek kaynak grubunu seçin

  3. Kaynak grubunun Genel Bakış sayfasında Kaynak grubunu sil'i seçin.

    Kaynak grubunu silme

  4. Sonraki pencerede, silinecek kaynak grubunun adını girin ve Sil'i seçin.

Sonraki adımlar

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. Artık daha karmaşık sorgular derleyebilir ve Gremlin kullanarak güçlü grafik geçişi mantığını kullanabilirsiniz.

Gremlin kullanarak sorgulama