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

  • Şunlara uygulanır: ✅ NoSQL

Öykünücünün yaygın bir kullanım örneği, uygulamalarınızı geliştirirken bir geliştirme veritabanı olarak kullanılmasıdır. Geliştirme için öykünücünün kullanılması, hizmet maliyetlerine neden olmadan Azure Cosmos DB gibi bir veritabanı için 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.

Prerequisites

Öykünücüyü yükle

Ö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 (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ızda kullanılabilir olduğundan emin olun.

    docker images

Başlamak için Microsoft Container Registry (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-emulator etiketini kullanarak Linux kapsayıcı görüntüsünü yerel Docker ana bilgisayarı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ızda kullanılabilir olduğundan 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şlat

İndirildikten sonra, belirttiğiniz API etkin durumdayken ö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:

    Description
    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.

    Linux sistemleri için şunu kullanın:

    docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

    Windows sistemleri için şunu kullanın:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250-10255:10250-10255"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

  2. Veri gezginine erişmek için https://localhost:8081/_explorer/index.html 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:

    Description
    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.

    Linux sistemleri için şunu kullanın:

    docker run \
    --publish 8081:8081 \
    --publish 10250:10250 \
    --env AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0 \
    --name linux-emulator \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

    Windows sistemleri için şunu kullanın:

    $parameters = @(
    "--publish", "8081:8081"
    "--publish", "10250:10250"
    "--env", "AZURE_COSMOS_EMULATOR_ENABLE_MONGODB_ENDPOINT=4.0"
    "--name", "windows-emulator"
    "--detach"
)
docker run @parameters mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb

  2. Veri gezginine erişmek için https://localhost:8081/_explorer/index.html 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 konteyner yolunda _explorer/emulator.pem bulunabilir. Sertifikayı çalışan kapsayıcıdan yerel makinenize indirmek için kullanın curl .

  1. Çalışan kapsayıcıdan sertifikayı alın.

    Linux sistemleri için şunu kullanın:

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

    Windows sistemleri için şunu kullanın:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

  2. İşletim sisteminiz için uygun komutu kullanarak sertifika paketini yeniden üretin.

    Debian tabanlı Linux sistemleri (örneğin, Ubuntu) için şunu kullanın:

    sudo update-ca-certificates

    Red Hat tabanlı Linux sistemleri (örneğin, CentOS, Fedora) için şunu kullanın:

    sudo update-ca-trust

    Windows sistemleri için şunu kullanın:

    certutil -f -addstore "Root" ~/emulatorcert.crt

    Daha ayrıntılı yönergeler için işletim sisteminize özgü belgelere bakın.

Öykünücü sertifikası, çalışan konteyner yolunda /_explorer/emulator.pem bulunabilir.

  1. Sertifikayı çalışan kapsayıcıdan yerel makinenize indirin.

    Linux sistemleri için şunu kullanın:

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

    Windows sistemleri için şunu kullanın:

    $parameters = @{
    Uri = 'https://localhost:8081/_explorer/emulator.pem'
    Method = 'GET'
    OutFile = 'emulatorcert.crt'
    SkipCertificateCheck = $True
}
Invoke-WebRequest @parameters

    Note

    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.

    Linux sistemleri için şunu kullanın:

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

    Windows sistemleri için şunu kullanın:

    $parameters = @{
    FilePath = 'emulatorcert.crt'
    CertStoreLocation = 'Cert:\CurrentUser\Root'
}
Import-Certificate @parameters

  3. Linux sistemleri için, Linux dağıtımınız için uygun komutu kullanarak sertifika paketini yeniden üretin.

    Debian tabanlı Linux sistemleri (örneğin, Ubuntu) için şunu kullanın:

    sudo update-ca-certificates

    Red Hat tabanlı Linux sistemleri (örneğin, CentOS, Fedora) için şunu kullanın:

    sudo update-ca-trust

    Daha ayrıntılı yönergeler için işletim sisteminize ö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.

.NET uygulamanızdan öykünücüye bağlanmak için Azure Cosmos DB API'sini NoSQL .NET SDK'sı ile 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 paketini ekleyin.

    dotnet add package Microsoft.Azure.Cosmos

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

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

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

    using Microsoft.Azure.Cosmos;

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

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

  8. CreateDatabaseIfNotExistsAsync ve CreateContainerIfNotExistsAsync kullanarak 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

    Warning

    SSL hatası alırsanız, uygulamanız için TLS/SSL'yi devre dışı bırakmanız gerekebilir. Bu durum genellikle kapsayıcıdaki Azure Cosmos DB öykünücüsünüzü kullanarak yerel makinenizde geliştiriyorsanız ve kapsayıcının SSL sertifikasını aktarmadıysanız oluşur. 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
);

Tip

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

.NET bir uygulamadan ö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 paketini ekleyin.

    dotnet add package MongoDB.Driver

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

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

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

    using MongoDB.Driver;

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

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

  8. GetDatabase ve GetCollection<> kullanarak veritabanı ve kapsayıcı edinin.

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

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

  9. XXX içinde InsertOneAsync kullanarak 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

.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 paketini ekleyin.

    dotnet add package CassandraCSharpDriver

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

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

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

    using Cassandra;

  7. Öykünücünün Cluster kimlik bilgilerini kullanarak yeni bir örnek 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. PrepareAsync ve ExecuteAsync kullanarak 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

Important

Başlamadan önce, Apache Gremlin API için emülatörde 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.

.NET bir uygulamadan ö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 paketini ekleyin.

    dotnet add package Gremlin.Net

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

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

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

    using Gremlin.Net.Driver;

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

    var server = new GremlinServer(
    hostname: "localhost",
    port: 65400,
    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. Grafiği SubmitAsync kullanarak 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

.NET uygulamasından öykünücüye bağlanmak 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 paketini ekleyin.

    dotnet add package Azure.Data.Tables

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

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

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

    using Azure.Data.Tables;

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

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

  8. GetTableClient kullanarak tablonun adıyla TableClient'in yeni bir örneğini oluşturun. Ardından, CreateIfNotExistsAsync kullanarak tablonun mevcut olduğundan emin olun.

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

await client.CreateIfNotExistsAsync();

  9. Öğeler için yeni bir record 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. UpsertEntityAsync ve Replace modunu kullanarak 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ü kullanma

Uygulamanızı otomatik olarak doğrulayan sürekli tümleştirme iş yükünü çalıştırmak için, seçtiğiniz çerçeveden bir test paketiyle Azure Cosmos DB öykünücüsü kullanın. Azure Cosmos DB emülatörü, GitHub Actions'ın barındırılan çalıştırıcılarının windows-latest 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çevesi 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 .github/workflows/ci.yml adlı bir dosyada yeni bir iş akışı oluşturun.

  3. PowerShell kullanarak Azure Cosmos DB öykünücüyü 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

    Note

    Ç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 öykünücü komut satırı parametrelerine bkz.

Sonraki adım

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

  • Last updated on