Azure Cosmos DB öykünücüsü kullanarak yerel olarak geliştirme

  • Makale

Öykünücü için yaygın bir kullanım örneği, uygulamalarınızı oluştururken geliştirme veritabanı olarak hizmet vermektir. Geliştirme için öykünücüyü kullanmak, azure cosmos DB gibi bir veritabanı için herhangi bir hizmet maliyeti ödemeden veri oluşturma ve modelleme özelliklerini öğrenmenize yardımcı olabilir. Ayrıca, öykünücüyü bir otomasyon iş akışının parçası olarak kullanmak, aynı tümleştirme testleri paketini çalıştırabilmenizi sağlayabilir. Aynı testlerin hem geliştirme makinenizde yerel olarak hem de sürekli tümleştirme işinde uzaktan çalıştığından emin olabilirsiniz.

Önkoşullar

  • .NET 6 veya üzeri, Node.js LTS veya Python 3.7 veya üzeri
    • Tüm gerekli yürütülebilir dosyalarınızda PATHkullanılabilir olduğundan emin olun.
  • Windows öykünücüsü
    • 64 bit Windows Server 2016, 2019, Windows 10 veya Windows 11.
    • En düşük donanım gereksinimleri:
      • 2 GB RAM
      • 10 GB kullanılabilir sabit disk alanı
  • Docker öykünücüsü

Öykünücüyü yükleme

Öykünücünün birden çok varyasyonu vardır ve her varyasyon nispeten sorunsuz bir yükleme işlemine sahiptir.

Başlamak için Microsoft Container Registry'den (MCR) kapsayıcı görüntüsünün Linux değişkenini alın.

  1. mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator Linux kapsayıcı görüntüsünü kapsayıcı kayıt defterinden yerel Docker konağına çekin.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Öykünücü görüntüsünün yerel Docker konağınıza çekildiğinden emin olun.

    docker images

Başlamak için Microsoft Container Registry'den (MCR) kapsayıcı görüntüsünün Linux değişkenini alın.

  1. Kapsayıcı kayıt defterinden mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulatormongodb yerel Docker konağına etiketini kullanarak Linux kapsayıcı görüntüsünü çekin.

    docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Öykünücü görüntüsünün yerel Docker konağınıza çekildiğinden emin olun.

    docker images

Öykünücünün Docker kapsayıcı değişkeni (Linux veya Windows), Apache Cassandra API'sini, Apache Gremlin api'sini veya Tablo için API'yi desteklemez.

Öykünücüyü başlatma

İndirildikten sonra, belirtilen API'niz etkinken öykünücüyü başlatın.

Öykünücünün Docker kapsayıcı değişkeni Apache Cassandra API'sini desteklemez.

Öykünücünün Docker kapsayıcı değişkeni Apache Gremlin API'sini desteklemez.

Öykünücünün Docker kapsayıcısı değişkeni Tablo API'sini desteklemez.

  1. Kapsayıcı görüntüsünü ve aşağıdaki yapılandırmayı kullanarak yeni bir kapsayıcı çalıştırın:

    Açıklama
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(İsteğe bağlı) Kullanılacak bölüm sayısını belirtin.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(İsteğe bağlı) Öykünücü çalıştırmaları arasında veri kalıcılığını etkinleştirin.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(İsteğe bağlı) Öykünücünün varsayılan IP adresini geçersiz kılın. 
    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Veri gezginine https://localhost:8081/_explorer/index.html erişmek için adresine gidin.

  1. Kapsayıcı görüntüsünü ve aşağıdaki yapılandırmayı kullanarak yeni bir kapsayıcı çalıştırın:

    Açıklama
    AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT Kullanılacak MongoDB uç noktasının sürümünü belirtin. Desteklenen uç noktalar şunlardır: 3.2, 3.6veya 4.0.
    AZURE_COSMOS_EMULATOR_PARTITION_COUNT(İsteğe bağlı) Kullanılacak bölüm sayısını belirtin.
    AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE(İsteğe bağlı) Öykünücü çalıştırmaları arasında veri kalıcılığını etkinleştirin.
    AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE(İsteğe bağlı) Öykünücünün varsayılan IP adresini geçersiz kılın. 
    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --interactive \
    --tty \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Veri gezginine https://localhost:8081/_explorer/index.html erişmek için adresine gidin.

Öykünücünün TLS/SSL sertifikasını içeri aktarma

Öykünücüyü istemcide TLS/SSL'yi devre dışı bırakmadan tercih ettiğiniz geliştirici SDK'sıyla kullanmak için öykünücünün TLS/SSL sertifikasını içeri aktarın.

Öykünücünün Docker kapsayıcı değişkeni (Linux veya Windows), Apache Cassandra API'sini, Apache Gremlin api'sini veya Tablo için API'yi desteklemez.

Öykünücü sertifikası, çalışan kapsayıcının yolunda _explorer/emulator.pem kullanılabilir. Sertifikayı çalışan kapsayıcıdan yerel makinenize indirmek için kullanın curl .

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

Öykünücü sertifikası, çalışan kapsayıcının yolunda _explorer/emulator.pem kullanılabilir.

  1. Sertifikayı çalışan kapsayıcıdan yerel makinenize indirmek için kullanın curl .

    curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

    Not

    Bu değerleri daha önce değiştirdiyseniz konak (veya IP adresi) ve bağlantı noktası numarasını değiştirmeniz gerekebilir.

  2. Sertifikayı genellikle işletim sisteminiz için kullanılan işleme göre yükleyin. Örneğin, Linux'ta sertifikayı /usr/local/share/ca-certificates/ yola kopyalarsınız.

    cp ~/emulatorcert.crt /usr/local/share/ca-certificates/

  3. CA sertifikalarını güncelleştirin ve Linux dağıtımınız için uygun komutu kullanarak sertifika paketini yeniden üretin.

    Debian tabanlı sistemler (örneğin, Ubuntu) için şunları kullanın:

    sudo update-ca-certificates

    Red Hat tabanlı sistemler (örneğin, CentOS, Fedora) için şunları kullanın:

    sudo update-ca-trust

    Daha ayrıntılı yönergeler için Linux dağıtımınıza özgü belgelere bakın.

SDK'dan öykünücüye Bağlan

Her SDK genellikle SDK'yı Azure Cosmos DB hesabınıza bağlamak için kullanılan bir istemci sınıfı içerir. Öykünücünün kimlik bilgilerini kullanarak SDK'yı öykünücü örneğine bağlayabilirsiniz.

Bir .NET uygulamasından öykünücüye bağlanmak için NoSQL .NET SDK için Azure Cosmos DB API'sini kullanın.

  1. Boş bir klasörden başlayın.

  2. Yeni bir .NET konsol uygulaması oluşturma

    dotnet new console

  3. NuGet'ten Microsoft.Azure.Cosmos paketi ekleyin.

    dotnet add package Microsoft.Azure.Cosmos

  4. Program.cs dosyasını açın.

  5. Dosyadaki mevcut tüm içeriği silin.

  6. Ad alanı için Microsoft.Azure.Cosmos bir using bloğu ekleyin.

    using Microsoft.Azure.Cosmos;

  7. Öykünücünün CosmosClient kimlik bilgilerini kullanarak yeni bir örneği oluşturun.

    using CosmosClient client = new(
    accountEndpoint: "https://localhost:8081/",
    authKeyOrResourceToken: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

  8. ve CreateContainerIfNotExistsAsynckullanarak CreateDatabaseIfNotExistsAsync yeni bir veritabanı ve kapsayıcı oluşturun.

    Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks",
    throughput: 400
);

Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/id"
);

  9. kullanarak UpsertItemAsynckapsayıcıda yeni bir öğe oluşturun.

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

await container.UpsertItemAsync(item);

  10. .NET uygulamasını çalıştırın.

    dotnet run

    Uyarı

    SSL hatası alırsanız, uygulamanız için TLS/SSL'yi devre dışı bırakmanız gerekebilir. Bu durum genellikle bir kapsayıcıda Azure Cosmos DB öykünücüsü kullanarak yerel makinenizde geliştirme yaptığınız ve kapsayıcının SSL sertifikasını içeri aktarmadığınız durumlarda ortaya çıkar. Bu sorunu çözmek için istemciyi oluşturmadan önce TLS/SSL doğrulamasını devre dışı bırakmak için istemcinin seçeneklerini yapılandırın:

    CosmosClientOptions options = new ()
{
    HttpClientFactory = () => new HttpClient(new HttpClientHandler()
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    }),
    ConnectionMode = ConnectionMode.Gateway,
};

using CosmosClient client = new(
  ...,
  ...,
  clientOptions: options
);

İpucu

.NET SDK'sını kullanarak gerçekleştirebileceğiniz diğer işlemler için .NET geliştirici kılavuzuna bakın.

Bir .NET uygulamasından öykünücüye bağlanmak için MongoDB .NET sürücüsünü kullanın.

  1. Boş bir klasörden başlayın.

  2. Yeni bir .NET konsol uygulaması oluşturma

    dotnet new console

  3. NuGet'ten MongoDB.Driver paketi ekleyin.

    dotnet add package MongoDB.Driver

  4. Program.cs dosyasını açın.

  5. Dosyadaki mevcut tüm içeriği silin.

  6. Ad alanı için MongoDB.Driver bir using bloğu ekleyin.

    using MongoDB.Driver;

  7. Öykünücünün MongoClient kimlik bilgilerini kullanarak yeni bir örneği oluşturun.

    var client = new MongoClient(
    "mongodb://localhost:C2y6yDjf5%2FR%2Bob0N8A7Cgv30VRDJIWEHLM%2B4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw%2FJw%3D%3D@localhost:10255/admin?ssl=true&retrywrites=false"
);

  8. ve GetCollection<>kullanarak GetDatabase veritabanını ve kapsayıcıyı alın.

    var database = client.GetDatabase("cosmicworks");

var collection = database.GetCollection<dynamic>("products");

  9. kullanarak InsertOneAsyncXXX içinde yeni bir öğe oluşturun.

    var item = new
{
    name = "Kiama classic surfboard"
};

await collection.InsertOneAsync(item);

  10. .NET uygulamasını çalıştırın.

    dotnet run

Bir .NET uygulamasından öykünücüye bağlanmak için Apache Cassandra .NET sürücüsünü kullanın.

  1. Boş bir klasörden başlayın.

  2. Yeni bir .NET konsol uygulaması oluşturma

    dotnet new console

  3. NuGet'ten CassandraCSharpDriver paketi ekleyin.

    dotnet add package CassandraCSharpDriver

  4. Program.cs dosyasını açın.

  5. Dosyadaki mevcut tüm içeriği silin.

  6. Ad alanı için Cassandra bir using bloğu ekleyin.

    using Cassandra;

  7. Öykünücünün Cluster kimlik bilgilerini kullanarak yeni bir örneği oluşturun. kullanarak Connectyeni bir oturum oluşturun.

    var options = new SSLOptions(
    sslProtocol: System.Security.Authentication.SslProtocols.Tls12,
    checkCertificateRevocation: true,
    remoteCertValidationCallback: (_, _, _, policyErrors) => policyErrors == System.Net.Security.SslPolicyErrors.None);

using var cluster = Cluster.Builder()
    .WithCredentials(
        username: "localhost",
        password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
    )
    .WithPort(
        port: 10350
    )
    .AddContactPoint(
        address: "localhost"
    )
    .WithSSL(
        sslOptions: options
    )
    .Build();

using var session = cluster.Connect();

  8. ve ExecuteAsynckullanarak PrepareAsync yeni bir veritabanı ve kapsayıcı oluşturun.

    var createKeyspace = await session.PrepareAsync("CREATE KEYSPACE IF NOT EXISTS cosmicworks WITH replication = {'class':'basicclass', 'replication_factor': 1};");
await session.ExecuteAsync(createKeyspace.Bind());

var createTable = await session.PrepareAsync("CREATE TABLE IF NOT EXISTS cosmicworks.products (id text PRIMARY KEY, name text)");
await session.ExecuteAsync(createTable.Bind());

  9. kullanarak ExecuteAsynctabloda yeni bir öğe oluşturun. Öğeye özellik atamak için kullanın Bind .

    var item = new
{
    id = "68719518371",
    name = "Kiama classic surfboard"
};

var createItem = await session.PrepareAsync("INSERT INTO cosmicworks.products (id, name) VALUES (?, ?)");

var createItemStatement = createItem.Bind(item.id, item.name);

await session.ExecuteAsync(createItemStatement);

  10. .NET uygulamasını çalıştırın.

    dotnet run

Önemli

Başlamadan önce Apache Gremlin API'sinde öykünücüde kaynaklarınızı oluşturmanız gerekir. adlı bir veritabanı ve adlı db1coll1bir kapsayıcı oluşturun. Aktarım hızı ayarları bu kılavuz için ilgisizdir ve istediğiniz kadar düşük olarak ayarlanabilir.

Bir .NET uygulamasından öykünücüye bağlanmak için Apache Gremlin .NET sürücüsünü kullanın.

  1. Boş bir klasörden başlayın.

  2. Yeni bir .NET konsol uygulaması oluşturma

    dotnet new console

  3. NuGet'ten Gremlin.Net paketi ekleyin.

    dotnet add package Gremlin.Net

  4. Program.cs dosyasını açın.

  5. Dosyadaki mevcut tüm içeriği silin.

  6. Ad alanı için Gremlin.Net.Driver bir using bloğu ekleyin.

    using Gremlin.Net.Driver;

  7. Öykünücünün GremlinServerGremlinClient kimlik bilgilerini kullanarak yeni bir ve örneği oluşturun.

    var server = new GremlinServer(
    hostname: "localhost",
    port: 8901,
    username: "/dbs/db1/colls/coll1",
    password: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
);

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

  8. kullanarak SubmitAsyncgrafiği temizleyin.

    await client.SubmitAsync(
    requestScript: "g.V().drop()"
);

  9. Belirtilen parametrelerle grafiğe yeni bir öğe eklemek için yeniden kullanın SubmitAsync .

    await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', prop_id).property('name', prop_name)",
    bindings: new Dictionary<string, object>
    {
        { "prop_id", "68719518371" },
        { "prop_name", "Kiama classic surfboard" }
    }
);

  10. .NET uygulamasını çalıştırın.

    dotnet run

Bir .NET uygulamasından öykünücüye bağlanmak için .NET için Azure Tablolar SDK'sını kullanın.

  1. Boş bir klasörden başlayın.

  2. Yeni bir .NET konsol uygulaması oluşturma

    dotnet new console

  3. NuGet'ten Azure.Data.Tables paketi ekleyin.

    dotnet add package Azure.Data.Tables

  4. Program.cs dosyasını açın.

  5. Dosyadaki mevcut tüm içeriği silin.

  6. Ad alanı için Azure.Data.Tables bir using bloğu ekleyin.

    using Azure.Data.Tables;

  7. Öykünücünün TableServiceClient kimlik bilgilerini kullanarak yeni bir örneği oluşturun.

    var serviceClient = new TableServiceClient(
    connectionString: "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;"
);

  8. Tablo adıyla yeni bir örneği TableClient oluşturmak için kullanınGetTableClient. Ardından kullanarak tablonun var CreateIfNotExistsAsyncolduğundan emin olun.

    var client = serviceClient.GetTableClient(
    tableName: "cosmicworksproducts"
);

await client.CreateIfNotExistsAsync();

  9. Öğeler için yeni record bir tür oluşturun.

    public record Product : Azure.Data.Tables.ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; init; }

    public Azure.ETag ETag { get; set; }

    public DateTimeOffset? Timestamp { get; set; }
}

  10. ve Replace modunu kullanarak UpsertEntityAsync tabloda yeni bir öğe oluşturun.

    var item = new Product
{
    RowKey = "68719518371",
    PartitionKey = "Surfboards",
    Name = "Kiama classic surfboard",
    Timestamp = DateTimeOffset.Now
};

await client.UpsertEntityAsync(
    entity: item,
    mode: TableUpdateMode.Replace
);

  11. .NET uygulamasını çalıştırın.

    dotnet run

GitHub Actions CI iş akışında öykünücüyü kullanma

Uygulamanızı otomatik olarak doğrulayan sürekli tümleştirme iş yükünü çalıştırmak için Azure Cosmos DB öykünücüsünün seçtiğiniz çerçeveden bir test paketiyle birlikte kullanılmasını sağlayın. Azure Cosmos DB öykünücüsü, GitHub Action'ın barındırılan windows-latest çalıştırıcılarının varyantına önceden yüklenmiştir.

.NET için yerleşik test sürücüsünü ve MSTest, NUnit veya XUnit gibi bir test çerçevesini kullanarak bir test paketi çalıştırın.

  1. Uygulamanız için birim test paketinin beklendiği gibi çalıştığını doğrulayın.

    dotnet test

  2. GitHub deponuzda adlı .github/workflows/ci.ymlbir dosyada yeni bir iş akışı oluşturun.

  3. PowerShell kullanarak Azure Cosmos DB öykünücüsünüzü başlatmak ve birim test paketinizi çalıştırmak için iş akışınıza bir iş ekleyin.

    name: Continuous Integration
on:
  push:
    branches:
      - main
jobs:
  unit_tests:
    name: Run .NET unit tests
    runs-on: windows-latest
    steps:
      - name: Checkout (GitHub)
        uses: actions/checkout@v3
      - name: Start Azure Cosmos DB emulator
        run: >-
          Write-Host "Launching Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator
      - name: Run .NET tests
        run: dotnet test

    Not

    Çeşitli bağımsız değişkenleri veya PowerShell komutlarını kullanarak komut satırından öykünücüyü başlatın. Daha fazla bilgi için bkz . öykünücü komut satırı bağımsız değişkenleri.

Sonraki adım

Öykünücünün sürüm notlarını gözden geçirin